CallFluent API: Agent Services

The Agent Services API allows you to create, configure, and manage AI-powered voice agents within your CallFluent workspace. Agents can handle inbound/outbound calls, execute actions (email, SMS, webhooks), and integrate with third-party services.

Base URL

All requests must be sent to:
https://api.callfluent.ai/api

Authentication

Include your API key in the Authorization header:

Authorization: Bearer {api_key}  

---

Agent Endpoints

1. Get Twilio Number List

GET /agent/number-list/{id}/{agentType}

Retrieves the Twilio number list.

Header

Authorization: Bearer {api_key}  

Path Parameters

Field	Type	Required	Description	Example
id	number	true	Workspace ID	1
agentType	string	true	outbound or inbound	outbound

Example Request

curl -X GET https://api.callfluent.ai/api/agent/number-list/1/outbound \
  -H "Authorization: Bearer {api_key}"

Response

• Example Success

status code: 200: workspace list

{ status: true, data: number_list, agentNumMap: {used_number: used_avatar_url, …}}

number_list: [
{number: twlio_number, sid: twilio_sid, type: “twilio/verified”}
]

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 403 (Permission Error) – Permission error.

{ 
        status: false,
        msg: "Your account doesn't have the permission to access that page."
}

---

2. Create a New Agent

POST /agent/create

Creates a new voice agent with customizable settings.

Header

Authorization: Bearer {api_key}  

Request Body (agentPayload)

Field	Type	Required	Description	Example
workspaceId	number	true	Workspace ID	1
format	string	true	outbound/inbound	outbound
timezone	string	true	Agent timezone	UTC+00:00
name	string	true	Agent name	Sales assistant
avatar	string	XX	Public image URL/image’s base64	https://...
lang	string	true	Value of language list	en
voice	string	true	Value of workspace voice	alloy
phone_number	string	true (outbound) false (inbound)	Agent phone number	+123456789
welcome_msg_flag	boolean	false	Turn on/off welcome message	true
welcome_msg	string	false	Turn on/off the welcome message	How are you today?
welcome_msg_delay	number	false	Wait time (in seconds) before playing the welcome message	3
call_recording	boolean	false	Enable call recording	true
blocked_phone_types	string	false	Block phone type list	1,2,3
enable_voice_mail	boolean	false	Enable machine detection	true
voice_mail_mode	number	false	1. Leave a voice message. 2. hang up the call	1
voice_mail_text	string	false	1. Leave a voice message. 2. Hang up the call	Please try again.
machine_detection_timeout	number	false	Twilio machine detection timeout	10
openai_model	string	false	OpenAI model name (only available when openAI key is valid)	gpt-4o
answer_creativity	number	false	OpenAI temperature (0–10)	3
context_max_tokens	number	false	OpenAI prompt max token count	350
speech_stop_sensitivity	number	false	Word count that stops the agent’s speech (0-10)	5
answer_length	number	false	Limit the maximum no. of words (approximatively) per answer	25
silence_message_delay	number	false	Trigger the “are you there?” message after X seconds	10
silence_end_call	number	false	End the call if there is no sound for XX seconds	20
utterance_detection	number	false	How long to wait before an utterance ends (min 500ms)	1000
transcribe_filler_words	boolean	false	Transcribe words like “hmm” or “uhm”	true
agent_type	string	true	Agent type	sales
background	string	true	Agent’s background	You are a support agent.
goal	string	true	Agent’s goal	Support clients
tone	string	true	Agent’s tone	Professional
instructions	string	true	Agent’s instructions
script_option	boolean	false	Enable agent’s script	true
script	text	false	Agent’s script	Enable the agent’s script
background_sound	string	false	Background noise (only for browser call)	office-ambience.wav

Example Request

curl -X POST https://api.callfluent.ai/api/agent/create \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": 1,
    "format": "outbound",
    "name": "Sales Bot",
    "voice": "alloy",
    "phone_number": "+123456789",
    "agent_type": "sales",
    "background": "You are a sales agent.",
    "goal": "Close deals."
  }'

Response

• Example Success

status code: 200: workspace list

{status: true, data: new_agent }

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 400 (Bad Request) – Agent limit reached.

{ 
        status: false,
        msg: "You have reached limit.",
}

---

