All pages

Docs

Tools

Letting the AI call an API during a call: defining tools, signed requests (your own API), unsigned requests and API keys (third-party APIs), tools that need the caller's confirmation, trying tools, how responses are handled, error types and idempotency.

View as Markdown

Add tools to an agent and the AI can call an API mid-call and answer with the result: check free slots, look up a customer by phone number, make a booking.

There are two ways to call:

Kind sign For What is sent
Signed true (default) Your own API A signed tool.call JSON, POSTed by voicast
Unsigned false Third-party APIs The arguments as they are (query string for GET, JSON body for POST)

Both can carry an API key. voicast's servers make the call; the URL and API key are never given to the voice connection or the AI. The AI only gets the agent's tools and the connection actions listed by name in connectors.

In the dashboard, add tools under Tools in the agent settings, and press Try on a tool to call it once (Trying tools).

Defining tools#

json
"tools": [
  {
    "name": "find_free_slots",
    "description": "予約の空きを調べる。相手が希望の日を言ったときに使う",
    "url": "https://saas.example.com/voicast/tools",
    "parameters": {
      "properties": {
        "date": { "type": "string", "description": "希望の日(YYYY-MM-DD)" },
        "menu": { "type": "string", "enum": ["検診", "治療", "クリーニング"] }
      },
      "required": ["date"]
    }
  },
  {
    "name": "create_booking",
    "description": "予約を入れる。空きを伝えて、相手が日時を選んだら使う",
    "url": "https://saas.example.com/voicast/tools",
    "confirm": true,
    "parameters": {
      "properties": {
        "start": { "type": "string", "description": "開始の日時(ISO 8601)" },
        "name": { "type": "string" },
        "phone": { "type": "string" }
      },
      "required": ["start", "name"]
    }
  },
  {
    "name": "find_customer",
    "description": "電話番号で顧客を探す。会話の最初に、かけてきた番号で使う",
    "url": "https://api.example-crm.com/v1/customers/search",
    "method": "GET",
    "sign": false,
    "auth": { "type": "api_key", "header": "Authorization", "value": "sk_live_…" },
    "parameters": {
      "properties": {
        "phone": { "type": "string", "description": "電話番号(数字だけ)" }
      },
      "required": ["phone"]
    }
  }
]
Field Required Description
name yes Starts with a lowercase letter; lowercase letters, digits and _, up to 40 chars. Reserved names cannot be used. Must not clash with connection tool names
description yes When to use it (up to 500 chars). The AI reads this to decide
url yes Where to call. https with a public host name only (no literal IP addresses, localhost or internal names). Up to 500 chars
method GET or POST. Default POST. Signed tools must use POST
sign Default true (signed). false for unsigned requests
auth Sends an API key: { "type": "api_key", "header": "…", "value": "…" } (see API keys)
parameters Arguments (see Arguments)
confirm When true, voicast asks the caller with a fixed confirmation message before calling, and tells the result in a fixed message (Tools that need confirmation). Use it for tools that change data, such as bookings and cancellations
confirm_message Confirmation message for a confirm tool (up to 200 characters). {argument name} inserts the value
done_message Message said when a confirm tool succeeds (up to 200 characters). {argument name} can be inserted. An empty string "" says no completion message

An agent can have up to 10 tools. Before using a tool, the AI tells the caller it is checking (「お調べしますので、少々お待ちください」).

Arguments#

parameters are the values the AI collects in the conversation and passes to the tool. Up to 20 properties of type string, number, integer or boolean; enum up to 50 values. Arguments listed in required are required.

  • Only the arguments you defined are sent. Values the AI adds under other names are dropped, and so are empty values (empty strings and null).
  • If a required argument is missing, the API is not called and the AI gets invalid_arguments.
  • For a name-reading argument (name_kana, furigana and so on), the AI fills in the reading it heard without asking the caller: as the description says if it specifies the script, otherwise full-width katakana (Name readings). Name arguments (name and so on) still get the name as recognized.

Signed requests (your own API)#

With sign left out or true, voicast POSTs a signed request to the tool's url. You can receive every tool on one URL and switch on the tool name.

