API ReferenceAgents

Upsert

Upserts an agent by name. If an agent with the same name already exists, it will be updated. Otherwise, it will be created.

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 containing the agent.

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.
additional_languageslist of enumsOptional

Array of additional ISO 639-1 language codes that the agent should be able to recognize and speak. Should not include default_language.

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_noiseenumOptional

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

Allowed values:
background_noise_leveldoubleOptional0-0.25Defaults to 0
The background noise level of the agent.
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 to get configuration options.

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.

default_languageenumOptional

ISO 639-1 language code that sets the agent’s default language to recognize and speak. Welcome message and no input poke text should be in this language.

generate_no_input_poke_textbooleanOptionalDefaults to false

Whether to have the no-input poke text be generated by AI.

generate_welcome_messagebooleanOptionalDefaults to false

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

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.

min_words_to_interruptintegerOptional1-10Defaults to 1
Minimum number of words required to interrupt the assistant.
multilingual_modeenumOptionalDefaults to request

If "auto", each user audio is automatically identified for the language to respond in. If "request", user must request to change language (recommended).

Allowed values:
no_input_end_conversation_secintegerOptionalDefaults to 180
Seconds of silence before ending the conversation.
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. Ignored when generate_no_input_poke_text is true.

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:
push_to_talkbooleanOptionalDefaults to false

Push to talk mode. User must send mute/unmute messages to turn on/off listening to audio. Defaults to false.

system_promptstringOptionalDefaults to Respond in 1-2 sentences.

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

taskslist of objectsOptional

Array of task objects with name and description fields.

template_variablesmap from strings to objectsOptional
Variables that can be used in the welcome message and the system prompt.
timezonestringOptional

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

toolslist of enums or stringsOptional

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

vad_min_silence_duration_msintegerOptional0-1500Defaults to 800
Minimum silence duration for voice activity detection in milliseconds.
vad_min_speech_duration_msintegerOptional0-1500Defaults to 50
Minimum speech duration for voice activity detection in milliseconds.
vad_prebuffer_duration_msintegerOptional0-2000Defaults to 500
Voice activity detection prebuffer duration in milliseconds.
vad_thresholddoubleOptional0.2-0.8Defaults to 0.38
Voice activity detection threshold.
voice_idstringOptionalDefaults to sabrina
The voice ID to use.
welcome_messagestringOptionalDefaults to

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

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.

languageslist of enumsOptionalDeprecated

Array of ISO 639-1 language codes that the agent should be able to recognize. This field is deprecated. Use default_language and additional_languages instead.

Response

Success response
agentobject
insertedboolean
Whether the agent was inserted.
updatedboolean
Whether the agent was updated.

Errors

400
Bad Request Error
404
Not Found Error