All pages

Docs

API reference

Every voicast API endpoint (/v1) and the voice connections: authentication, format, inputs, responses and errors.

View as Markdown

Basics#

  • URL: https://api.voicast.jp/v1
  • Auth: Authorization: Bearer vk_live_… or vk_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 as request_id in error bodies. Quote it when contacting support
  • Rate limit: 600 requests per minute per API key. x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset (end of the window, Unix seconds) show what is left; over the limit you get 429 with Retry-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.

ts
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 of config on save and stored encrypted per agent and tool name. It is not kept in the version history.
  • 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. The key itself is never returned.
  • On later saves you can leave value out 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 with auth and no key returns 422 invalid_config.
  • '*' in a connectors entry's actions returns 422 invalid_config.

List agents#

GET /v1/agents

Returns { 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}/versions

Returns { 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-templates

Returns { 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.

ts
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.

ts
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/tenants

Returns { 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}/secret

Returns { 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-credentials

Creates 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-credentials

Returns: { 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).

ts
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}/transcript

Returns { 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-calls

Returns { 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}/webhooks

The 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:

ts
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}/recording

Returns 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}/recording

Returns 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/accesses

Returns { 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:

ts
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).

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/billing

Returns the billing state of the API key's organization (shared by the live and test environments), the same as Billing in the dashboard.

ts
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/secret

Returns { 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/rotate

Returns { 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/retention

Returns { 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/try

Calls 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
ts
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. Invalid tool, agent_id or tenant_id returns 422 invalid_request.
  • confirm tools are called without asking. Tools that change data really change it.
  • Signed requests carry test: true; call.channel is test and call.id is try_….
  • Up to 30 per minute per environment; beyond that, 429 rate_limited with Retry-After.

List connectors#

GET /v1/connectors

Returns { data: Connector[] }. See Connections for the available connectors.

ts
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/connections

Returns { 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=.

ts
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}/options

Asks 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}/connections

Returns { data: Connection[] }: the tenant's own connections (those the business connected on the embedded connect page).

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/ws

The 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.