API ReferenceAgents

Update

Updates an agent by name or ID.

Authentication

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

Path parameters

nameOrIdstringRequired
The name or the ID of the agent to update.

Query parameters

projectstringOptionalDefaults to main

The name of the project containing the agent. Only used when nameOrId is a name.

Request

This endpoint expects an object.
namestringOptional
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 anymore. When set to `"assign-automatically"`, the agent will be assigned a random phone number if it doesn't have one yet. If the agent already has a phone number, `"assign-automatically"` has no effect. 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_idstringOptional
The voice ID to use.
audio_formatenumOptional
The audio format of the agent.
Allowed values:
audio_speeddoubleOptional0.5-1.5
The audio speed of the agent.
background_noise_leveldoubleOptional0-0.25
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_messagebooleanOptional

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

welcome_messagestringOptional

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

system_promptstringOptional

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_textstringOptional
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-1

Float between 0.0 and 1.0 representing the percentage of inbound calls handled by Agent. 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.

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
successboolean
Whether the agent was updated successfully.

Errors