API reference
Every voicast API endpoint (/v1) and the voice connections: authentication, format, inputs, responses and errors.
Basics#
- URL:
https://api.voicast.jp/v1 - Auth:
Authorization: Bearer vk_live_…orvk_test_…. A key reads and writes only inside its environment (live or test) - Format: JSON. Times are Unix milliseconds; IDs are prefixed strings (
agt_,ten_,call_,sess_,con_) - Errors:
{ error, message, details?, request_id }. See Errors and limits - Request ID: every response has
x-request-id(req_…), the same asrequest_idin error bodies. Quote it when contacting support - Rate limit: 600 requests per minute per API key.
x-ratelimit-limit,x-ratelimit-remainingandx-ratelimit-reset(end of the window, Unix seconds) show what is left; over the limit you get 429 withRetry-After(seconds)
Create API keys under API keys in the dashboard (admin or above). Keep them on your server; never ship them to browsers or apps.
Endpoints#
| Method | Path | Description |
|---|---|---|
| POST | /v1/agents |
Create an agent |
| GET | /v1/agents |
List agents |
| GET | /v1/agents/{id} |
Get an agent |
| PUT | /v1/agents/{id} |
Update an agent (new version) |
| GET | /v1/agents/{id}/versions |
List versions |
| DELETE | /v1/agents/{id} |
Delete an agent |
| GET | /v1/agent-templates |
List agent templates |
| POST | /v1/tenants |
Create a tenant |
| GET | /v1/tenants |
List tenants |
| GET | /v1/tenants/{id} |
Get a tenant |
| PATCH | /v1/tenants/{id} |
Update a tenant |
| POST | /v1/tenants/{id}/secret |
Rotate the connection secret |
| DELETE | /v1/tenants/{id} |
Delete a tenant |
| POST | /v1/tenants/{id}/sip-credentials |
Create a SIP credential |
| GET | /v1/tenants/{id}/sip-credentials |
List SIP credentials |
| PATCH | /v1/tenants/{id}/sip-credentials/{credential} |
Update a SIP credential |
| DELETE | /v1/tenants/{id}/sip-credentials/{credential} |
Delete a SIP credential |
| GET | /v1/calls |
List calls |
| GET | /v1/calls/{id} |
Get a call |
| GET | /v1/calls/by-provider/{providerCallId} |
Get a call by your provider's ID |
| GET | /v1/calls/{id}/transcript |
Get a transcript |
| GET | /v1/calls/{id}/tool-calls |
List tool calls in a call |
| GET | /v1/calls/{id}/webhooks |
Get webhook delivery status for a call |
| GET | /v1/calls/{id}/recording |
Get a recording (MP3) |
| DELETE | /v1/calls/{id}/recording |
Delete a recording |
| GET | /v1/calls/{id}/recording/accesses |
Recording playback and deletion log |
| POST | /v1/sessions |
Create a Web/app session |
| GET | /v1/usage |
Usage breakdown |
| POST | /v1/webhooks/portal |
Webhook portal link |
| GET | /v1/billing |
Billing (balance, auto-recharge, per-minute price, payment method) |
| POST | /v1/billing/topups |
Top-up URL |
| GET | /v1/tools/secret |
In-call tools signing secret |
| POST | /v1/tools/secret/rotate |
Rotate the signing secret |
| GET | /v1/retention |
Retention period for call records and recordings |
| PATCH | /v1/retention |
Change the retention period |
| POST | /v1/tools/try |
Try a tool |
| GET | /v1/connectors |
List connectors |
| GET | /v1/connections |
List connections |
| POST | /v1/connections |
Create a connection (URL and API key) |
| GET | /v1/connections/{id} |
Get a connection |
| PATCH | /v1/connections/{id} |
Configure a connection |
| GET | /v1/connections/{id}/options |
Options for configuring a connection |
| DELETE | /v1/connections/{id} |
Delete a connection |
| GET | /v1/tenants/{id}/connections |
List a tenant's connections |
| POST | /v1/tenants/{id}/connect-links |
Create an embedded connect page link |
Voice connections (no API key):
| Kind | URL | Description |
|---|---|---|
| WebSocket | wss://voice.voicast.jp/ws |
Phone (Twilio Media Streams) |
| WebSocket | wss://voice.voicast.jp/ws/{sender} |
Phone (Telnyx, Plivo, Vonage, Exotel, Genesys, Asterisk) |
| POST | https://voice.voicast.jp/v1/webrtc/offer |
Web and apps (WebRTC offer) |
| PATCH | https://voice.voicast.jp/v1/webrtc/offer |
Add ICE candidates |
For MCP (https://api.voicast.jp/mcp), see MCP.
Create an agent#
POST /v1/agents| Input | Type | Description |
|---|---|---|
name |
string | Name (1–100 chars) |
config |
AgentConfig | The agent config (Agents) |
Returns 201 Agent (with config and tool_keys, version: 1). Invalid config returns 422 invalid_config with per-item details.
type Agent = {
id: string; name: string; version: number; config?: AgentConfig;
tool_keys?: { name: string; hint: string; updated_at: number }[]; // stored tool API keys (create, get and update only)
created_at: number; updated_at: number;
};
type AgentConfig = {
greeting: string; // first thing the AI says (up to 300 chars)
persona: string; // role and manner (up to 1,000 chars)
fields: { key: string; label: string; required?: boolean; type?: 'text' | 'phone' }[]; // 1–20
handoff_when: string[]; // handoff rules (up to 20)
closing: string; // closing when everything is collected (up to 300 chars)
closing_answered?: string; // closing when an FAQ answer settled the call
faq?: { q: string; a: string }[]; // up to 50
domain?: string; // line of business (recognition hint)
vocabulary?: string[]; // terms (recognition hints, up to 200)
voice?: string; // voice ID (default female-breezy)
speaking_rate?: number; // speaking rate (default 1.0)
max_call_minutes?: 5 | 10 | 15 | 30 | 60; // maximum length of one conversation in minutes (default 30)
tools?: AgentTool[]; // tools (up to 10)
connectors?: ConnectorEntry[]; // connections (up to 10)
};
type AgentTool = {
name: string; description: string; url: string; // url is https
method?: 'GET' | 'POST'; // default POST; signed tools must use POST
sign?: boolean; // default true (a signed tool.call); false sends the arguments as they are
auth?: { type: 'api_key'; header: string; value?: string }; // value is write-only (stored outside the config, never returned)
confirm?: boolean; // true: voicast asks the caller with a fixed confirmation message first, and tells the result in a fixed message
confirm_message?: string; // confirmation message for a confirm tool (up to 200 characters; {argument name} inserts the value)
done_message?: string; // message said when a confirm tool succeeds (up to 200 characters). An empty string "" says nothing
parameters?: { properties: Record<string, { type: 'string' | 'number' | 'integer' | 'boolean'; description?: string; enum?: string[] }>; required?: string[] };
};
type ConnectorEntry = { connection: string; actions: string[]; confirm?: string[] }; // a connection ID (con_…); actions are action names ('*' is not accepted)See Tools for how to write tools.
auth.value(the API key) is taken out ofconfigon save and stored encrypted per agent and tool name. It is not kept in the version history.tool_keyslists the stored keys:name(the tool name),hint(the last 4 characters; empty for keys shorter than 12 characters) andupdated_at. The key itself is never returned.- On later saves you can leave
valueout to keep the stored key. Enter it again after renaming a tool or changing its URL origin, and in another agent. Saving deletes the stored key of a tool whose URL origin changed or that was removed. Saving a tool withauthand no key returns 422invalid_config. '*'in aconnectorsentry'sactionsreturns 422invalid_config.
List agents#
GET /v1/agentsReturns { data: Agent[] } (without config).
Get an agent#
GET /v1/agents/{id}?version=Omit version (an integer ≥ 1) for the current version. Returns Agent with config and tool_keys; 404 if not found. tool_keys are the keys stored now, whichever version you get.
Update an agent#
PUT /v1/agents/{id}| Input | Type | Description |
|---|---|---|
name |
string | Optional. Unchanged if omitted |
config |
AgentConfig | The whole config (leave out auth.value for tools that keep their stored key) |
Returns Agent (the new version, with tool_keys). Calls in progress keep the version they started with.
List agent versions#
GET /v1/agents/{id}/versionsReturns { data: [{ version, created_at }] }, newest first.
Delete an agent#
DELETE /v1/agents/{id}Returns 204. 409 in_use if a tenant or a SIP credential uses it (details holds the counts, such as { "tenants": 1, "sip_credentials": 0 }). Call records are kept. The tools' stored API keys are deleted.
List agent templates#
GET /v1/agent-templatesReturns { data: AgentTemplate[] }: ready-made agents to start from (Templates). Replace the placeholders in config (such as 〇〇歯科) before passing it as config to POST /v1/agents. If any 〇〇 remains, the request fails with 422 invalid_config.
type AgentTemplate = {
id: string; // dental_clinic, restaurant, inquiry, take_message, car_service
name: string; name_en: string; // name (can also be the new agent's name)
description: string; description_en: string;
placeholders: { text: string; label: string; label_en: string; example: string }[]; // parts to replace (text appears in config) and a sample value
config: AgentConfig; // no integrations (connectors, tools), voice, speaking rate or language
};Create a tenant#
POST /v1/tenants| Input | Type | Description |
|---|---|---|
external_id |
string | Your customer ID. 1–100 chars of letters, digits and . _ : -; unique within the environment |
name |
string | Optional. Display name (up to 100 chars) |
agent_id |
string | Optional. Default agent |
pronunciations |
{ text, reading }[] |
Optional. How to read words aloud (the business or location name and so on). reading in hiragana or katakana (up to 100 chars including ー, spaces and 、text up to 100 chars, up to 20 entries. Each text only once |
Returns 201 Tenant plus secret (the connection secret vts_…, returned only here). 409 conflict if the external_id exists.
type Tenant = {
id: string; external_id: string; name: string; agent_id: string | null; status: 'active' | 'disabled';
pronunciations: { text: string; reading: string }[]; // the tenant's pronunciations ([] if none)
created_at: number;
};At the start of each conversation, the tenant's pronunciations are added to the agent's pronunciations (for the same text, the tenant's reading wins). When one agent serves many businesses, register the reading of the name that fills {{tenant_name}} on the tenant (for example { "text": "医療法人社団 東壽会", "reading": "いりょうほうじんしゃだん とうじゅかい" }). Invalid entries return 422 invalid_request with the problems in details.
List tenants#
GET /v1/tenantsReturns { data: Tenant[] }.
Get a tenant#
GET /v1/tenants/{id}Returns Tenant (the connection secret is never returned here).
Update a tenant#
PATCH /v1/tenants/{id}| Input | Type | Description |
|---|---|---|
name |
string | Optional |
agent_id |
string | null | Optional. null removes it |
status |
active, disabled |
Optional. disabled stops phone and Web/app connections |
pronunciations |
{ text, reading }[] |
Optional. Replaces the list. [] clears it |
Returns Tenant. Only the fields you pass change.
Rotate a tenant secret#
POST /v1/tenants/{id}/secretReturns { secret, previous_secret_expires_at }. The old secret keeps working for 24 hours.
Delete a tenant#
DELETE /v1/tenants/{id}Returns 204. The tenant can no longer connect. Call records are kept (recordings are deleted). You can create a tenant with the same external_id again. Its SIP credentials are deleted too.
Create a SIP credential#
POST /v1/tenants/{id}/sip-credentialsCreates the Digest username and password a PBX uses to send calls to sip.voicast.jp over SIP. See Phone.
| Input | Type | Description |
|---|---|---|
name |
string | Optional. A name to tell the PBX apart (up to 100 characters) |
agent_id |
string | Optional. The agent that answers calls with this credential. Defaults to the tenant's agent |
transfer_to |
string | Optional. Where the PBX transfers the call (asked with REFER) when the AI hands it to a person (outcome: handoff). An extension number (digits and * # +, up to 32 characters) or a SIP URI (sip:, sips:). Omit it to hang up without transferring |
Returns: 201 { id, username, password, realm, server, tenant_id, agent_id, name, transfer_to, created_at }. password is returned only here. username is the id (sipc_…), realm is voicast, and server is sip.voicast.jp.
List SIP credentials#
GET /v1/tenants/{id}/sip-credentialsReturns: { data: [...] }. Passwords are not returned.
Update a SIP credential#
PATCH /v1/tenants/{id}/sip-credentials/{credential}Changes name, agent_id (null for the tenant's agent) and transfer_to (empty or null for no transfer). Only the fields you pass change. The password doesn't change.
Returns: the credential (without the password).
Delete a SIP credential#
DELETE /v1/tenants/{id}/sip-credentials/{credential}Returns: 204. Calls using the credential are refused right away.
List calls#
GET /v1/calls?tenant_id=&outcome=&from=&to=&cursor=&limit=| Query | Description |
|---|---|
tenant_id |
Optional. Filter by tenant |
outcome |
Optional. Filter by outcome (completed, answered, handoff, hangup, time_limit, error; in_progress is a call that has no outcome yet) |
from, to |
Optional. Filter by start time. A date (YYYY-MM-DD, Japan time; to includes that day) or Unix milliseconds |
cursor |
Optional. Where to continue (pass the previous response's next_cursor as is) |
limit |
Optional. 1–100 (default 50) |
before |
Optional. The older way to page (calls that started before this started_at). It can skip calls that started in the same millisecond, so use cursor. Cannot be combined with cursor (422) |
Returns { data: Call[], has_more, next_cursor }, newest first. Calls deleted after the environment's retention period (30 days by default) are not included (Retention). While has_more is true, pass next_cursor as cursor to read on (next_cursor is null when has_more is false).
type Call = {
id: string; tenant_id: string; agent: { id: string; version: number };
provider_call_id: string | null; // Twilio CallSid, or the session ID for Web and apps
from: string | null; // caller's number (phone, when passed)
started_at: number; ended_at: number | null; duration_ms: number | null;
outcome: 'completed' | 'answered' | 'handoff' | 'hangup' | 'time_limit' | 'error' | null; reason: string | null;
fields: Record<string, string> | null;
summary: string | null; category: string | null; has_transcript: boolean;
channel: 'phone' | 'web'; output: 'audio' | 'text';
trial: boolean; // true for a call made with Test in browser in the dashboard
billed_yen: number | null; // what this call costs you (yen before tax, up to 3 decimals); null while in progress
has_recording: boolean; // true when the recording can be fetched
recording: { // null when the conversation was not recorded
status: 'available' | 'expired' | 'deleted';
content_type: 'audio/mpeg'; duration_ms: number | null; size_bytes: number | null;
expires_at: number; // retention deadline (saved time + the environment's retention period; moves if the period changes)
} | null;
};billed_yen is the amount taken from the balance (seconds × your per-minute price ÷ 60) (Pricing and billing).
Get a call#
GET /v1/calls/{id}Returns Call. Calls deleted after the environment's retention period return 404 not_found, like calls in other environments (Retention). The same applies to the transcript, tool calls, delivery status and recording.
Get a call by provider ID#
GET /v1/calls/by-provider/{providerCallId}Look up a call by Twilio CallSid (CA…) or session ID (sess_…), for example from Twilio's <Connect> action. Returns Call; 404 if there is no record.
Get a transcript#
GET /v1/calls/{id}/transcriptReturns { call_id, turns: [{ role: 'assistant' | 'user', text }] }. Created after the call ends; 404 if none.
List tool calls in a call#
GET /v1/calls/{id}/tool-callsReturns { data: [{ name, status, error, started_at }] } in call order. status is ok, error or running; error is the failure kind (timeout, not_connected and so on; null when it succeeded or is running). Arguments passed to the tool and the results it returned are not returned because they contain personal information. Post-call notifications (Slack and so on) are not included.
Get webhook delivery status for a call#
GET /v1/calls/{id}/webhooksThe delivery status of each event (call.*) sent for the call, and of each post-call notification to Slack, Chatwork or Microsoft Teams (voicast.notify; see Connections). This is the same data as Webhook deliveries on the call details page in the dashboard.
Returns:
type CallWebhooks = {
enabled: boolean; // whether this environment sends webhooks
data: {
event_type: string; // call.started and so on; voicast.notify for post-call notifications
connector: string | null; // connector of a post-call notification (slack, chatwork, teams); null for events
connection_id: string | null; // connection of a post-call notification (con_…); null for events
status: 'success' | 'retrying' | 'failed' | 'pending' | 'cancelled' | 'no_endpoint' | 'rejected' | 'unknown';
attempts: number; // attempts, summed over endpoints
last_response_status: number | null; // HTTP status of the latest attempt (null if no response or not attempted yet)
last_attempt_at: number | null;
next_attempt_at: number | null; // next retry (while retrying)
sent_at: number; // when the delivery was accepted
endpoints: { // result per endpoint
url: string | null; // null for polling endpoints
status: 'success' | 'retrying' | 'failed' | 'pending' | 'held' | 'cancelled' | 'waiting';
attempts: number; last_response_status: number | null;
last_attempt_at: number | null; next_attempt_at: number | null;
}[];
}[];
};status |
Meaning |
|---|---|
success |
Succeeded (delivered to every endpoint) |
retrying |
Retrying (failed endpoints are retried with backoff) |
failed |
Failed (an endpoint used up its retries) |
pending |
Pending |
cancelled |
Cancelled (a payload transformation chose not to send) |
no_endpoint |
No endpoint (there is no endpoint, or none receives this event) |
rejected |
Rejected (the delivery was not accepted, for example because a sending limit was reached) |
unknown |
Unknown (the status couldn't be read: the log is past its retention period, or the service is temporarily unreachable) |
Per-endpoint status can also be held (the endpoint is paused) or waiting (a polling endpoint hasn't fetched it yet).
Environments that don't send webhooks return enabled: false. If no events were sent, data is empty. Only events whose status couldn't be read become unknown; the others are still returned. To see the full delivery logs and retry, use the endpoint registration page (Create a webhook portal link).
Get a recording#
GET /v1/calls/{id}/recordingReturns the recording audio (audio/mpeg). Supports Range (206 with Content-Range; 416 outside the recording). Cache-Control: private, no-store. 404 not_found if the conversation was not recorded, 410 recording_expired after the retention period, 410 recording_deleted after deletion. Calls in other environments return 404. See Results.
Delete a recording#
DELETE /v1/calls/{id}/recordingReturns 204. Cannot be undone. The call record and transcript are kept. If the recording is already gone, returns 410 (expired or deleted) or 404 (not recorded). In the dashboard, admins and owners can delete recordings.
Recording access log#
GET /v1/calls/{id}/recording/accessesReturns { data: [{ action: 'play' | 'delete', actor: { kind: 'user' | 'api_key', id, email }, at }] } (newest first, up to 100). A playback is logged when the recording is read from the start (no Range, or a range from 0). In the dashboard, admin or above.
Create a session#
POST /v1/sessions| Input | Type | Description |
|---|---|---|
tenant_id |
string | Tenant ID |
agent_id |
string | Optional. Defaults to the tenant's agent |
output |
audio, text |
Optional. Default audio |
Returns 201 { id, tenant_id, agent_id, output, client_token, expires_at, webrtc_url, ice_servers }. client_token (vct_…) lasts 2 minutes and works once. Pass ice_servers ([{ urls, username?, credential? }]) to RTCPeerConnection's iceServers as is (STUN, plus short-lived TURN when available). Give only client_token, webrtc_url and ice_servers to the browser or app.
Errors: 402 balance_depleted (zero balance), 409 tenant_disabled, 422 no_agent or invalid_request.
Get usage#
GET /v1/usage?from=&to=&group_by=&channel=&tenant_id=&external_id=| Query | Description |
|---|---|
from, to |
A date (YYYY-MM-DD, Japan time; to includes that day) or Unix milliseconds (to exclusive). Defaults to the start of this month until now. Up to 366 days |
group_by |
Optional. tenant, day or channel |
channel |
Optional. Only phone or web |
tenant_id, external_id |
Optional. Only this tenant (external_id matches existing tenants). 0 if nothing matches |
Returns:
type Usage = {
environment: 'live' | 'test'; from: number; to: number;
group_by: 'tenant' | 'day' | 'channel' | null;
filter: { channel: 'phone' | 'web' | null; tenant_id: string | null; external_id: string | null };
unit_price_yen: number;
total: { calls: number; seconds: number; minutes: number; amount_yen: number };
data: (({ tenant: { id: string; external_id: string; name: string } } | { day: string } | { channel: 'phone' | 'web' })
& { calls: number; seconds: number; minutes: number; amount_yen: number })[]; // [] without group_by
note: string;
};Filters can be combined (group_by=tenant&channel=phone gives phone minutes per tenant). Invalid values return 422. Calls that ended within the period are counted, including calls already deleted after the retention period, whenever they were deleted (they are kept as daily totals in Japan time, so for periods older than the retention period a Unix-millisecond boundary in the middle of a day counts that day's calls at the start of the day). amount_yen is an estimate excluding tax (Pricing and billing).
Create a webhook portal link#
POST /v1/webhooks/portal| Input | Type | Description |
|---|---|---|
frame_origin |
string | Optional. Parent origin when embedding in an iframe |
locale |
ja, en |
Optional. Page language (default ja) |
Returns 201 { url, expires_at } (valid for 15 minutes): a page to register endpoint URLs, choose events and see signing secrets (Results). 503 unavailable if webhook delivery is not available.
Get billing#
GET /v1/billingReturns the billing state of the API key's organization (shared by the live and test environments), the same as Billing in the dashboard.
type Billing = {
organization_id: string; month: string; // this month (Japan time, YYYY-MM)
contract: { per_minute_yen: number }; // your contract price (payment is by card top-up only)
has_card: boolean; // a card is saved for auto-recharge
usage: { calls: number; seconds: number; minutes: number }; // this month's calls (live and test)
estimate_yen: number; // taken from the balance this month
balance: { yen: number; milli_yen: number; depleted: boolean; next_expiry: { yen: number; at: number } | null };
auto_recharge: { enabled: boolean; threshold_yen: number; amount_yen: number; monthly_cap_yen: number | null;
recharged_this_month_yen: number; failures: number; max_failures: number };
topup: { min_yen: number; max_yen: number; quick_yen: number[]; credit_months: number };
spending_cap_yen: number | null; cap_reached: boolean; // auto-recharge monthly cap and whether it was reached
tax: 'excluded'; tax_rate: number;
// also price, stripe_enabled, threshold
};Create a top-up#
POST /v1/billing/topups| Input | Type | Description |
|---|---|---|
amount_yen |
integer | Amount in yen before tax, 500–300,000 |
Returns 201 { url, amount_yen, tax_yen }. url is a Stripe payment page: open it in a browser and pay, and the amount is added to the balance. 422 outside the range. Auto-recharge, the monthly cap and the card are changed in the dashboard (Pricing and billing).
Get the tools signing secret#
GET /v1/tools/secretReturns { secret, previous_secret_expires_at }. secret (whsec_…) signs the environment's in-call tool requests. previous_secret_expires_at is when the previous secret stops being used after a rotation (null if none).
Rotate the tools signing secret#
POST /v1/tools/secret/rotateReturns { secret, previous_secret_expires_at }. For 24 hours after a rotation, requests are signed with both the new and the previous secret; switch your server to the new one within that time.
Retention#
GET /v1/retentionReturns { retention_days, choices }. retention_days is the retention period in days for call records and recordings in the key's environment, and choices lists the allowed values ([1, 7, 14, 30]). The default is 30. Call records count from the end of the call and recordings from when they were saved (Retention).
Change the retention period#
PATCH /v1/retention| Field | Type | Description |
|---|---|---|
retention_days |
integer | One of 1, 7, 14 or 30 (days). It cannot be longer than 30 days |
Returns { retention_days, choices }. Other values return 422 invalid_request. Only the key's environment changes (live and test are separate). In the dashboard, admins change it in the environment settings.
If you shorten it, call records and recordings past the new period are deleted at the next daily cleanup and cannot be restored. Recordings not yet expired get recording.expires_at = saved time + the new period. If you lengthen it, records not yet deleted are kept until the new period ends. The usage breakdown (GET /v1/usage) and billing do not change.
Try a tool#
POST /v1/tools/tryCalls an agent tool once and returns what it answered. It runs exactly as when the AI calls it during a call (signature, API key, 8-second limit). There is no conversation charge and nothing is recorded as a call.
| Input | Type | Description |
|---|---|---|
tool |
string | AgentTool | The name of a saved tool (requires agent_id), or an unsaved tool definition |
agent_id |
string | Optional. The agent with the tool (required when tool is a name). Its stored key is used only when tool is a name. A definition with auth and no auth.value returns 422 missing_api_key |
arguments |
object | Optional. The tool's arguments (default {}) |
tenant_id |
string | Optional. The tenant sent as call.tenant. Without it, call.tenant is null |
type ToolTryResult = {
tool: string; // the tool name
ok: boolean;
result?: unknown; // on success: what the AI would get
error?: string; // on failure (unauthorized, not_found, upstream_error, timeout, invalid_arguments, missing_api_key)
message?: string;
status: number | null; // the tool's HTTP status (null with no response)
body: string | null; // the tool's response body (up to 10,000 characters; null with no response)
truncated: boolean; // true when body was cut
duration_ms: number;
};- A failing tool still returns 200 with
ok: false. Invalidtool,agent_idortenant_idreturns 422invalid_request. confirmtools are called without asking. Tools that change data really change it.- Signed requests carry
test: true;call.channelistestandcall.idistry_…. - Up to 30 per minute per environment; beyond that, 429
rate_limitedwithRetry-After.
List connectors#
GET /v1/connectorsReturns { data: Connector[] }. See Connections for the available connectors.
type Connector = {
id: string; name: string; description: string;
category: 'scheduling' | 'crm' | 'notify' | 'custom'; auth: 'oauth2' | 'api_key' | 'webhook_url';
available: boolean; // usable on this voicast
needs_setup: boolean; // needs configuration after connecting
notify: boolean; // posts a notification after each call
env_only: boolean; // environment connections only
inputs: { name: string; type: 'text' | 'password' | 'url' | 'number' }[];
actions: { name: string; tool: string; description: string; confirm: boolean }[]; // tool is the name shown to the AI
};List connections#
GET /v1/connectionsReturns { data: Connection[] }. Deleted connections are not listed. Narrow it to one tenant's connections with ?tenant_id=ten_…, or to environment connections with an empty ?tenant_id=.
type Connection = {
id: string; connector: string; tenant_id: string | null;
label: string; // the other side (api.example.com…)
status: 'active' | 'needs_setup' | 'needs_reauth';
config: object; created_by: string | null; created_at: number; updated_at: number;
};Create a connection (URL and API key)#
POST /v1/connections| Input | Type | Description |
|---|---|---|
connector |
http |
The URL-and-API-key connector |
secret |
string | The API key (1–2,000 chars) |
input |
object | { base_url, header } (the API's base URL and the header that carries the key) |
Returns 201 Connection (needs_setup). Before saving, voicast checks the URL and header name; invalid ones return 422 verify_failed. It is environment-only, so passing tenant_id returns 422 invalid_request.
Get a connection#
GET /v1/connections/{id}Returns Connection.
Configure a connection#
PATCH /v1/connections/{id}| Input | Type | Description |
|---|---|---|
config |
object | Connector-specific settings (tools for URL and API key). Only the fields you pass change |
Returns Connection. A needs_setup connection becomes active. Invalid settings return 422 invalid_config. See Connections for the settings.
Connection options#
GET /v1/connections/{id}/optionsAsks the provider for the choices available when configuring. Google Calendar returns { calendars: { id, name, primary }[] }, kintone { apps: { id, name }[], fields: { code, label }[] } (the fields of the app chosen with ?app=), LINE WORKS { users: { id, name }[] }. For Google Sheets it returns { spreadsheets: { id, name }[], sheets: string[], headers: string[] } (spreadsheets voicast created, the sheets of the chosen spreadsheet and the row-1 headers of the chosen sheet); pass your choices with ?spreadsheet= and ?sheet=. URL-and-API-key (http) connections have no choices and return {} (define their tools in config.tools). 409 needs_reauth if the connection is broken.
Delete a connection#
DELETE /v1/connections/{id}Returns 204. The provider's token is revoked too.
List a tenant's connections#
GET /v1/tenants/{id}/connectionsReturns { data: Connection[] }: the tenant's own connections (those the business connected on the embedded connect page).
Create a connect page link#
POST /v1/tenants/{id}/connect-links| Input | Type | Description |
|---|---|---|
connectors |
string[] | Optional. Connectors to show on the page (all available ones if omitted; custom connections cannot be shown) |
frame_origin |
string | Optional. The origin (https) of the parent page that embeds it in an iframe |
Returns 201 { url, expires_at }. The link expires after 15 minutes. See Connections for how to use it.
Phone (Twilio Media Streams)#
wss://voice.voicast.jp/wsThe target of Twilio's <Connect><Stream>. Pass these as <Parameter>s:
| Parameter | Description |
|---|---|
tenant |
Tenant ID |
secret |
The tenant's connection secret (vts_…) |
agent |
Optional. Agent ID |
from |
Optional. The caller's number |
The stream is closed immediately when the secret is wrong, the tenant is disabled or calls are refused for billing reasons. See Phone.
WebRTC offer#
POST https://voice.voicast.jp/v1/webrtc/offer| Input | Type | Description |
|---|---|---|
sdp, type |
string | The WebRTC offer |
token |
string | The session's client_token (RTVI clients may send it as requestData.token) |
pc_id, restart_pc |
string, boolean | Renegotiation only (no token needed) |
Returns { sdp, type, pc_id }. 403 when the token is wrong, expired or used. When calls are refused for billing reasons, 402 with error balance_depleted in the body, like POST /v1/sessions. When the voice server is busy and at its limit of concurrent calls, 503 with error busy (Retry-After: 30; the token is not used, so you can reconnect with the same token).
Once connected, send RTVI client-ready on the data channel, then a ping string every second (Web and apps).
ICE candidates#
PATCH https://voice.voicast.jp/v1/webrtc/offer| Input | Type | Description |
|---|---|---|
pc_id |
string | pc_id from the offer response |
candidates |
array | [{ candidate, sdp_mid, sdp_mline_index }] |
Returns { ok: true }. 404 for an unknown pc_id.