Voice agentsAgent tools

Create tool

Adds a tool to one of your agents. An agent can have each tool_type once per channel.

POST/v2/tools

Authorization

Authorizationstringheaderrequired
Bearer authentication header of the form Bearer <api_key>, where <api_key> is a key from Account Settings → API keys in your dashboard.

Request body

application/json

agent_idstring (uuid)required
The agent to add the tool to.
tool_typestringrequired
A built-in type, or your custom tool's task name.
configobject
Tool settings. The shape depends on tool_type.
Default: {}
credentialsobject
Secrets the tool needs, e.g. {"api_key": "..."}. Stored encrypted, never returned.
channelstring
Which agent channel uses the tool.
Allowed:telephonywhatsappDefault: telephony

Response

The created tool object.

Show all 9 fieldsHide fields

idstring (uuid)
Unique identifier of the tool.
agent_idstring (uuid)
Agent the tool belongs to.
tool_typestring
Built-in type (call_transfer, cal_com_booking, knowledge_base, media_attachment, static_response, whatsapp_template) or, for a custom tool, its task name.
is_enabledboolean
Whether the agent may use the tool.
configobject
Tool settings. The shape depends on tool_type.
has_credentialsboolean
Whether secret credentials are stored. Credentials are never returned.
channelstring
telephony for the voice agent, whatsapp for the WhatsApp text agent.
Allowed:telephonywhatsapp
created_atstring (date-time)
When the tool was created.
updated_atstring (date-time)
When the tool was last changed.

curl --request POST \ --url 'https://api.tarangnow.com/v2/tools' \ --header 'Authorization: Bearer <api_key>' \ --header 'Content-Type: application/json' \ --data '{ "agent_id": "3f6c2b1e-8a4d-4c5e-9b2a-1d7e6f8a9b0c", "tool_type": "check_order_status", "channel": "telephony", "config": { "name": "check_order_status", "description": "Look up the status of a customer'\''s order by order id.", "pre_call_message": "One moment while I check that for you.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The customer'\''s order id" } }, "required": [ "order_id" ] }, "method": "GET", "url": "https://api.example.com/orders/{order_id}", "param": {}, "headers": {} }, "credentials": { "api_key": "sk_live_your_backend_key" } }'

{ "id": "b7e1c2d3-4f5a-4b6c-9d7e-8f9a0b1c2d3e", "agent_id": "3f6c2b1e-8a4d-4c5e-9b2a-1d7e6f8a9b0c", "tool_type": "check_order_status", "is_enabled": true, "config": { "name": "check_order_status", "description": "Look up the status of a customer's order by order id.", "pre_call_message": "One moment while I check that for you.", "parameters": { "type": "object", "properties": { "order_id": { "type": "string", "description": "The customer's order id" } }, "required": [ "order_id" ] }, "method": "GET", "url": "https://api.example.com/orders/{order_id}", "param": {}, "headers": {} }, "has_credentials": true, "channel": "telephony", "created_at": "2026-10-20T09:15:42.120Z", "updated_at": "2026-10-24T14:03:11.508Z" }

Request body

application/json

agent_idstring (uuid)required

The agent to add the tool to.

tool_typestringrequired

A built-in type, or your custom tool's task name.

configobject

Tool settings. The shape depends on tool_type.

Default: {}

credentialsobject

Secrets the tool needs, e.g. {"api_key": "..."}. Stored encrypted, never returned.

channelstring

Which agent channel uses the tool.

Allowed:telephonywhatsappDefault: telephony

Response

The created tool object.

Show all 9 fieldsHide fields

idstring (uuid)
Unique identifier of the tool.
agent_idstring (uuid)
Agent the tool belongs to.
tool_typestring
Built-in type (call_transfer, cal_com_booking, knowledge_base, media_attachment, static_response, whatsapp_template) or, for a custom tool, its task name.
is_enabledboolean
Whether the agent may use the tool.
configobject
Tool settings. The shape depends on tool_type.
has_credentialsboolean
Whether secret credentials are stored. Credentials are never returned.
channelstring
telephony for the voice agent, whatsapp for the WhatsApp text agent.
Allowed:telephonywhatsapp
created_atstring (date-time)
When the tool was created.
updated_atstring (date-time)
When the tool was last changed.