Skip to navigation

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.

Query parameters

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

Request

This endpoint expects an object.
namestringRequired

Deprecated alias of slug; agents have no separate display name. If both name and slug are provided, slug takes precedence and name is set to the same value. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.

slugstringOptional

URL-friendly agent slug, which also serves as the agent’s name. 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 stringsOptionalDefaults to []

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.
additional_voice_idslist of stringsOptionalDefaults to []

Additional voice IDs that, together with voice_id, form the agent’s voice set. Each conversation is assigned one voice from the set, chosen at random with equal probability. Must not include voice_id and must not contain duplicates.

audio_formatenumOptionalDefaults to pcm_44100
The audio format of the agent.
Allowed values:
audio_speeddoubleOptional0.5-1.5Defaults to 1.2
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.

is_welcome_message_interruptiblebooleanOptionalDefaults to true

When false, the welcome message will not be interruptible by the user.

websocket_timeout_secintegerOptional1-300Defaults to 60
Number of seconds of inactivity before the conversation WebSocket is closed.
listen_only_inbound_enabledbooleanOptionalDefaults to false
Play an uninterruptible welcome message on incoming calls, then transcribe the caller without responding. Silence timeout and call duration limits still apply.
listen_only_inbound_messagestring or nullOptional<=1000 characters

Welcome message for listen-only incoming calls. Can contain template variables like {{customer_name}}. Must be nonempty when listen_only_inbound_enabled is true. Replaces welcome_message for these calls, regardless of generate_welcome_message.

welcome_messagestring or nullOptional

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

system_promptstringOptionalDefaults to Today's date is {{system_date}} {{system_year}}. The day of week is {{system_weekday}}. The current time is {{system_time}}. The timezone for the current conversation is {{system_conversation_timezone}}. Use it only for date/time calculations. Do not infer location from it.

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

template_variablesmap from strings to objectsOptional

Template variables saved on the agent, keyed by snake_case variable name, for use in the welcome message and the system prompt. Each value is an object such as {"default_value": "Sarah"}, not a plain string. Leave a variable out to require every conversation to provide it. To set values for a single conversation, pass plain strings in that conversation’s template_variables instead.

toolslist of enums or stringsOptional

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

built_in_tool_configsobjectOptional

Configuration overrides for built-in tools, keyed by built-in tool ID: tool_natural_conversation_ending, tool_keypad_input, tool_web_search, or tool_choose_not_to_respond (the tool name prefixed with tool_; bare tool names such as natural_conversation_ending are rejected). Built-in tools not listed here use their default configuration.

taskslist of objectsOptional

Array of task objects with name and description fields.

generate_no_input_poke_textbooleanOptionalDefaults to false

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

no_input_poke_secinteger or nullOptional1-120

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.

no_input_end_conversation_secintegerOptional30-3600Defaults to 180
Seconds of silence before ending the conversation.
enable_assistant_backchannelbooleanOptionalDefaults to false

When true, the assistant will produce backchannel responses (e.g. “mm-hmm”) while the user is speaking.

assistant_backchannel_aggressivenessdoubleOptional0-1Defaults to 0.1

How aggressively the assistant produces backchannel responses. Only relevant when enable_assistant_backchannel is true.

data_retention_policyobjectOptional
Controls how long transcripts and audio recordings are retained before deletion.
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.

additional_languageslist of enumsOptionalDefaults to []

Array of additional ISO 639-1 language codes that the agent should be able to recognize and speak. Should not include default_language. When multilingual_mode is "auto", a maximum of 2 additional languages is allowed.

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). If "initial" the first turn user audio determines the language for the rest of the conversation.

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.

intelligence_levelenumOptionalDefaults to standard

The intelligence level of the agent. high uses a more capable model for more complex reasoning, while standard is optimized for lower latency.

Allowed values:
modelenum or stringOptional

The Phonic speech-to-speech model to generate with. Omit it to use the current default model.

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

Array of { word, pronunciation } entries. Words must be unique.

min_words_to_interruptintegerOptional1-10Defaults to 1
Minimum number of words required to interrupt the assistant.
turn_takingenumOptionalDefaults to standard

How long the agent waits after the user stops speaking before taking its turn. "eager" responds fastest; "very_patient" waits the longest.

max_conversation_duration_secintegerOptional1-7200Defaults to 7200
Maximum duration of a conversation in seconds. When the limit is reached, the conversation is ended.
detect_voicemail_tonebooleanOptionalDefaults to true
Whether to listen for the beep at the end of a voicemail greeting and tell the agent when it hears one. Runs during the first 45 seconds of outbound phone calls and WebSocket conversations, and never on inbound phone calls.
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.

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.

enable_redactionbooleanOptionalDefaults to false

When true, PII and PHI are redacted from text transcripts (e.g. replaced with tags like [PHONE]) and bleeped from audio recordings after the conversation ends.

redaction_entitieslist of enums or nullOptional

The types of PII and PHI to redact when enable_redaction is true. null redacts all PII and PHI. Must contain at least one item when not null.

enable_watermarkingbooleanOptionalDefaults to false

When true, an inaudible watermark is embedded in the audio the agent generates.

mcp_server_idslist of stringsOptionalDefaults to []
Array of MCP server IDs to make available to the agent.
observability_integrationslist of enumsOptionalDefaults to []
Names of observability integrations to enable for the agent. Each must be one of the supported providers.
Allowed values:
external_storage_policystring or nullOptional
Name of an external storage policy in the same project that conversation artifacts are delivered to. Requires zero data retention.
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 enumsOptionalDefaults to ["en"]Deprecated

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.

phonic_modelenum or stringOptionalDeprecated

The Phonic speech-to-speech model to generate with. This field is deprecated. Use model instead.

vad_prebuffer_duration_msintegerOptional0-2000Deprecated

Voice activity detection prebuffer duration in milliseconds. Deprecated. Stored on the agent but ignored at runtime. Use turn_taking, or send VAD settings in the conversation config instead.

vad_min_speech_duration_msintegerOptional0-1500Deprecated

Minimum speech duration for voice activity detection in milliseconds. Deprecated. Stored on the agent but ignored at runtime. Use turn_taking, or send VAD settings in the conversation config instead.

vad_min_silence_duration_msintegerOptional0-1500Deprecated

Minimum silence duration for voice activity detection in milliseconds. Deprecated. Stored on the agent but ignored at runtime. Use turn_taking, or send VAD settings in the conversation config instead.

vad_thresholddoubleOptional0.2-0.8Deprecated

Voice activity detection threshold. Deprecated. Stored on the agent but ignored at runtime. Use turn_taking, or send VAD settings in the conversation config instead.

Response

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

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
500
Internal Server Error