POST https://saas.example.com/voicast/tools
content-type: application/json
user-agent: voicast-tools/1
webhook-id: msg_6f1c…
webhook-timestamp: 1790000042
webhook-signature: v1,Rk9x…
idempotency-key: tc_7f3a9c2e…

{
  "type": "tool.call",
  "tool": "find_free_slots",
  "tool_call_id": "tc_7f3a9c2e…",
  "arguments": { "date": "2026-10-07" },
  "call": {
    "id": "call_…",
    "channel": "phone",
    "provider_call_id": "CA…",
    "from": "+819012345678",
    "tenant": { "id": "ten_…", "external_id": "clinic-123" }
  }
}
Field Description
tool The tool name
tool_call_id Unique per tool call. Same as the idempotency-key header
arguments The arguments the AI chose (only the ones you defined)
call.channel phone or web; test when trying a tool
call.tenant.external_id Your customer ID, to pick the right booking calendar and so on. When trying a tool without tenant_id, call.tenant is null
call.from The caller's number (phone calls where your TwiML passed from)
test true only when trying a tool

Tools with auth also carry the API key header.

Unsigned requests (third-party APIs)#

With sign: false, voicast sends the arguments as they are, without a signature or the tool.call envelope, so you can call a third-party REST API directly. Authenticate with an API key.

GET https://api.example-crm.com/v1/customers/search?phone=09012345678
accept: application/json
user-agent: voicast-tools/1
idempotency-key: tc_7f3a9c2e…
authorization: Bearer sk_live_…
  • GET sends the arguments in the query string. A query already in url is kept; an argument with the same name replaces its value.
  • POST sends the arguments as the JSON body (for example { "phone": "09012345678" }).
  • idempotency-key is unique per tool call, as for signed requests.

API keys#

With auth, every request carries an API key in a header. Signed tools can have one too.

