API ReferenceAgents

Create

Creates a new agent in a project.

Authentication

AuthorizationBearer
Bearer authentication header of the form `Bearer <PHONIC_API_KEY>`. Manage your API keys [here](https://phonic.co/api-keys).

Query parameters

projectstringOptionalDefaults to main
The name of the project to create the agent in.

Request

This endpoint expects an object.
namestringRequired
The name of the agent. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.
phone_numberenum or nullOptional

When set to null, the agent will not be associated with a phone number. When set to "assign-automatically", the agent will be assigned a random phone number. When set to "custom", you must provide custom_phone_numbers.

Allowed values:
custom_phone_numberslist of stringsOptional

Array of custom phone numbers in E.164 format (e.g., [“+1234567890”, “+0987654321”]). The agent will be able to receive phone calls on any of these numbers. Required when phone_number is set to "custom". All phone numbers must be unique.

timezonestringOptional

The timezone of the agent. Used to format system variables like {{system_time}}.

voice_idstringOptionalDefaults to grant
The voice ID to use.
audio_formatenumOptionalDefaults to pcm_44100
The audio format of the agent.
Allowed values:
audio_speeddoubleOptional0.5-1.5Defaults to 1
The audio speed of the agent.
background_noise_leveldoubleOptional0-0.25Defaults to 0
The background noise level of the agent.
background_noiseenumOptional

The background noise type. Can be “office”, “call-center”, “coffee-shop”, or null.

Allowed values:
generate_welcome_messagebooleanOptionalDefaults to false

When true, the welcome message will be automatically generated and the welcome_message field will be ignored.

welcome_messagestringOptionalDefaults to

Message to play when the conversation starts. Can contain template variables like {{customer_name}}. Ignored when generate_welcome_message is true.

system_promptstringOptionalDefaults to Respond in 1-2 sentences.

Instructions for the conversation. Can contain template variables like {{subject}}.

template_variablesmap from strings to objectsOptional
Variables that can be used in the welcome message and the system prompt.
toolslist of enums or stringsOptional

Array of built-in or custom tool names to use.

taskslist of objectsOptional

Array of task objects with name and description fields.

no_input_poke_secinteger or nullOptionalDefaults to 180

Number of seconds of silence before sending a poke message. null disables the poke message.

no_input_poke_textstringOptionalDefaults to Are you still there?
The message to send after the specified silence.
no_input_end_conversation_secintegerOptionalDefaults to 180
Seconds of silence before ending the conversation.
languageslist of enumsOptional

Array of ISO 639-1 language codes that the agent should be able to recognize

boosted_keywordslist of stringsOptional
These words, or short phrases, will be more accurately recognized by the agent.
configuration_endpointobject or nullOptional

When not null, at the beginning of the conversation the agent will make a POST request to this endpoint when to get configuration options.

inbound_rolloutdoubleOptional0-1Defaults to 1

Float between 0.0 and 1.0 representing the percentage of inbound calls handled by Agent. Defaults to 1.0. Requires phone_number to be set when less than 1.0.

inbound_rollout_forward_phone_numberstring or nullOptional

E.164 formatted phone number where non-agent calls will be forwarded. Required when inbound_rollout < 1.0, must be null when inbound_rollout = 1.0. Defaults to null.

custom_phone_numberstring or nullOptionalDeprecated

The custom phone number to use for the agent in E.164 format (e.g., +1234567890). This field is deprecated. Use custom_phone_numbers instead.

Response

Success response
idstring
The ID of the created agent.
namestring
The name of the created agent.

Errors