API リファレンス
voicast の
基本#
- URL:
https://api.voicast.jp/v1 - 認証:
Authorization: Bearer vk_live_…かvk_test_…。キーの 環境 (本番か テスト) の 中だけを 読み 書きします - 形式: JSON。
時刻は Unix ミリ秒、 ID は 接頭辞付きの 文字列 ( agt_・ten_・call_・sess_・con_) - エラー:
{ error, message, details?, request_id }。種類はエラーと 制限 - 呼び出しの
ID : すべての応答に x-request-id( req_…)が 付きます。 エラーの 本文の request_idと同じです。 問い合わせの ときに 伝えてください - 回数の
上限 : API キーごとに1 分 600 回。 応答の x-ratelimit-limit・x-ratelimit-remaining・x-ratelimit-reset(枠の 終わり、 Unix 秒) で 残りが 分かり、 超えると 429 と Retry-After(秒)
API キーは
エンドポイント#
音声の
| 方式 | URL | 内容 |
|---|---|---|
| WebSocket | wss://voice.voicast.jp/ws |
電話 |
| WebSocket | wss://voice.voicast.jp/ws/{相手} |
電話 |
| POST | https://voice.voicast.jp/v1/webrtc/offer |
Web・アプリ |
| PATCH | https://voice.voicast.jp/v1/webrtc/offer |
ICE の |
MCPhttps://api.voicast.jp/mcp)
エージェントの作成#
POST /v1/agents| 入力 | 型 | 内容 |
|---|---|---|
name |
string | 名前 |
config |
AgentConfig | エージェント設定 |
返り: 201 Agentconfig とtool_keys 付き、version: 1)invalid_configdetails に
type Agent = {
id: string; name: string; version: number; config?: AgentConfig;
tool_keys?: { name: string; hint: string; updated_at: number }[]; // 預かっているツールの API キー(作成・取得・変更の応答だけ)
created_at: number; updated_at: number;
};
type AgentConfig = {
greeting: string; // 最初のあいさつ(300 文字まで)
persona: string; // 役割と話し方(1,000 文字まで)
fields: { key: string; label: string; required?: boolean; type?: 'text' | 'phone' }[]; // 1〜20 個
handoff_when: string[]; // 担当者に転送するときの条件(20 個まで)
closing: string; // 聞き取りが終わったときの締め(300 文字まで)
closing_answered?: string; // よくある質問で用が済んだときの締め
faq?: { q: string; a: string }[]; // 50 個まで
domain?: string; // 業種(音声認識の手がかり)
vocabulary?: string[]; // 用語(音声認識の手がかり、200 個まで)
voice?: string; // 声の ID(既定 female-breezy)
speaking_rate?: number; // 話す速さ(既定 1.0)
max_call_minutes?: 5 | 10 | 15 | 30 | 60; // 1 回の会話の長さの上限(分。既定 30)
tools?: AgentTool[]; // 会話中のツール(10 個まで)
connectors?: ConnectorEntry[]; // 連携(10 個まで)
};
type AgentTool = {
name: string; description: string; url: string; // url は https
method?: 'GET' | 'POST'; // 省くと POST。署名付きのツールは POST だけ
sign?: boolean; // 省くと true(voicast の署名を付けた tool.call)。false は引数をそのまま送る
auth?: { type: 'api_key'; header: string; value?: string }; // value は送るだけ(保存すると設定から外して預かり、返さない)
confirm?: boolean; // true なら、voicast が決まった確認の文で相手の同意を伺ってから使い、結果も決まった文で伝える
confirm_message?: string; // confirm のツールの確認の文(200 文字まで。{引数の名前} に値を差し込む)
done_message?: string; // confirm のツールが済んだときの文(200 文字まで)。空文字 "" なら言わない
parameters?: { properties: Record<string, { type: 'string' | 'number' | 'integer' | 'boolean'; description?: string; enum?: string[] }>; required?: string[] };
};
type ConnectorEntry = { connection: string; actions: string[]; confirm?: string[] }; // 連携の ID(con_…)。actions は操作の名前('*' は使えない)ツールの
auth.value(API キー) は、 保存すると configから外し、 エージェントと ツールの 名前ごとに 暗号化して 預かります。 バージョンの 履歴には 残りません。 tool_keysは、預かっている キーの name(ツールの 名前) ・ hint(末尾 4文字。 12文字未満の キーは 空) ・ updated_atです。値は 返しません。 - 2回目からの
保存では valueを省けます (預けた キーを 使います) 。 ツールの 名前や URL の オリジンを 変えた ときと、 別の エージェントでは 入れ直します。 オリジンを 変えた ツールと 外した ツールの 預けた キーは、 保存の ときに 削除します。 キーの 無いまま authのツールを 保存すると 422 invalid_config。 connectorsのactionsに'*'を書くと 422 invalid_configです。
エージェントの一覧#
GET /v1/agents返り: { data: Agent[] }config なし)
エージェント設定の取得#
GET /v1/agents/{id}?version=versionAgentconfig とtool_keys 付き)tool_keys は、
エージェント設定の変更#
PUT /v1/agents/{id}| 入力 | 型 | 内容 |
|---|---|---|
name |
string | 任意。 |
config |
AgentConfig | 全体をauth.value を |
返り: Agenttool_keys 付き)
エージェント設定のバージョンの一覧#
GET /v1/agents/{id}/versions返り: { data: [{ version, created_at }] }
エージェントの削除#
DELETE /v1/agents/{id}返り: 204。in_usedetails に{ "tenants": 1, "sip_credentials": 0 })
エージェントのテンプレート#
GET /v1/agent-templates返り: { data: AgentTemplate[] }。placeholders にconfig のPOST /v1/agents のconfig にinvalid_config です。
type AgentTemplate = {
id: string; // dental_clinic・restaurant・inquiry・take_message・car_service
name: string; name_en: string; // 名前(作るエージェントの名前にも使える)
description: string; description_en: string;
placeholders: { text: string; label: string; label_en: string; example: string }[]; // 変更する箇所(text が config の中にある)と、変更した例
config: AgentConfig; // 連携(connectors・tools)・声・話す速さ・言語は入らない
};テナントの作成#
POST /v1/tenants| 入力 | 型 | 内容 |
|---|---|---|
external_id |
string | サービスの. _ : - の |
name |
string | 任意。 |
agent_id |
string | 任意。 |
pronunciations |
{ text, reading }[] |
任意。reading はtext はtext は |
返り: 201 Tenant とsecretvts_…。external_id がconflict。
type Tenant = {
id: string; external_id: string; name: string; agent_id: string | null; status: 'active' | 'disabled';
pronunciations: { text: string; reading: string }[]; // テナントの読み(無ければ [])
created_at: number;
};会話のpronunciations にpronunciations をtext なら{{tenant_name}} に{ "text": "医療法人社団 東壽会", "reading": "いりょうほうじんしゃだん とうじゅかい" })invalid_requestdetails に
テナントの一覧#
GET /v1/tenants返り: { data: Tenant[] }。
テナントの取得#
GET /v1/tenants/{id}返り: Tenant
テナントの変更#
PATCH /v1/tenants/{id}| 入力 | 型 | 内容 |
|---|---|---|
name |
string | 任意 |
agent_id |
string | null | 任意。null で |
status |
active・disabled |
任意。disabled で |
pronunciations |
{ text, reading }[] |
任意。[] で |
返り: Tenant。
接続シークレットの再発行#
POST /v1/tenants/{id}/secret返り: { secret, previous_secret_expires_at }。
テナントの削除#
DELETE /v1/tenants/{id}返り: 204。external_id で
SIP の接続情報の作成#
POST /v1/tenants/{id}/sip-credentialsPBX からsip.voicast.jp に
| 入力 | 型 | 内容 |
|---|---|---|
name |
string | 任意。 |
agent_id |
string | 任意。 |
transfer_to |
string | 任意。outcome: handoff)REFER で* # +、sip:・sips:) |
返り: 201 { id, username, password, realm, server, tenant_id, agent_id, name, transfer_to, created_at }。password はusername はidsipc_…)realm はvoicast、server はsip.voicast.jp です。
SIP の接続情報の一覧#
GET /v1/tenants/{id}/sip-credentials返り: { data: [...] }。
SIP の接続情報の変更#
PATCH /v1/tenants/{id}/sip-credentials/{credential}name・agent_idnull でtransfer_tonull で
返り: 接続情報
SIP の接続情報の削除#
DELETE /v1/tenants/{id}/sip-credentials/{credential}返り: 204。
会話の一覧#
GET /v1/calls?tenant_id=&outcome=&from=&to=&cursor=&limit=| クエリ | 内容 |
|---|---|
tenant_id |
任意。 |
outcome |
任意。completed・answered・handoff・hangup・time_limit・error。in_progress は |
from・to |
任意。YYYY-MM-DD、to は |
cursor |
任意。next_cursor を |
limit |
任意。 |
before |
任意。started_at よりcursor をcursor と |
返り: { data: Call[], has_more, next_cursor }has_more がtrue のnext_cursor をcursor にhas_more がfalse ならnext_cursor はnull)
type Call = {
id: string; tenant_id: string; agent: { id: string; version: number };
provider_call_id: string | null; // Twilio の CallSid、Web・アプリはセッションの ID
from: string | null; // かけてきた番号(電話で from を渡したとき)
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
billed_yen: number | null; // この会話の利用料(税抜の円、小数 3 桁まで)。会話中は null
has_recording: boolean; // 録音を取れるとき true
recording: { // 録音していない会話は null
status: 'available' | 'expired' | 'deleted';
content_type: 'audio/mpeg'; duration_ms: number | null; size_bytes: number | null;
expires_at: number; // 保存の期限(保存してから環境の保存期間。保存期間を変えるとずれる)
} | null;
};billed_yen は、
会話の取得#
GET /v1/calls/{id}返り: Call。not_found
サービスの側の ID で会話を引く#
GET /v1/calls/by-provider/{providerCallId}Twilio のCallSidCA…)sess_…)<Connect> のaction でCall。
文字起こし#
GET /v1/calls/{id}/transcript返り: { call_id, turns: [{ role: 'assistant' | 'user', text }] }。
会話中のツールの呼び出し#
GET /v1/calls/{id}/tool-calls返り: { data: [{ name, status, error, started_at }] }status はokerrorrunningerror はtimeout・not_connected など。null)
会話の Webhook の送信の状態#
GET /v1/calls/{id}/webhooksそのcall.*)voicast.notify。連携)
返り:
type CallWebhooks = {
enabled: boolean; // この環境が Webhook を送っているか
data: {
event_type: string; // call.started など。会話のあとの通知は voicast.notify
connector: string | null; // 会話のあとの通知の連携先(slack・chatwork・teams)。イベントは null
connection_id: string | null; // 会話のあとの通知の連携(con_…)。イベントは null
status: 'success' | 'retrying' | 'failed' | 'pending' | 'cancelled' | 'no_endpoint' | 'rejected' | 'unknown';
attempts: number; // 試行の回数(送信先ごとの合計)
last_response_status: number | null; // 最後の試行の HTTP の状態コード(応答が無かった・まだ試していないときは null)
last_attempt_at: number | null;
next_attempt_at: number | null; // 次の再送(再送待ちのとき)
sent_at: number; // 送信を受け付けた時刻
endpoints: { // 送信先ごとの結果
url: string | null; // 取りに来る送信先は null
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 |
意味 |
|---|---|
success |
成功 |
retrying |
再送待ち |
failed |
失敗 |
pending |
送信待ち |
cancelled |
取りやめ |
no_endpoint |
送信先なし |
rejected |
拒否 |
unknown |
不明 |
送信先ごとのstatus には、heldwaiting
Webhook をenabled: false です。data はunknown に
録音の取得#
GET /v1/calls/{id}/recording返り: 録音のaudio/mpeg)Range にContent-Range。Cache-Control: private, no-store。not_found、recording_expired、recording_deleted。
録音の削除#
DELETE /v1/calls/{id}/recording返り: 204。
録音の再生と削除の記録#
GET /v1/calls/{id}/recording/accesses返り: { data: [{ action: 'play' | 'delete', actor: { kind: 'user' | 'api_key', id, email }, at }] }Range が
セッションの作成#
POST /v1/sessions| 入力 | 型 | 内容 |
|---|---|---|
tenant_id |
string | テナントの |
agent_id |
string | 任意。 |
output |
audio・text |
任意。audio |
返り: 201 { id, tenant_id, agent_id, output, client_token, expires_at, webrtc_url, ice_servers }。client_tokenvct_…)ice_servers[{ urls, username?, credential? }])RTCPeerConnection のiceServers にclient_token・webrtc_url・ice_servers だけを
エラー: 402 balance_depletedtenant_disabled、no_agent・invalid_request。
利用の内訳#
GET /v1/usage?from=&to=&group_by=&channel=&tenant_id=&external_id=| クエリ | 内容 |
|---|---|
from・to |
日付YYYY-MM-DD、to はto は |
group_by |
任意。tenant・day・channel |
channel |
任意。phone・web に |
tenant_id・external_id |
任意。external_id は |
返り:
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 })[]; // group_by が無ければ []
note: string;
};絞り込みはgroup_by=tenant&channel=phone でamount_yen は
Webhook の設定画面のリンク#
POST /v1/webhooks/portal| 入力 | 型 | 内容 |
|---|---|---|
frame_origin |
string | 任意。 |
locale |
ja・en |
任意。ja) |
返り: 201 { url, expires_at }unavailable。
請求の状態#
GET /v1/billingAPI キーの
type Billing = {
organization_id: string; month: string; // 今月(日本時間、YYYY-MM)
contract: { per_minute_yen: number }; // 契約の 1 分の値段(お支払いはカードのチャージだけ)
has_card: boolean; // オートチャージに使うカードを保存したか
usage: { calls: number; seconds: number; minutes: number }; // 今月の会話(本番とテストの合計)
estimate_yen: number; // 今月に残高から引いた額
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; // オートチャージの月の上限と、それに届いたか
tax: 'excluded'; tax_rate: number;
// ほかに price・stripe_enabled・threshold
};チャージ#
POST /v1/billing/topups| 入力 | 型 | 内容 |
|---|---|---|
amount_yen |
integer | チャージの |
返り: 201 { url, amount_yen, tax_yen }。url は
ツールの署名シークレット#
GET /v1/tools/secret返り: { secret, previous_secret_expires_at }。secretwhsec_…)previous_secret_expires_at はnull)
ツールの署名シークレットの再発行#
POST /v1/tools/secret/rotate返り: { secret, previous_secret_expires_at }。
保存期間#
GET /v1/retention返り: { retention_days, choices }。retention_days はchoices は[1, 7, 14, 30])
保存期間の変更#
PATCH /v1/retention| 項目 | 型 | 内容 |
|---|---|---|
retention_days |
integer | 1・7・14・30 の |
返り: { retention_days, choices }。invalid_request。
短くrecording.expires_at は、GET /v1/usage)
ツールを試す#
POST /v1/tools/tryエージェントの
| 入力 | 型 | 内容 |
|---|---|---|
tool |
string | AgentTool | 保存したagent_id が |
agent_id |
string | 任意。tool がauth がauth.value がmissing_api_key |
arguments |
object | 任意。{}) |
tenant_id |
string | 任意。call.tenant にcall.tenant はnull |
type ToolTryResult = {
tool: string; // ツールの名前
ok: boolean;
result?: unknown; // 成功のとき、AI に渡すもの
error?: string; // 失敗のとき(unauthorized・not_found・upstream_error・timeout・invalid_arguments・missing_api_key)
message?: string;
status: number | null; // 相手の HTTP の状態(応答が無ければ null)
body: string | null; // 相手の本文(10,000文字まで。応答が無ければ null)
truncated: boolean; // body を切ったとき true
duration_ms: number;
};- ツールが
失敗しても、 応答は 200 の ok: falseです。tool・agent_id・tenant_idの誤りは 422 invalid_request。 confirmのツールも 確認なしで 呼びます。 書き換える ツールは 実際に 書き換わります。 - 署名付きの
ツールの 本文には test: trueが付き、 call.channelはtest、call.idはtry_…です。 - 回数は
環境ごとに 1分 30回までです。 超えると 429 rate_limitedとRetry-After。
連携先の一覧#
GET /v1/connectors返り: { data: Connector[] }。
type Connector = {
id: string; name: string; description: string;
category: 'scheduling' | 'crm' | 'notify' | 'custom'; auth: 'oauth2' | 'api_key' | 'webhook_url';
available: boolean; // この voicast で使える
needs_setup: boolean; // 連携したあとに設定が要る
notify: boolean; // 会話のあとに通知する
env_only: boolean; // 環境の連携だけ
inputs: { name: string; type: 'text' | 'password' | 'url' | 'number' }[];
actions: { name: string; tool: string; description: string; confirm: boolean }[]; // tool は AI に見せる名前
};連携の一覧#
GET /v1/connections返り: { data: Connection[] }。?tenant_id=ten_… で?tenant_id=
type Connection = {
id: string; connector: string; tenant_id: string | null;
label: string; // 相手の名前(api.example.com など)
status: 'active' | 'needs_setup' | 'needs_reauth';
config: object; created_by: string | null; created_at: number; updated_at: number;
};連携の作成(URL と API キー)#
POST /v1/connections| 入力 | 型 | 内容 |
|---|---|---|
connector |
http |
URL と |
secret |
string | API キー |
input |
object | { base_url, header } |
返り: 201 Connectionneeds_setup)verify_failed。tenant_id をinvalid_request。
連携の取得#
GET /v1/connections/{id}返り: Connection。
連携の設定#
PATCH /v1/connections/{id}| 入力 | 型 | 内容 |
|---|---|---|
config |
object | 連携先ごとのtools) |
返り: Connection。needs_setup)active にinvalid_config。
連携の設定の選択肢#
GET /v1/connections/{id}/options連携先に{ calendars: { id, name, primary }[] }、{ apps: { id, name }[], fields: { code, label }[] }?app= で{ users: { id, name }[] }、{ spreadsheets: { id, name }[], sheets: string[], headers: string[] }?spreadsheet= と?sheet= でhttp){} をconfig.tools にneeds_reauth。
連携の解除#
DELETE /v1/connections/{id}返り: 204。
テナントの連携の一覧#
GET /v1/tenants/{id}/connections返り: { data: Connection[] }。
埋め込みの連携の画面のリンク#
POST /v1/tenants/{id}/connect-links| 入力 | 型 | 内容 |
|---|---|---|
connectors |
string[] | 任意。 |
frame_origin |
string | 任意。 |
返り: 201 { url, expires_at }。
電話(Twilio Media Streams)#
wss://voice.voicast.jp/wsTwilio の<Connect><Stream> の<Parameter> で
| Parameter | 内容 |
|---|---|
tenant |
テナントの |
secret |
テナントのvts_…) |
agent |
任意。 |
from |
任意。 |
鍵が
WebRTC の offer#
POST https://voice.voicast.jp/v1/webrtc/offer| 入力 | 型 | 内容 |
|---|---|---|
sdp・type |
string | WebRTC の |
token |
string | セッションのclient_tokenrequestData.token でも |
pc_id・restart_pc |
string・boolean | つなぎ直しのtoken は |
返り: { sdp, type, pc_id }。POST /v1/sessions とerror がbalance_depleted です。error がbusyRetry-After: 30。
つないだら、client-ready をping の
ICE の候補#
PATCH https://voice.voicast.jp/v1/webrtc/offer| 入力 | 型 | 内容 |
|---|---|---|
pc_id |
string | offer のpc_id |
candidates |
array | [{ candidate, sdp_mid, sdp_mline_index }] |
返り: { ok: true }。pc_id は