Create
Authentication
Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.
Query parameters
Request
The name of the tool. Must be snake_case and unique within the organization.
The type of tool. Each type accepts only its own fields, and a field from another type is rejected with a 400 error. Most execution flags are for custom_webhook and custom_websocket tools only. built_in_transfer_to_agent accepts only require_speech_before_tool_call, built_in_transfer_to_phone_number accepts require_speech_before_tool_call and uninterruptible, and the built_in_natural_conversation_ending, built_in_keypad_input, and built_in_choose_not_to_respond types accept none of them. Leave out any field your type doesn’t accept; the field’s presence is rejected, so sending it as false or null also fails. See which tool types accept each flag.
Mode of operation. Only custom_webhook and custom_websocket tools can be async; every other type must be sync. Optional for built_in_natural_conversation_ending, built_in_keypad_input, and built_in_choose_not_to_respond tools, where it defaults to sync.
The tool’s parameters, either as a flat array of parameter definitions or as a raw JSON Schema object (use the object form for nested parameters). When sending an array:
- For
custom_webhooktools with POST method, each parameter must include alocationfield. - For
custom_webhooktools with GET method,locationdefaults to"query_string"if not specified. - For
custom_websocket,built_in_transfer_to_phone_number, andbuilt_in_transfer_to_agenttools,locationmust not be specified. parameter_locationsmust not be sent, since placement is carried inline on each parameter. When sending a JSON Schema object,custom_webhooktools supply parameter placement inparameter_locationsinstead. Tools that cannot have parameters (custom_contextand thebuilt_in_*types) must send an empty array or omit the field.
Where each top-level parameter is sent in the webhook request, as a map from parameter name to location. Only for custom_webhook tools whose parameters are a raw JSON Schema object.
Every key must name a top-level parameter. For POST webhooks, every parameter needs an entry. For GET webhooks, entries default to "query_string" and "request_body" is not allowed.
Required for webhook tools. Must be a publicly routable HTTPS URL without embedded credentials. May contain {name} placeholders in the path or query (not the scheme, host, port, or credentials), each filled by a required parameter with location "url_path".
A SIP destination to transfer calls to instead of a phone number. Cannot be set together with phone_number, so phone_number must be null when sip is set. Only available for built_in_transfer_to_phone_number tools.
DTMF digits to send after the transfer connects (e.g., “1234”). Defaults to null. Ignored when dynamic_dtmf is true.
Fixed line the agent speaks into the bridged call once the transfer connects. Defaults to null, meaning no announcement. Must be null when keep_listening is false, since Phonic drops out of the call and has no line to speak it on. Only available for built_in_transfer_to_phone_number tools.
When true, the agent determines the DTMF digits at call time (and may choose to send none); the static dtmf is ignored.
When true, Phonic will transfer the call using the agent’s phone number. When false, Phonic will transfer the call using the phone number of the party to whom the agent is connected. This is only available for built_in_transfer_to_phone_number tools.
When true, Phonic will listen in and tell the user if the transfer hits voicemail. This is only available for built_in_transfer_to_phone_number tools when use_agent_phone_number is true.
When true, Phonic bridges the transfer and stays on the call. When false, Phonic drops out once the transfer connects, which requires use_agent_phone_number and detect_voicemail to be false and post_transfer_message to be null. Without DTMF the call is handed off with a SIP REFER; with DTMF (static or dynamic) Phonic bridges the call to send the digits and then detaches, leaving the two parties connected. Only available for built_in_transfer_to_phone_number tools. Defaults to the value of use_agent_phone_number.
What happens when the transfer target does not answer before the ring timeout. return_to_assistant hands control back to the agent. keep_retrying keeps the caller on the line and re-dials the target until it answers, the caller hangs up, or a retry cap is reached, then returns to the assistant. keep_retrying only applies to bridged transfers, so it cannot be used when keep_listening is false. Only available for built_in_transfer_to_phone_number tools.
Array of agent names that the LLM can choose from when transferring. Required for built_in_transfer_to_agent tools. All agents must exist in the same project as the tool.
When true, forces the agent to speak before executing the tool. Available for custom_webhook, custom_websocket, custom_context, built_in_transfer_to_phone_number, and built_in_transfer_to_agent tools. The built_in_natural_conversation_ending and built_in_keypad_input types use speech_before_tool_call instead, and built_in_choose_not_to_respond takes neither. Omit it for those three types; sending it, even as false, returns a 400 error.
For built_in_natural_conversation_ending and built_in_keypad_input tools. Whether the agent must speak before calling the tool (“required”), the model decides (“optional”), or the agent must stay silent (“suppressed”). Not used by other tool types.
For built_in_choose_not_to_respond tools. Number of seconds to wait after the tool fires before the agent speaks a follow-up if the user stays silent. When null, the agent stays silent (default). Not used by other tool types.
If true, the agent will wait to finish speaking before executing the tool. This is only available for custom_webhook and custom_websocket tools. Omit it for every other tool type, including built_in_transfer_to_agent and built_in_transfer_to_phone_number; sending it, even as false, returns a 400 error.
When true, forbids the agent from speaking after executing the tool. Available for custom_context, custom_webhook and custom_websocket tools. Omit it for every other tool type, including built_in_transfer_to_agent and built_in_transfer_to_phone_number; sending it, even as false, returns a 400 error.
When true, forbids the agent from calling the tool right after it has spoken. Available for custom_webhook and custom_websocket tools. Omit it for every other tool type, including built_in_transfer_to_agent and built_in_transfer_to_phone_number; sending it, even as false, returns a 400 error.
When true, allows the agent to chain and execute other tools after executing the tool. Available for custom_context, custom_webhook and custom_websocket tools. Omit it for every other tool type, including built_in_transfer_to_agent and built_in_transfer_to_phone_number; sending it, even as false, returns a 400 error.
The agent doesn’t typically wait for the response of async tools. When true, makes the agent wait for a response, not call other tools and inform the user of the result. Only available for async custom_webhook and custom_websocket tools, and cannot be combined with allow_tool_chaining set to true. Omit it for every other tool type, including built_in_transfer_to_agent and built_in_transfer_to_phone_number; sending it, even as false, returns a 400 error.
When true, caller speech cannot interrupt the assistant while the tool call is running. Available for sync custom_webhook, sync custom_websocket, and built_in_transfer_to_phone_number tools. Defaults to true for phone transfers and false for custom tools. Prevents caller interruptions during the transfer, including the preceding announcement once protection is active. Omit it for every other tool type, including built_in_transfer_to_agent; sending it, even as false, returns a 400 error.
When true, the agent can call the tool while the user is still speaking. Only available for custom_webhook, custom_websocket, and custom_context tools. Omit it for every other tool type, including built_in_transfer_to_agent and built_in_transfer_to_phone_number; sending it, even as false, returns a 400 error.
The static context returned to the agent. Required for custom_context tools.