Agents
How to write an agent: the AI's role, greeting, fields to collect, FAQ, handoff rules, voice, speaking rate and language.
An agent decides what the AI says, what it collects and when it hands off to a person. One agent can serve many tenants. Create agents in the dashboard (Agents), with the API (POST /v1/agents) or over MCP (create_agent). You can also start from a template.
Conversations are in Japanese today, so the text you write (greeting, persona, labels, rules, FAQ) is in Japanese. Field keys and other identifiers are ASCII.
Shape#
{
"name": "Dental reception",
"config": {
"greeting": "お電話ありがとうございます。さくら歯科です。ご用件をお話しください。",
"persona": "落ち着いた丁寧な受付。1 回の発話は 2 文まで",
"fields": [
{ "key": "name", "label": "お名前", "required": true },
{ "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" },
{ "key": "purpose", "label": "ご用件", "required": true }
],
"handoff_when": ["人と話したいと言われた", "急な痛みや腫れがある"],
"closing": "承知しました。担当者から折り返しご連絡します。",
"closing_answered": "ほかにご不明な点があれば、またお電話ください。",
"faq": [
{ "q": "診療時間は", "a": "平日は 9 時から 18 時、土曜は 13 時までです。日曜・祝日は休みです。" }
],
"domain": "歯科医院",
"vocabulary": ["インプラント", "ホワイトニング", "定期検診"],
"voice": "female-firm",
"speaking_rate": 1.0
}
}Fields#
| Field | Required | Description | Limit |
|---|---|---|---|
greeting |
yes | The first thing the AI says, read out as written | 300 chars |
persona |
yes | Role and manner of speaking (e.g. calm, polite receptionist; at most two sentences per turn) | 1,000 chars |
fields |
yes | What to collect (below) | 1–20 |
handoff_when |
yes | When to hand off to a person (below). May be an empty array | 20 items, 200 chars each |
closing |
yes | What the AI says when it has collected everything (not used when a tool that changes bookings succeeded; the AI ends with a short thank-you instead. See Connectors) | 300 chars |
closing_answered |
What it says when an FAQ answer settled the call | 300 chars | |
faq |
Frequent questions [{ q, a }] |
50; q 200 chars, a 1,000 chars | |
domain |
Line of business (a hint for speech recognition) | 200 chars | |
vocabulary |
Industry terms and proper nouns (hints for speech recognition). A {{name}} entry adds the per-conversation value, split on commas (、 or ,), for that conversation only (e.g. location names) |
200 items, 50 chars each | |
voice |
Voice ID (below). Defaults to female-breezy |
||
speaking_rate |
Speaking rate (below). Defaults to 1.0 |
||
language |
Conversation language (below). Defaults to ja |
||
tools |
APIs (yours or third-party) the AI can call during a call (below). See Tools | 10 | |
connectors |
Connections to third-party APIs. See Connections | 10 | |
recording |
true records the conversation (below). Omit to not record |
||
max_call_minutes |
Maximum length of one conversation in minutes (below). Defaults to 30 |
Unknown keys are dropped. Invalid input returns 422 invalid_config with one entry per problem in details.
Fields to collect#
{ "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" }| Key | Description |
|---|---|
key |
Name in the call's fields. Starts with a lowercase letter; lowercase letters, digits and _, up to 40 chars. Must be unique |
label |
How the AI asks for it (up to 100 chars) |
required |
When true, the call does not finish until it is collected |
type |
text (default) or phone. Phone numbers are stored as digits only, and the AI asks again unless the number is 10 or 11 digits starting with 0 (Japanese numbers) |
The AI reads names and phone numbers back to confirm them; phone numbers are read in three groups. Names are read back by how they sound, not by kanji.
Name readings#
On the phone the caller's kanji cannot be heard, so the kanji in name and similar fields are the speech recognizer's guess (a different character with the same reading is common, e.g. 小林真琴 for こばやし まことkey ends with kana (such as name_kana) or contains furigana, yomi or reading, and fields whose label contains 読み, ふりがlabel says ひらが
{ "key": "name_kana", "label": "お名前の読み" }- Half-width kana, hiragana and katakana are unified and spaces collapsed (
ヤマダ タロウ) - The values and format of
nameand other fields do not change. Without a reading field, results are the same as before - Every template includes
name_kana(お名前の読み)
Handoff rules#
When a rule matches, the AI ends the conversation right away (without asking for a name and so on) and the outcome is handoff. On the phone you then transfer the call to a person (Phone).
"handoff_when": ["人と話したいと言われた", "怒っている", "急な痛みや腫れがある", "聞き取れない状態が 2 回続いた"]Write rules as plain sentences. Avoid broad rules (such as "the caller asked a question"), or most calls will be handed off.
The AI closes with "I'll connect you to a staff member. Please hold on a moment." If persona describes what to do before handing off (looking something up with a tool, asking for the name and so on) or what to say when handing off, the AI does that first and closes with those words (up to 200 characters; the outcome is still handoff). Use this when you do not transfer the call right away, for example to ask the caller to call the shop's own number.
FAQ#
When asked, the AI answers using only these answers. Anything not written here is not guessed; the AI offers a callback instead. When an answer settles the call, the outcome is answered and the AI closes with closing_answered.
Outcomes#
When the AI ends the conversation, the call's outcome is set.
outcome |
When |
|---|---|
completed |
All required fields were collected; staff will call back |
answered |
An FAQ answer settled the call |
handoff |
A handoff rule matched (connect a person now) |
hangup |
The caller hung up before the end, or stayed silent even after being asked again |
time_limit |
The conversation reached its maximum length (max_call_minutes, below) |
error |
The voice server failed |
Voices#
Pick one of the following voices by ID. Every voice speaks every supported language. You can listen to each voice in the dashboard (Agents).
| ID | Gender | Dashboard name |
|---|---|---|
female-breezy (default) |
Female | Breezy female |
female-firm |
Female | Firm female |
female-youthful |
Female | Youthful female |
female-bright |
Female | Bright female |
female-cheerful |
Female | Cheerful female |
female-upbeat |
Female | Upbeat female |
female-warm |
Female | Warm female |
female-gentle |
Female | Gentle female |
female-soft |
Female | Soft female |
female-smooth |
Female | Smooth female |
female-clear |
Female | Clear female |
female-brisk |
Female | Brisk female |
female-mature |
Female | Mature female |
female-easygoing |
Female | Easygoing female |
male-calm |
Male | Calm male |
male-upbeat |
Male | Upbeat male |
male-firm |
Male | Firm male |
male-deep |
Male | Deep male |
male-energetic |
Male | Energetic male |
male-friendly |
Male | Friendly male |
male-clear |
Male | Clear male |
male-easygoing |
Male | Easygoing male |
male-smooth |
Male | Smooth male |
male-gravelly |
Male | Gravelly male |
male-informative |
Male | Informative male |
male-steady |
Male | Steady male |
male-casual |
Male | Casual male |
male-lively |
Male | Lively male |
male-savvy |
Male | Savvy male |
male-breathy |
Male | Breathy male |
Speaking rate#
1.0 is normal speed and the default. Choose one of these values.
| Value | Speed |
|---|---|
0.85 |
Very slow |
0.9 |
Slow |
0.95 |
A little slow |
1.0 |
Normal (default) |
1.05 |
Barely faster |
1.1 |
Slightly faster |
1.15 |
A little faster |
1.2 |
Faster |
1.25 |
Quite fast |
1.3 |
Fast |
1.4 |
Very fast |
1.5 |
Fastest |
Language#
Choose the language the AI speaks with callers.
| Value | Language |
|---|---|
ja (default) |
Japanese |
en |
English |
zh |
Chinese (Mandarin, Simplified) |
ko |
Korean |
auto |
Match the caller (Japanese, English, Chinese or Korean) |
- Speech recognition, the AI's replies and the voice all use that language. The voice (
voice) is the same in every language. greeting,closingandclosing_answeredare read exactly as written. If you choose a language other thanja, write them in that language. Built-in lines, such as handing off to a person or checking whether the caller is still there, are spoken by voicast in that language.autoreplies in the language the caller speaks. The greeting plays as written, and the AI speaks Japanese until it knows the caller's language. A closing is used only when it is written in the caller's language; otherwise voicast speaks its built-in closing in that language.
Tools#
APIs the AI calls during a call, such as checking open slots or looking up a customer. The AI only gets this agent's tools and the connection actions listed by name in connectors.
"tools": [
{
"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 | Tool name. Starts with a lowercase letter; lowercase letters, digits and _, up to 40 chars |
description |
yes | What the tool does and when to use it (up to 500 chars) |
url |
yes | Where to call (https) |
method |
GET or POST. Default POST |
|
sign |
Default true: a signed tool.call POST (for your own API). false sends the arguments as they are (for third-party APIs) |
|
auth |
{ "type": "api_key", "header", "value" }: sends an API key in a header |
|
parameters |
Arguments the AI collects in the conversation | |
confirm |
When true, voicast asks the caller with a fixed confirmation message before the tool runs, and tells the result in a fixed message |
|
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 (Tools) |
- The API key (
auth.value) is taken out of the settings on save and stored encrypted. It is not kept in the version history;tool_keysin the response lists only the tool name and the last 4 characters. You can leavevalueout on later saves. - See Tools for details.
In the dashboard#
Under Tools in the agent settings form, press Add tool (up to 10).
| Field | API field |
|---|---|
| Tool name | name |
| Description | description |
| URL | url |
| Method | method |
| Sign requests | sign |
| Confirm before use | confirm |
| Confirmation message, Completion message (shown only for confirm-before-use tools) | confirm_message, done_message |
| Authentication (None / API key) | auth |
| Header for the API key (Authorization (Bearer) / Other) | auth.header |
| API key | auth.value. Not shown again after saving; enter a key only to change it |
| Arguments (name, description, required) | parameters |
Press Try on a tool to enter arguments and call the API once; Results shows success or failure, the status code, the elapsed time and the body. It uses what is in the form, even before you save. There is no conversation charge and nothing is added to the conversation history. Tools that change data really change it (see Trying tools).
Recording (recording)#
Set "recording": true to record conversations. In the dashboard, use [Record conversations] in the agent settings. Recording is off by default.
- Both phone and Web/app conversations are recorded, with the caller and the AI mixed into one audio file (MP3, mono). Conversations that return text only (
output: "text") contain only the caller's voice. - The recording is saved when the conversation ends and is deleted automatically once the environment's retention period (1, 7, 14 or 30 days; 30 days by default) has passed since it was saved. The call's
recording.expires_attells you when (Retention). - You can play recordings from the conversation records in the dashboard or fetch them with
GET /v1/calls/{id}/recording(Results). Acall.recording_readywebhook is sent when a recording is ready. - Storing recordings costs nothing extra (still ¥10 per minute of conversation; see Pricing and billing).
- A conversation in progress follows the setting of the version it started with.
Tell the caller the conversation is recorded. Voices are personal information. When recording, tell the caller at the start of the conversation, for example by adding "This call is recorded for quality purposes." to the greeting. Whether you must notify the caller and how long you may keep recordings depends on your industry and on the rules of each country or region. Also state in your service's terms and privacy policy that you record and store conversations.
Maximum length (max_call_minutes)#
Choose the maximum length of one conversation: 5, 10, 15, 30 or 60 minutes. Defaults to 30. In the dashboard, choose it in the agent settings under [Maximum conversation length].
- Shortly before the limit, the AI ends the conversation with a fixed closing (in English: "We've reached the time limit, so I'll have to end the call here. Thank you."). The call's
outcomeistime_limit. - If a booking or other change is not finished, the AI says so before the closing.
- The length is counted from when the conversation connects, for phone and web/app conversations alike.
Versions#
Updating an agent (PUT /v1/agents/{id}) creates a new version. Calls already in progress keep the version they started with; the next call uses the new one. Each call records the version it used (agent.version), and GET /v1/agents/{id}?version= returns that version's config.
PUT takes the whole config; partial updates are not supported.
Tool API keys are stored outside the versions. After rolling back to an earlier version, a tool with the same name uses the key stored now.
Assigning to tenants#
A tenant's agent_id is the default agent for its calls. You can override it per call: <Parameter name="agent"> on the phone, or agent_id in POST /v1/sessions for Web and apps.
An agent used by a tenant or a SIP credential cannot be deleted (409 in_use). First change the tenant's agent_id, and change the SIP credential's agent_id (PATCH /v1/tenants/{id}/sip-credentials/{credential}) or delete it.
Templates#
Ready-made agents you can start from. In the dashboard, they are offered first when you create an agent (or choose “Start from scratch”). The API returns the same list from GET /v1/agent-templates, and MCP from list_agent_templates.
id |
Name | Parts to replace |
|---|---|---|
dental_clinic |
Dental clinic appointments | Clinic name (〇〇歯科), Office hours (〇〇(診療時間)), Parking location (〇〇(駐車場の場所)), Number of parking spaces (〇〇(台数)) |
restaurant |
Restaurant reservations | Restaurant name (〇〇(店名)), Opening hours (〇〇(営業時間)), Regular closing days (〇〇(定休日)), Cancellation policy (〇〇(キャンセル料の決まり)) |
inquiry |
Inquiry intake | Company name (株式会社〇〇), Phone hours (〇〇(受付時間)), Address (〇〇(所在地)) |
take_message |
Message taking | Company name (株式会社〇〇), Business hours (〇〇(営業時間)) |
car_service |
Auto service and tire shop bookings | Shop name (〇〇(店名)), Business hours (〇〇(営業時間)), Regular closing days (〇〇(定休日)), Address (〇〇(所在地)), Typical service times (〇〇(作業の所要時間の目安)), Payment methods (〇〇(お支払い方法)) |
- Each template includes a role (
persona), greeting, fields to collect, sample FAQ answers, sample handoff rules and closings. When the dental clinic and auto service templates hand off (outcomehandoff), the AI gives the clinic's or shop's own phone number, looked up with a connected tool that returns its details, and asks the caller to call it directly. If the number is not available, it first takes the name, phone number and request, and says staff will call back. They contain no integrations (connectors,tools): staff call back to check availability and confirm bookings. When you connect a calendar and the AI books the appointment itself, the conversation ends with a short thank-you instead ofclosing. - Names, hours and similar details are written as placeholders such as
〇〇歯科,株式会社〇〇and〇〇(営業時間). Replace them before creating the agent. If any〇〇remains, the request fails with 422invalid_configanddetailslists what to replace. - The templates are written in Japanese, following real phone scripts for dental clinics, restaurant reservations, auto service shops and company front desks. The greeting tells callers that an AI is answering, that the call is recorded, and how to reach a person.
Testing in the dashboard#
On an agent's page in the dashboard, press Test in browser to talk to that agent with your browser's microphone. You can check what you built without connecting a phone number or your own Web app.
- Choose the tenant for the conversation. Tools and connections receive this tenant's customer ID (
external_id) and use its own connections. To keep tests apart from real customers, create a tenant for testing (the dashboard never creates one for you). - Press Start and allow the microphone. The AI greets you.
- While you talk, the page shows the transcript, the tools the AI called (name, arguments and result), the collected fields, the outcome and the elapsed time.
- Press End to hang up. The conversation is saved to call records (
channel: 'web'), and webhooks and post-call notifications are sent as for real conversations.
- The conversation uses the latest saved version. Unsaved changes are not used.
- Test conversations are charged like real ones: ¥10 per minute (excl. tax) is deducted from your balance, in the test environment too. Without balance, you can't start (402
balance_depleted). - Developers, admins and owners can use it.
Tips#
- Putting "at most two sentences per turn" (
「1 回の 発話は 2 文まで」 ) in personamakes the AI easier to follow on the phone. - Collect as few fields as you can. Many required fields make calls long.
- Put industry terms, product names, store names, staff names and place names in
vocabularyfor steadier recognition (names of people and places are misrecognized far less often once they are listed; see Recognition accuracy). - To try an agent quickly, use Test in browser in the dashboard (Testing in the dashboard). To try it from your own app, connect from the Web in the test environment.
Recognition accuracy#
We combine several AI models that are strong in Japanese and tune them for phone-line audio. We keep testing with phone audio that includes dialects and background noise. Register your business name, staff names and industry terms in vocabulary, and even hard-to-catch names are more likely to be recognized correctly.
| Standard Japanese | Dialects | |
|---|---|---|
| Recognition accuracy | 94% | 93% |
*Values from our internal tests measuring how accurately numbers and names are recognized. We measured under several conditions and show the highest value (254 patterns, 1,016 test runs; the values shown were measured at phone audio quality; dialects were measured on public Japanese speech data that includes dialects).