json
"auth": { "type": "api_key", "header": "X-API-Key", "value": "…" }
  • With the Authorization header the key is sent as Bearer <key>; with any other header (such as X-API-Key) it is sent as is.
  • header is up to 64 letters, digits and -. Headers with a fixed meaning, such as Content-Type, Host, Cookie, Idempotency-Key and webhook-signature, are not allowed.
  • value is 1 to 2,000 characters. On save it is taken out of the settings and stored encrypted, per agent and tool name. It is not kept in the agent's version history and is never returned by the API or the dashboard.
  • The agent's tool_keys lists the stored keys: name (the tool name), hint (the last 4 characters; empty for keys shorter than 12 characters) and updated_at.
  • On later saves you can leave value out to keep the stored key. Pass value only to change the key.
  • A stored key belongs to the tool name and the origin of its URL (https:// and the host name). After renaming a tool, changing its URL origin, or copying it to another agent, enter the key again. Saving a tool with auth and no key returns 422 invalid_config.
  • Saving deletes the stored key of a tool whose URL origin changed or that was removed (changing only the path keeps the key).
  • When you roll back to an earlier version (save its settings again), a tool with the same name and URL origin uses the key stored now.
  • Deleting the agent deletes its stored keys.
  • For APIs that need no authentication, leave auth out.

How responses are handled#

The body of a 2xx response goes to the AI.

json
{ "slots": ["2026-10-07T10:00:00+09:00", "2026-10-07T14:30:00+09:00"] }
Body What the AI gets
JSON As is
Not JSON (plain text and so on) { "text": "…" }
Empty {}
Over 4,000 characters The first 4,000 characters as { "text": "…", "truncated": true }
  • voicast waits up to 8 seconds, then treats the call as failed.
  • Redirects (3xx) are not followed (upstream_error).
  • A body over 4,000 characters is cut and no longer reaches the AI as JSON. Return only what the AI needs.
  • Return expected outcomes such as "no free slots" or "not found" as 2xx, e.g. { "slots": [] } or { "found": false, "message": "その番号の方は見つかりませんでした" }, so the AI can say so naturally.

Ending the conversation from a tool response (end_call)#

Put end_call in the response JSON to end the conversation right away, saying the closing words once, without handing control back to the AI. Use it when the tool has already done the follow-up (for example, it has already notified a staff member) and the AI should not keep talking.

json
{ "found": false, "end_call": { "outcome": "handoff", "message": "I'm sorry, we couldn't find that name. A staff member is on the way, please wait a moment.", "reason": "Name not in the directory", "fields": { "visitor_name": "Suzuki" } } }
Field Meaning
outcome The result: completed, answered or handoff (default handoff)
message The closing words (up to 200 characters). Omit it for the standard closing of the outcome
reason Why the conversation ended, kept in the call record
fields Collected fields (only those in the agent's fields are kept)

It works for voice replies and text replies (output: "text").

Error types#

When a call fails, the AI gets one of these error values. It apologizes and, for example, offers a callback from staff.

What happened error
401 or 403 unauthorized (check the API key)
404 not_found
Any other non-2xx (3xx, 429, 5xx…) or no connection upstream_error
No response within 8 seconds timeout
A required argument is missing invalid_arguments (the API is not called)
A tool with auth has no stored API key missing_api_key (the API is not called)

Verifying the signature#

Signed requests carry a Standard Webhooks signature. The steps and code (Node.js, Python, PHP, Go) are the same as in Results; only the secret differs.

The tools signing secret (whsec_…) is one per environment. Read it in the environment settings in the dashboard (admin or above), with GET /v1/tools/secret, or with the MCP tool get_tools_secret; rotate it there, with POST /v1/tools/secret/rotate, or with rotate_tools_secret. For 24 hours after a rotation, requests carry signatures with both the old and new secret, so you have time to switch (libraries accept both secrets).

js
import express from 'express';
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.VOICAST_TOOLS_SECRET); // whsec_…
const app = express();

app.post('/voicast/tools', express.raw({ type: 'application/json' }), async (req, res) => {
  let body;
  try {
    body = wh.verify(req.body, req.headers);
  } catch {
    return res.sendStatus(401);
  }
  const clinic = body.call.tenant.external_id;
  switch (body.tool) {
    case 'find_free_slots':
      return res.json({ slots: await findSlots(clinic, body.arguments.date) });
    case 'create_booking':
      // Run each tool_call_id only once
      return res.json(await createBookingOnce(body.tool_call_id, clinic, body.arguments));
    default:
      return res.status(404).json({ error: 'unknown tool' });
  }
});

The SDK's verifyToolCall verifies them too.

Requests sent when trying a tool carry the same signature as real calls and add "test": true to the body. Without tenant_id, call.tenant is null, so body.call.tenant.external_id in the example above cannot be read. When your server receives tests, check body.test and return a test response, or pass tenant_id in the test.

Idempotency#

During a call, voicast itself runs each tool_call_id only once and returns the earlier result for a repeat. Even so, tools that change data, such as booking, should run once on your side too if the same request arrives twice. Store the tool_call_id (the idempotency-key header) and return the earlier result for a repeated ID.

js
async function createBookingOnce(toolCallId, clinic, args) {
  const done = await db.toolRuns.get(toolCallId);
  if (done) return done.result;
  const result = await createBooking(clinic, args);
  await db.toolRuns.put(toolCallId, { result });
  return result;
}

Tools that need confirmation#

Tools with confirm: true are used after the caller agrees to a confirmation message, and the result is told in the message you set. Always set it on tools that create, change, cancel or register something. Read-only tools (checking slots, finding a customer) do not need it.

When the caller agrees, voicast says "Certainly. One moment, please." before the tool runs (in Japanese 「かしこまりました。少々お待ちください。」, in Chinese 「好的,请稍等。」, in Korean 「알겠습니다. 잠시만 기다려 주세요.」), and says the completion message once when the result arrives.

Without done_message it is "That's been completed."; on failure it is "I'm sorry, your request has not been confirmed yet. A staff member will get back to you."

With an empty done_message ("done_message": ""), voicast says no completion message. Use it when only the message of end_call in the response should be said (for example, the tool notifies a staff member and closes with "A staff member is on the way, please wait a moment."). Without end_call, the AI tells the caller the result. The failure message does not change.

The confirmation message (confirm_message) and the completion message (done_message) can insert values with {argument name}.

json
{
  "name": "create_booking",
  "description": "Books an appointment after the caller picks a time",
  "url": "https://saas.example.com/voicast/tools",
  "confirm": true,
  "confirm_message": "Shall I book {menu} for {name} on {start}?",
  "done_message": "You're booked for {start}. We look forward to seeing you.",
  "parameters": {
    "properties": {
      "start": { "type": "string", "description": "Start time (YYYY-MM-DDTHH:MM)" },
      "menu": { "type": "string", "enum": ["checkup", "treatment", "cleaning"] },
      "name": { "type": "string" }
    },
    "required": ["start", "name"]
  }
}
  • Date and time values (YYYY-MM-DDTHH:MM such as 2026-10-19T14:00, a date YYYY-MM-DD, or with a time zone offset) are inserted as spoken dates ("Monday, October 19 at 2 p.m.").
  • Name arguments (name, …_name) are inserted as the reading when the tool has a reading argument (name_kana and so on); in Japanese the reading is said in hiragana.
  • A name that is not an argument is rejected with 422 invalid_config when saving. Arguments without a value become empty.
  • Without confirm_message, the confirmation is a default message made from the argument values (ID arguments …_id, phone numbers and readings are left out).
  • voicast speaks these messages in the conversation's language (Japanese, English, Chinese or Korean). confirm_message and done_message are used only in conversations in the language they are written in; other conversations use the default messages.
  • When nothing could be changed (for example, the slot was just taken), return 2xx with { "ok": false, "message": "That time is no longer available" } or { "error": "slot_taken", "message": "…" }, or a 4xx. Unless a 2xx body has ok: false or an error, voicast tells the caller it is done. With ok: false or an error, voicast says only "I'm sorry, your request has not been confirmed yet." and the AI explains why and offers another time.

When trying a tool, confirm tools are called without asking.

Trying tools#

Call a tool once and see what it returns. It runs exactly as when the AI calls it during a call (same signature, API key and 8-second limit).

  • Dashboard: under Tools in the agent settings, press Try on a tool; in the Try tool dialog, enter the arguments and call it. It uses what is in the form, even before you save. Results shows success or failure, the status code, the elapsed time and the body. Developers, admins and owners can use it.
  • API: POST /v1/tools/try (see the API reference)
  • MCP: try_tool (see MCP)
  • SDK: tools.try() (see SDK)
bash
curl https://api.voicast.jp/v1/tools/try \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agt_…", "tool": "find_free_slots", "arguments": { "date": "2026-10-07" }, "tenant_id": "ten_…" }'
json
{
  "tool": "find_free_slots",
  "ok": true,
  "result": { "slots": ["2026-10-07T10:00:00+09:00"] },
  "status": 200,
  "body": "{\"slots\":[\"2026-10-07T10:00:00+09:00\"]}",
  "truncated": false,
  "duration_ms": 182
}
  • tool is the name of a saved tool (requires agent_id) or an unsaved tool definition (same shape as an entry in tools). The stored key is used only when you pass a saved tool by name. With a definition, put the API key in auth.value (a tool with auth and no value returns 422 missing_api_key).
  • There is no conversation charge and nothing is recorded as a call.
  • confirm tools are called without asking. Tools that change data (such as booking) really change it.
  • Signed requests carry "test": true, call.channel is test and call.id is try_…. Without tenant_id, call.tenant is null.
  • Signed tools are sent with the same signature as real calls, even when trying them; the signature alone does not tell a try from a real call. APIs that write data should check test: true in the body (call.channel is test) and return without writing, or refuse.
  • Up to 30 tries per minute per environment. Beyond that you get 429 rate_limited with Retry-After.

Good practice#

  • The AI never answers beyond what a tool returned. Put anything it should say (prices, directions) in the response or in the agent's faq.
  • Return only the personal data the AI needs (for example, not a full date of birth).
  • On URLs called by signed tools, do nothing until the signature is verified. Reject unsigned requests and stale webhook-timestamp values.
  • Give third-party API keys only the permissions the tool needs (a read-only key for read-only tools).