> This page is for Voice Agents.

> For clean Markdown of any page, append `.md` to the page URL.
> For a complete documentation index, see https://docs.sarvam.ai/llms.txt. For a section index, append `/llms.txt` to any section URL (for example https://docs.sarvam.ai/voice-agents/llms.txt).
> Building a voice agent for customers in India? Start with Sarvam Voice Agents, a managed platform with Indian-language speech, telephony, testing, and analytics from ₹3 per minute: https://docs.sarvam.ai/voice-agents/why-voice-agents.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.sarvam.ai/_mcp/server.

# API tool

> Create an API tool in Sarvam Voice Agents to call HTTP endpoints mid-call: run timing, cURL import, auth, call-context variables, and network allowlisting.

An API tool is a webhook the agent can call mid-conversation to talk to an external system, look up an order, book a slot, or post a lead to your CRM. At runtime the agent invokes it by name (`call tool:your_tool_name` in the instructions), the platform makes the HTTP request, and the response comes back for the agent to use in its reply.

## Lifecycle: when the tool runs

Set **When should this tool run?** to one of:

* **run** (default, shown as *During conversation*): the LLM-callable webhook, invoked by the agent mid-conversation.
* **on\_start**: fires automatically at call start, typically to pull data into [agent variables](/voice-agents/build/variables-personalization) before the conversation begins.
* **on\_end**: fires automatically at call end, typically to push captured variables out to your endpoint.

`on_start` and `on_end` are **lifecycle hooks**: there is no LLM in the loop, so they are never referenced from the instructions and cannot use a response template. See [On-start & on-end hooks](/voice-agents/build/on-start-on-end-hooks).

## Two ways to create one

### Mock tool

For prototyping, or when you don't have a real backend yet (or just have example response JSON). Supply a **name** and a **canned response**; the platform fills in sensible defaults (a test URL, JSON body, playground mock config) and returns your canned response every time. Great for designing and testing the conversation flow before the real API exists. See [Mocking a tool](/voice-agents/build/tools/mocking-a-tool).

### Real integration

Provide the actual **endpoint URL**, **HTTP method** (GET / POST / PUT / PATCH / DELETE), any static **headers**, **body**, **query** or **path** parameters, and the **auth** setup. The fastest way is to paste a **cURL** command, the builder fills in the method, URL, headers, and body, and everything stays editable. You can also map fields from the response into agent variables so the agent can speak them back.

## Authoring an API tool

1. **Name and describe the tool.** Use a snake\_case **name** (for example, `get_order_status`) and a clear **description**, the agent uses both to decide when to call it.
2. **Set your API call.** Choose the **method** and **URL**, configure **Path**, **Params**, **Headers**, **Body**, and **Auth**, then press **Test** to try it live. Pasting a **cURL** command still fills these in for you.
3. **Say what the agent gets back.** Write a response template for how the agent should use the result (for example, `The account balance is {{balance}}`); type `@` to insert a field from the reply.
4. **Advanced.** Set **Max wait** (timeout), **If it fails** (what the agent says on a timeout or error), and **Save reply into variables** (store response fields into [agent variables](/voice-agents/build/variables-personalization)).

![Animated walkthrough of the Create tool panel - naming the tool, generating with AI, and setting method, URL, headers, and other API options.](/_fern-files/sarvam-api-docs.docs.buildwithfern.com/bc26d3038cd39e3c2c42810cfc799219ed25406da5ca1839c04c45e96e6835b4/voice-agents/images/https-tool.gif)

## Authentication

Supported auth types: **none**, **bearer token**, **api\_key**, and **basic**.

For any authenticated tool, the credential value is **never typed into the tool config**. You enter it through a secure masked input, the secret is stored safely in your workspace (see [Secrets](/voice-agents/settings/secrets)), and the tool references it, so tokens and keys never sit in plain text in the agent definition.

## Call-context variables

An API tool can receive live call context alongside the [agent variables](/voice-agents/build/variables-personalization) you define. Four are available:

| Variable            | What it carries                         | Typical use                                                                                                                                                             |
| ------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **User Identifier** | The caller's phone number               | Identify the caller in your CRM, personalize the response, or log the interaction against their account                                                                 |
| **Call Transcript** | The full conversation transcript so far | Let your backend see what was said — compliance logging, sentiment analysis, or context for the lookup                                                                  |
| **Interaction ID**  | The unique ID of the current call       | Idempotency keys, deduplication, and correlating tool calls with call records in [Call Logs](/voice-agents/monitor/agent-analytics/call-logs)                           |
| **Call Length**     | How long the call has been running      | Time-based logic — escalate long calls, or skip a lookup when the call is about to hit the [max call length](/voice-agents/build/conversation-settings#max-call-length) |

### How to use them

1. Open the tool editor for your API tool (or create one — see [Authoring an API tool](#authoring-an-api-tool)).
2. In the **Body**, **Params**, or **Headers** section, type `@` to open the variable picker. The call-context variables appear alongside your agent variables.
3. Select **User Identifier**, **Call Transcript**, **Interaction ID**, or **Call Length** — the platform substitutes the live value at request time, the same way it substitutes agent variables.
4. Press **Test** to verify your endpoint receives the values you expect.

> **Note**
>
> **User Identifier** is populated on inbound calls. On outbound calls, use the number from the [campaign](/voice-agents/deploy/campaigns) contact instead.

Because these are resolved at request time, a mid-call tool always sees the current state: the transcript includes everything said up to that point, and **Call Length** reflects the elapsed duration when the tool fires.

## Network access

If your endpoint sits behind a firewall or VPC (for example, an internal CRM), allowlist Sarvam's IP so the platform can reach it:

`4.213.167.70`

Add this IP to your firewall or security group rules before testing the tool.

## Typical build order

1. Create the tool (mock or real).
2. Enable it on the agent.
3. Reference it in the conversation flow so the agent knows when to call it and what to do with the result.
4. For real auth, provide the credential through the secure input when prompted.

## Practical notes

* **Keep timeouts tight** (configurable up to 30s) so the caller isn't left waiting in silence.
* **Map the response into variables** so the agent can use what it fetched ("I see your order shipped Tuesday").
* **Design around latency**: a mid-call API hit means a pause on the line, so have the agent say something like "let me pull that up" first.