API ReferenceTools

Create

Creates a new tool in a project.

Authentication

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

Query parameters

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

Request

This endpoint expects an object.
namestringRequiredformat: "^[a-z0-9_]+$"

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

descriptionstringRequired
A description of what the tool does.
typeenumRequired
The type of tool.
Allowed values:
execution_modeenumRequired
Mode of operation.
Allowed values:
parameterslist of objectsOptional
Array of parameter definitions. For `custom_webhook` tools with POST method, each parameter must include a `location` field. For `custom_webhook` tools with GET method, `location` defaults to `"query_string"` if not specified. For `custom_websocket`, `built_in_transfer_to_phone_number`, and `built_in_transfer_to_agent` tools, `location` must not be specified.
endpoint_methodenumOptional
Required for webhook tools. HTTP method for the webhook endpoint.
Allowed values:
endpoint_urlstringOptionalformat: "uri"
Required for webhook tools.
endpoint_headersmap from strings to stringsOptional
Optional headers for webhook tools.
endpoint_timeout_msintegerOptional1000-180000Defaults to 5000
Timeout for webhook tools.
tool_call_output_timeout_msintegerOptional1000-180000Defaults to 5000
Timeout for WebSocket tool responses.
phone_numberstringOptional

The E.164 formatted phone number to transfer calls to. Required for built_in_transfer_to_phone_number tools.

dtmfstring or nullOptional

DTMF digits to send after the transfer connects (e.g., “1234”). Defaults to null.

use_agent_phone_numberbooleanOptionalDefaults to true

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_voicemailbooleanOptionalDefaults to false

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_tolist of stringsOptional

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_callbooleanOptionalDefaults to false
When true, forces the agent to speak before executing the tool.
wait_for_speech_before_tool_callbooleanOptionalDefaults to false

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_callbooleanOptionalDefaults to false

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

allow_tool_chainingbooleanOptionalDefaults to true

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_responsebooleanOptionalDefaults to false

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.

Response

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

Errors