Home
/
Blog
/
Agent Services

Agent Services

Published

Jul 3, 2025

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.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

{ 
        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	`outboun`d/`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.

server error: status code: 500

{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.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

{ 
        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.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

{ 
        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_list }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

6. Get an Agent’s Call History

GET: /agent/{agentId}/calls

Gets an agent’s call history.

Header

Authorization: Bearer {api_key}

Path Parameters

Field	Type	Required	Description	Example
`agentId`	number	true	Agent ID	`1`

Query Parameters

Field	Type	Required	Description	Example
`page`	number	false	Page number	`1`

Response

Example Success

status code: 200: workspace list

{
    status: true,
    data: calls
}

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

7. Update an Agent

PUT: /agent/update/{id}

Updates an agent.

Header

Authorization: Bearer {api_key}

Path Parameters

Field	Type	Required	Description	Example
`Id`	number	true	agent ID	`14`

Request Body

{
	Payload: agentPayload
}

agentPayload

Field	Type	Required	Description	Example
`workspaceId`	number	true	Workspace ID	`1`
`format`	string	true	`outboun`d/`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`

Response

Example Success

status code: 200: updated agent

{ status: true, data: updated_agent }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

8. Upload an Agent’s Knowledge Base File

PUT: /agent/knowledge/{id}

Upload an agent’s knowledge base file.

Header

Authorization: Bearer {api_key}

Path Parameters

Field	Type	Required	Description	Example
`agentId`	number	true	Agent ID	`1`

Request Body

Field	Type	Required	Description
`files`	binary	true	The file to be uploaded (Content-Type: multipart/form-data)

Response

Example Success

status code: 200: updated agent

{ status: true, data: agent_list }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

9. Delete an Agent’s Knowledge Base File

DELETE: /agent/knowledge/{id}

Deletes an agent’s knowledge base file.

Header

Authorization: Bearer {api_key}

Path Parameters

Field	Type	Required	Description	Example
`id`	number	true	Knowledge file ID	`11`

Response

Example Success

status code: 200: workspace list

{ status: true, data: agent_list }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

10. Delete an Agent’s Call

DELETE: /agent/delete-call/{call_id}

Deletes an agent’s call.

Header

Authorization: Bearer {api_key}

Path Parameters

Field	Type	Required	Description	Example
`call_id`	number	true	Call ID	`11`

Response

Example Success

status code: 200: workspace list

{ status: true, data: agent_list }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

11. Hang Up an In-Progress Twilio Call

POST: /agent/hangup-call

Hangs up an in-progress Twilio call.

Header

Authorization: Bearer {api_key}

Request Body

Field	Type	Required	Description	Example
`callid`	number	true	Call ID	`1`

Response

Example Success

status code: 200: updated agent

{ status: true, data: agent_list }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

12. Create an Agent’s Custom Fields

PUT: /agent/custom-field/{id}

Creates an agent’s custom fields.

Header

Authorization: Bearer {api_key}

Path Parameters

Field	Type	Required	Description	Example
`id`	number	true	Agent ID	`1`

Body

{
	data: custom_field
}

custom_field

Field	Type	Required	Description	Example
`id`	string	create: false update: true	Field ID	d7d6946a-d90a-438e-954f-08cb5950d680
`name`	string	true	Field name	name
`label`	string	true	Field description	Call’s name

Response

Example Success

status code: 200: workspace list

{ status: true, data: updated_custom_field }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

13. Delete an Agent’s Custom Fields

DELETE: /agent/remove-custom-fields/{agent_id}/{field_id}

Deletes an agent’s custom fields.

Header

Authorization: Bearer {api_key}

Path Parameters

Field	Type	Required	Description	Example
`agent_id`	number	true	Agent ID	`1`
field_id	number	true	Field ID	d7d6946a-d90a-438e-954f-08cb5950d680

Response

Example Success

status code: 200: updated custom field

{ status: true, data: updated_custom_field }

Errors

500 (Server Error) – Server error.

server error: status code: 500

{status: false, error: error_message}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

14. Create a New Agent Action

POST: /agent/create-action

Creates a new action for a specified agent.

Header

Authorization: Bearer {api_key}

Request Body

{
	payload: actionPayload
}

actionPayload Types

1. Send Email

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	sendEmail
name	string	true	Action name	Send email action
instruction	string	true	Instruction to trigger action	This is a test email
content	string	true	Email content	This is test email
subject	string	true	Email subject	Introduction email

2. Call Forwarding

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	callForwarding
name	string	true	Action name	Call forwarding action
instruction	string	true	Instruction to trigger action	Forward to the phone number
forwardNumber	string	true	Forward to phone number	+1XXXXXXXX

3. Send Text Message

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	sms
name	string	true	Action name	Sms action
instruction	string	true	Instruction to trigger action	Trigger when user wants sms
content	string	true	SMS content	It is test sms

4. Webhook / Zapier

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	webhook
name	string	true	Action name	webhook action
webhook_url	string	true	Webhook URL	https://webhook-test/XXX
fields	string	true	JSON string of custom fields	`[{"value":"dev1","label":"dev1"},{"value":"email","label":"email"}]`

5. Data Collection

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	dataCollection
name	string	true	Action name	Data collection action
instruction	string	true	Instruction to trigger action	Trigger when user shares his name
collectField	string	true	Field value of custom field	email

6. Email Data Push

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	email_push
name	string	true	Action name	Email push action
target_email	string	true	Email address to push data	[email protected]
subject	string	true	Email subject	Call summary
fields	string	true	JSON string of custom fields	`[{"value":"dev1","label":"dev1"},{"value":"email","label":"email"}]`

7. GHL Calendar

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	ghl_calendar
name	string	true	Action name	GHL meeting action
ghlCalendarId	string	true	GHL calendar ID	B6blCXXXXX
calendarPeriod	string	true	Date range for scheduling	1week
instruction	string	true	Instruction to trigger action	Trigger when user want to schedule call

8. Google Calendar

Field	Type	Required	Description	Example
agentId	number	true	Agent ID	1
actionType	string	true	Action type	google_calendar
name	string	true	Action name	GHL meeting action
google_title	string	true	Google meeting title	Introduction meeting
google_description	string	false	Google meeting description
instruction	string	true	Instruction to trigger action	Trigger when user want to schedule call
calendarPeriod	string	true	Date range for scheduling	1week
google_duration	string	true	Meeting duration	30 mins

Response

Example Success

status code: 200: created action

{ 
  status: true, 
  data: created_action 
}

Errors

500 (Server Error) – Server error.

server error: status code: 500

{ 
  status: false, 
  error: error_message 
}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

15. Update an Agent Action

POST: /agent/update-action/{actionId}

Updates an existing action for a specified agent.

Header

Authorization: Bearer {api_key}

Path Parameter

Field	Type	Required	Description	Example
actionId	number	true	Action ID	1

Request Body

actionPayload:

actionPayload Types

1. Send Email

Field	Type	Required	Description	Example
actionType	string	true	Action type	sendEmail
name	string	true	Action name	Send email action
instruction	string	true	Instruction to trigger action	Trigger when user asks to send email
content	string	true	Email content	This is test email
subject	string	true	Email subject	Introduction email

2. Call Forwarding

Field	Type	Required	Description	Example
actionType	string	true	Action type	callForwarding
name	string	true	Action name	Call forwarding action
instruction	string	true	Instruction to trigger action	Trigger when user want to connect with a manager
forwardNumber	string	true	Forward to phone number	+1XXXXXXXX

3. Send Text Message

Field	Type	Required	Description	Example
actionType	string	true	Action type	sms
name	string	true	Action name	Sms action
instruction	string	true	Instruction to trigger action	Trigger when user wants sms
content	string	true	SMS content	It is a test SMS

4. Webhook / Zapier

Field	Type	Required	Description	Example
actionType	string	true	Action type	webhook
name	string	true	Action name	webhook action
webhook_url	string	true	Webhook URL	https://webhook-test/XXX
fields	string	true	JSON string of custom fields	`[{"value":"dev1","label":"dev1"},{"value":"email","label":"email"}]`

5. Data Collection

Field	Type	Required	Description	Example
actionType	string	true	Action type	dataCollection
name	string	true	Action name	Data collection action
instruction	string	true	Instruction to trigger action	Trigger when user shares his name
collectField	string	true	Field value of custom field	email

6. Email Data Push

Field	Type	Required	Description	Example
actionType	string	true	Action type	email_push
name	string	true	Action name	Email push action
target_email	string	true	Email address to push data	[email protected]
subject	string	true	Email subject	Call summary
fields	string	true	JSON string of custom fields	`[{"value":"dev1","label":"dev1"},{"value":"email","label":"email"}]`

7. GHL Calendar

Field	Type	Required	Description	Example
actionType	string	true	Action type	ghl_calendar
name	string	true	Action name	GHL meeting action
ghlCalendarId	string	true	GHL calendar ID	B6blCXXXXX
calendarPeriod	string	true	Date range for scheduling	1week
instruction	string	true	Instruction to trigger action	Trigger when user want to schedule call

8. Google Calendar

Field	Type	Required	Description	Example
actionType	string	true	Action type	google_calendar
name	string	true	Action name	GHL meeting action
google_title	string	true	Google meeting title	Introduction meeting
google_description	string	false	Google meeting description
instruction	string	true	Instruction to trigger action	Trigger when user want to schedule call
calendarPeriod	string	true	Date range for scheduling	1week
google_duration	string	true	Meeting duration	30 mins

Response

Example Success

Status code: 200: created action

{ 
  status: true, 
  data: created_action 
}

Errors

500 (Server Error) – Server error.

server error: status code: 500

{ 
  status: false, 
  error: error_message 
}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

16. Delete an Agent Action

DELETE: /agent/delete-action/{actionId}

Deletes an existing action for a specified agent.

Header

Authorization: Bearer {api_key}

Path Parameter

Field	Type	Required	Description	Example
actionId	number	true	Action ID	1

Response

Example Success

Status code: 200: deleted action

{ 
  status: true, 
  data: deleted_action 
}

Errors

500 (Server Error) – Server error.

server error: status code: 500

{ 
  status: false, 
  error: error_message 
}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

17. Set Agent’s CORS Origin

PUT: /agent/webhook-cors-origin/{agent_id}

Sets the agent’s CORS origin.

Header

Authorization: Bearer {api_key}

Path Parameter

Field	Type	Required	Description	Example
agent_id	number	true	Agent ID	1

Request Body

{
	data: webhookPayload
}

webhookPayload

Field	Type	Required	Description	Example
has_webhook_cors_origin	boolean	true	Enable CORS origin	true
webhook_cors_origin	array	true	Domains	[“https://google.com“, “https://yahoo.com“]

Response

Example Success

Status code: 200: updated webhook

{ 
  status: true, 
  data: updated_webhook 
}

Errors

500 (Server Error) – Server error.

server error: status code: 500

{ 
  status: false, 
  error: error_message 
}

403 (Permission Error) – Permission error.

permission error: status code: 403

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

Conclusion

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

API docs

AI voice agents

Technical concepts

Table of Contents

Agent Services

Published

Base URL

Authentication

Agent Endpoints

1. Get Twilio Number List

Header

Path Parameters

Example Request

Response

Errors

2. Create a New Agent

Header

Request Body (agentPayload)

Example Request

Response

Errors

3. Get All Agents in Workspace

Header

Path Parameters

Response

Errors

4. Get Agent Details

Header

Path Parameters

Response

Errors

5. Delete an Agent

Header

Path Parameters

Response

Errors

6. Get an Agent’s Call History

Header

Path Parameters

Query Parameters

Response

Errors

7. Update an Agent

Header

Path Parameters

Request Body

agentPayload

Response

Errors

8. Upload an Agent’s Knowledge Base File

Header

Path Parameters

Request Body

Response

Errors

9. Delete an Agent’s Knowledge Base File

Header

Path Parameters

Response

Errors

10. Delete an Agent’s Call

Header

Path Parameters

Response

Errors

11. Hang Up an In-Progress Twilio Call

Header

Request Body

Response

Errors

12. Create an Agent’s Custom Fields

Header

Path Parameters

Body

custom_field

Response

Errors

13. Delete an Agent’s Custom Fields

Header

Path Parameters

Request Body (`agentPayload`)