> This page is for Voice APIs.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://dev.hume.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://dev.hume.ai/_mcp/server.

# Tool Call

POST 

Sent when EVI triggers a tool call

Reference: https://dev.hume.ai/voice/reference/speech-to-speech-evi/chat-webhooks/tool-call

## Request

### Payload

- `chat_group_id` (string, required) — Unique ID of the **Chat Group** associated with the **Chat** session.
- `chat_id` (string, required) — Unique ID of the **Chat** session.
- `config_id` (string, required, nullable) — Unique ID of the EVI **Config** used for the session.
- `caller_number` (string, required, nullable) — Phone number of the caller in E.164 format (e.g., `+12223333333`). This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration.
- `custom_session_id` (string, required, nullable) — User-defined session ID. Relevant only when employing a [custom language model](/docs/empathic-voice-interface-evi/custom-language-model) in the EVI Config.
- `timestamp` (integer, required) — Unix timestamp (in milliseconds) indicating when the tool call was triggered.
- `tool_call_message` (ToolCallMessage, required) — The tool call.
- `twilio_metadata` (map from string to string, required, nullable) — Twilio metadata associated with the chat. This field is included only if the Chat was created via the [Twilio phone calling](/docs/empathic-voice-interface-evi/phone-calling) integration. Fields may include `call_sid`, `account_sid`, `from_number`, `to_number`, `caller_name`, `caller_number`, `from_city`, `from_state`, `from_zip`, `from_country`, `to_city`, `to_state`, `to_zip`, and `to_country`.If a specific metadata is not available, this field will be set to an empty string.
- `event_name` ("tool_call", optional, default: tool_call) — Always `tool_call`.

## Types

### ToolCallMessage

**Indicates that the supplemental LLM has detected a need to invoke the specified tool.** This message is only received for user-defined function tools. Contains the tool name, parameters (as a stringified JSON schema), whether a response is required from the developer (either in the form of a `ToolResponseMessage` or a `ToolErrorMessage`), the unique tool call ID for tracking the request and response, and the tool type. See our [Tool Use Guide](/docs/speech-to-speech-evi/features/tool-use) for further details.

- `name` (string, required) — Name of the tool called.
- `parameters` (string, required) — Parameters of the tool. These parameters define the inputs needed for the tool's execution, including the expected data type and description for each input field. Structured as a stringified JSON schema, this format ensures the tool receives data in the expected format.
- `response_required` (boolean, required) — Indicates whether a response to the tool call is required from the developer, either in the form of a [Tool Response message](/reference/empathic-voice-interface-evi/chat/chat#send.Tool%20Response%20Message.type) or a [Tool Error message](/reference/empathic-voice-interface-evi/chat/chat#send.Tool%20Error%20Message.type).
- `tool_call_id` (string, required) — The unique identifier for a specific tool call instance. This ID is used to track the request and response of a particular tool invocation, ensuring that the correct response is linked to the appropriate request.
- `tool_type` (enum, required) — Type of tool called. Either `builtin` for natively implemented tools, like web search, or `function` for user-defined tools.
  - Allowed values: `builtin`, `function`
- `type` ("tool_call", required) — The type of message sent through the socket; for a Tool Call message, this must be `tool_call`. This message indicates that the supplemental LLM has detected a need to invoke the specified tool.
- `custom_session_id` (string, optional, nullable) — Used to manage conversational state, correlate frontend and backend data, and persist conversations across EVI sessions.