Sign in

v3

latestOpenAPI 3.1.02026-08-0755220214.3 KB
tools

Create

Creates a new tool in a project.

post/tools

Query parameters

projectstring

The name of the project to create the tool in.

Headers

Authorizationstring required

Bearer authentication header of the form Bearer <PHONIC_API_KEY>. Manage your API keys here.

Request body

namestring required

The name of the tool. Must be snake_case and unique within the organization.

descriptionstring required

A description of what the tool does.

type'custom_context' | 'custom_webhook' | 'custom_websocket' | 'built_in_transfer_to_phone_number' | 'built_in_transfer_to_agent' | 'built_in_natural_conversation_ending' | 'built_in_keypad_input' | 'built_in_choose_not_to_respond' required

The type of tool.

execution_mode'sync' | 'async' required

Mode of operation.

parameter_locationsobject

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.

endpoint_method'GET' | 'POST'

Required for webhook tools. HTTP method for the webhook endpoint.

endpoint_urlstring uri

Required for webhook tools. Must be a publicly routable HTTPS URL without embedded credentials.

endpoint_headersobject

Optional headers for webhook tools.

endpoint_timeout_msinteger

Timeout for webhook tools.

tool_call_output_timeout_msinteger

Timeout for WebSocket tool responses.

phone_numberstring nullable

The E.164 formatted phone number to transfer calls to. Set to null if the agent should determine the phone number.

dtmfstring nullable

DTMF digits to send after the transfer connects (e.g., "1234"). Defaults to null. Ignored when dynamic_dtmf is true.

dynamic_dtmfboolean

When true, the agent determines the DTMF digits at call time (and may choose to send none); the static dtmf is ignored. Only sent when use_agent_phone_number is true (not on a SIP REFER transfer).

use_agent_phone_numberboolean

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.

detect_voicemailboolean

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.

agents_to_transfer_tostring[]

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.

require_speech_before_tool_callboolean

When true, forces the agent to speak before executing the tool.

speech_before_tool_call'required' | 'optional' | 'suppressed'

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.

wait_for_speech_before_tool_callboolean

If true, the agent will wait to finish speaking before executing the tool. This is only available for custom_webhook and custom_websocket tools.

forbid_speech_after_tool_callboolean

When true, forbids the agent from speaking after executing the tool. Available for custom_context, custom_webhook and custom_websocket tools.

forbid_tool_call_after_speechboolean

When true, forbids the agent from calling the tool right after it has spoken. Available for custom_webhook and custom_websocket tools.

allow_tool_chainingboolean

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.

wait_for_responseboolean

The agent doesn't typically wait for the response of async custom_websocket 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_websocket tools.

contextstring

The static context returned to the agent. Required for custom_context tools.

Response

Success response

idstring required

The ID of the created tool.

namestring required

The name of the created tool.