3. Get All Agents in Workspace

GET /agent/get-all/{workspaceId}

Retrieves the agents’ list in a workspace.

Header

Authorization: Bearer {api_key}  

Path Parameters

Field	Type	Required	Description	Example
workspaceId	number	true	Workspace ID	1

Response

• Example Success

status code: 200: workspace list

{"status": true, "data": "agent_list" }

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 403 (Permission Error) – Permission error.

{ 
        status: false,
        msg: "Your account doesn't have the permission to access that page."
}

---

4. Get Agent Details

GET /agent/get-one/{agentId}

Retrieves details for a specific agent.

Header

Authorization: Bearer {api_key}  

Path Parameters

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1

Response

• Example Success

status code: 200: workspace list

{
    status: true,
    data: {
        agent,
        files,
        totalCalls,
        averageDuration
    }
}

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 403 (Permission Error) – Permission error.

{ 
        status: false,
        msg: "Your account doesn't have the permission to access that page."
}

---

5. Delete an Agent

DELETE /agent/delete/{agentId}

Deletes a specific agent.

Header

Authorization: Bearer {api_key}  

Path Parameters

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	11

Response

• Example Success

status code: 200: workspace list

{
    status: true,
    data: {
        agent,
        files,
        totalCalls,
        averageDuration
    }
}

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 403 (Permission Error) – Permission error.

{ 
        status: false,
        msg: "Your account doesn't have the permission to access that page."
}

---

4. Get Agent Details

GET /agent/get-one/{agentId}

Retrieves details for a specific agent.

Header

Authorization: Bearer {api_key}  

Path Parameters

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1

Response

• Example Success

status code: 200: workspace list

{
    status: true,
    data: {
        agent,
        files,
        totalCalls,
        averageDuration
    }
}

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 403 (Permission Error) – Permission error.

{ 
        status: false,
        msg: "Your account doesn't have the permission to access that page."
}

---

4. Get Agent Details

GET /agent/get-one/{agentId}

Retrieves details for a specific agent.

Header

Authorization: Bearer {api_key}  

Path Parameters

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1

Response

• Example Success

status code: 200: workspace list

{
    status: true,
    data: {
        agent,
        files,
        totalCalls,
        averageDuration
    }
}

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 403 (Permission Error) – Permission error.

{ 
        status: false,
        msg: "Your account doesn't have the permission to access that page."
}

---

4. Get Agent Details

GET /agent/get-one/{agentId}

Retrieves details for a specific agent.

Header

Authorization: Bearer {api_key}  

Path Parameters

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1

Response

• Example Success

status code: 200: workspace list

{
    status: true,
    data: {
        agent,
        files,
        totalCalls,
        averageDuration
    }
}

Errors

• 500 (Server Error) – Server error.

{status: false, error: error_message}

• 403 (Permission Error) – Permission error.

{ 
        status: false,
        msg: "Your account doesn't have the permission to access that page."
}

---

5. Update an Agent

PUT /agent/update/{id}

Updates agent settings (same fields as POST /agent/create).

Path Parameters

Field	Type	Required	Description	Example
id	number	✅	Agent ID	14

Response (Success – 200)

{ "status": true, "data": "updated_agent" }

---

6. Delete an Agent

DELETE /agent/delete/{agentId}

Permanently deletes an agent.

Path Parameters

Field	Type	Required	Description	Example
agentId	number	✅	Agent ID	11

Response (Success – 200)

{ "status": true, "data": "agent_list" }

---

7. Agent Actions (Webhooks, Email, SMS, etc.)

Endpoints for configuring agent actions:

• POST /agent/create-action – Create actions (email, SMS, forwarding).
• PUT /agent/update-action/{actionId} – Update actions.
• DELETE /agent/delete-action/{actionId} – Remove actions.

Supported Action Types

Type	Key	Example Use Case
Send Email	sendEmail	Follow-up emails
Call Forwarding	callForwarding	Transfer to human
SMS	sms	Text notifications
Webhook	webhook	Zapier integrations
Data Collection	dataCollection	Capture user info
Calendar Booking	ghl_calendar	Schedule meetings

---

Conclusion

This covers all Agent Services API endpoints. For workspace management, refer to the Workspace API Documentation.

Let me know if you need further enhancements! 🚀