v3
latestOpenAPI 3.1.02026-08-0755220214.3 KBCreate
Creates a new agent in a project.
Query parameters
The name of the project to create the agent in.
Headers
Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.
Request body
The name of the agent. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.
URL-friendly agent slug. Can only contain lowercase letters, numbers and hyphens. Must be unique within the project.
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.
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.
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.
The timezone of the agent. Used to format system variables like {{system_time}}.
The voice ID to use.
The audio format of the agent.
The audio speed of the agent.
The background noise level of the agent.
The background noise type. Can be "office", "call-center", "coffee-shop", or null.
When true, the welcome message will be automatically generated and the welcome_message field will be ignored.
When false, the welcome message will not be interruptible by the user.
Number of seconds of inactivity before the conversation WebSocket is closed.
Message to play when the conversation starts. Can contain template variables like {{customer_name}}. Ignored when generate_welcome_message is true.
Instructions for the conversation. Can contain template variables like {{subject}}.
Variables that can be used in the welcome message and the system prompt.
Per-tool configuration overrides for built-in tools, keyed by built-in tool ID (e.g. tool_natural_conversation_ending). A built-in tool referenced in tools but absent from this map uses its default configuration.
Whether to have the no-input poke text be generated by AI.
Number of seconds of silence before sending a poke message. null disables the poke message.
The message to send after the specified silence. Ignored when generate_no_input_poke_text is true.
Seconds of silence before ending the conversation.
When true, the assistant will produce backchannel responses (e.g. "mm-hmm") while the user is speaking.
How aggressively the assistant produces backchannel responses. Only relevant when enable_assistant_backchannel is true.
ISO 639-1 language codes supported by the agent
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.
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.
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.
Push to talk mode. User must send mute/unmute messages to turn on/off listening to audio. Defaults to false.
The intelligence level of the agent. high uses a more capable model for more complex reasoning, while standard is optimized for lower latency.
These words, or short phrases, will be more accurately recognized by the agent.
Minimum number of words required to interrupt the assistant.
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.
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.
Voice activity detection prebuffer duration in milliseconds.
Minimum speech duration for voice activity detection in milliseconds.
Minimum silence duration for voice activity detection in milliseconds.
Voice activity detection threshold.
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.
Array of MCP server IDs to make available to the agent.
Names of observability integrations to enable for the agent. Each must be one of the supported providers.
Name of an external storage policy in the same project that conversation artifacts are delivered to. Requires zero data retention and cannot be combined with enable_redaction.
Response
Success response
The ID of the created agent.
The name of the created agent.