ページの一覧

ドキュメント

API リファレンス

voicast の API(/v1)と音声の接続の一覧。認証・形式・各エンドポイントの入力と返り・エラー。

Markdown で見る

基本#

  • 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 キーは管理画面の「API キー」で作ります(管理者以上)。サービスのサーバーだけに置き、ブラウザやアプリには渡しません。

エンドポイント#

メソッド パス 内容
POST /v1/agents エージェントの作成
GET /v1/agents エージェントの一覧
GET /v1/agents/{id} エージェント設定の取得
PUT /v1/agents/{id} エージェント設定の変更(新しいバージョン)
GET /v1/agents/{id}/versions バージョンの一覧
DELETE /v1/agents/{id} エージェントの削除
GET /v1/agent-templates エージェントのテンプレート
POST /v1/tenants テナントの作成
GET /v1/tenants テナントの一覧
GET /v1/tenants/{id} テナントの取得
PATCH /v1/tenants/{id} テナントの変更
POST /v1/tenants/{id}/secret 接続シークレットの再発行
DELETE /v1/tenants/{id} テナントの削除
POST /v1/tenants/{id}/sip-credentials SIP の接続情報の作成
GET /v1/tenants/{id}/sip-credentials SIP の接続情報の一覧
PATCH /v1/tenants/{id}/sip-credentials/{credential} SIP の接続情報の変更
DELETE /v1/tenants/{id}/sip-credentials/{credential} SIP の接続情報の削除
GET /v1/calls 会話の一覧
GET /v1/calls/{id} 会話の取得
GET /v1/calls/by-provider/{providerCallId} サービスの側の ID で会話を引く
GET /v1/calls/{id}/transcript 文字起こし
GET /v1/calls/{id}/tool-calls 会話中のツールの呼び出し
GET /v1/calls/{id}/webhooks 会話の Webhook の送信の状態
GET /v1/calls/{id}/recording 録音の取得(MP3)
DELETE /v1/calls/{id}/recording 録音の削除
GET /v1/calls/{id}/recording/accesses 録音の再生と削除の記録
POST /v1/sessions Web・アプリのセッションの作成
GET /v1/usage 利用の内訳
POST /v1/webhooks/portal Webhook の設定画面のリンク
GET /v1/billing 請求の状態(残高・オートチャージ・1 分の値段・支払い方法)
POST /v1/billing/topups チャージの URL
GET /v1/tools/secret ツールの署名シークレット
POST /v1/tools/secret/rotate 署名シークレットの再発行
GET /v1/retention 会話の記録と録音の保存期間
PATCH /v1/retention 保存期間の変更
POST /v1/tools/try ツールを試す
GET /v1/connectors 連携先の一覧
GET /v1/connections 連携の一覧
POST /v1/connections 連携の作成(URL と API キー)
GET /v1/connections/{id} 連携の取得
PATCH /v1/connections/{id} 連携の設定
GET /v1/connections/{id}/options 連携の設定の選択肢
DELETE /v1/connections/{id} 連携の解除
GET /v1/tenants/{id}/connections テナントの連携の一覧
POST /v1/tenants/{id}/connect-links 埋め込みの連携の画面のリンク

音声の接続(API キーは使いません):

方式 URL 内容
WebSocket wss://voice.voicast.jp/ws 電話(Twilio の Media Streams)
WebSocket wss://voice.voicast.jp/ws/{相手} 電話(Telnyx・Plivo・Vonage・Exotel・Genesys・Asterisk)
POST https://voice.voicast.jp/v1/webrtc/offer Web・アプリ(WebRTC の offer)
PATCH https://voice.voicast.jp/v1/webrtc/offer ICE の候補を足す

MCP(https://api.voicast.jp/mcp)は MCP を見てください。


エージェントの作成#

POST /v1/agents
入力 型 内容
name string 名前(1〜100 文字)
config AgentConfig エージェント設定(エージェント設定)

返り: 201 Agent(config と tool_keys 付き、version: 1)。誤りは 422 invalid_config(details に項目ごとの誤り)。

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

version(1 以上の整数)を省くと、いまのバージョンです。返り: Agent(config と tool_keys 付き)。無ければ 404。tool_keys は、どのバージョンを取得しても、いま預かっているキーです。

エージェント設定の変更#

PUT /v1/agents/{id}
入力 型 内容
name string 任意。省くといまのまま
config AgentConfig 全体を渡す(預けた API キーを使い続けるツールは auth.value を省く)

返り: Agent(新しいバージョン、tool_keys 付き)。進行中の会話は始まったときのバージョンのまま続きます。

エージェント設定のバージョンの一覧#

GET /v1/agents/{id}/versions

返り: { data: [{ version, created_at }] }(新しい順)。

エージェントの削除#

DELETE /v1/agents/{id}

返り: 204。使っているテナントか SIP の接続情報があれば 409 in_use(details に件数 { "tenants": 1, "sip_credentials": 0 })。会話記録は残ります。預かっていたツールの API キーは削除します。

エージェントのテンプレート#

GET /v1/agent-templates

返り: { data: AgentTemplate[] }。最初から中身が入ったエージェント設定です(エージェントのテンプレート)。placeholders に並んだ箇所(config の中の「〇〇歯科」など)を変更してから、POST /v1/agents の config に渡します。「〇〇」が残っていると 422 invalid_config です。

ts
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 サービスの側の顧客の ID。英数字と . _ : - の 1〜100 文字。環境の中で重ならないこと
name string 任意。表示名(100 文字まで)
agent_id string 任意。既定のエージェント設定
pronunciations { text, reading }[] 任意。声にするときの読み(事業者・拠点の名前など)。reading はひらがなかカタカナ(ー・空白・読点を含めて 100 文字まで)、text は 100 文字まで、20 個まで。同じ text は 2 度書けません

返り: 201 Tenant と secret(接続シークレット vts_…。このときだけ)。同じ external_id があれば 409 conflict。

ts
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 ならテナントの読み)。1 つのエージェントを多くの事業者で使うとき、{{tenant_name}} に入る名前の読みはテナントに登録してください(例: { "text": "医療法人社団 東壽会", "reading": "いりょうほうじんしゃだん とうじゅかい" })。読みの誤りは 422 invalid_request(details に項目ごとの誤り)。

テナントの一覧#

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 で電話と Web・アプリの接続を止める
pronunciations { text, reading }[] 任意。渡した一覧で置き換えます。[] で消します

返り: Tenant。渡した項目だけが変わります。

接続シークレットの再発行#

POST /v1/tenants/{id}/secret

返り: { secret, previous_secret_expires_at }。古いシークレットも 24 時間は通ります。

テナントの削除#

DELETE /v1/tenants/{id}

返り: 204。接続できなくなります。会話記録は残ります(録音は削除します)。同じ external_id でまた作れます。SIP の接続情報も消えます。

SIP の接続情報の作成#

POST /v1/tenants/{id}/sip-credentials

PBX から sip.voicast.jp に SIP で電話を送るときの、Digest 認証のユーザー名とパスワードを作ります。手順は電話でつなぐ。

入力 型 内容
name string 任意。PBX を見分ける名前(100 文字まで)
agent_id string 任意。この接続情報で受けるエージェント。省くとテナントのエージェント
transfer_to string 任意。AI が担当者に渡すとき(outcome: handoff)に PBX へ REFER で頼む転送先。内線番号など(数字と * # +、32 文字まで)か SIP の URI(sip:・sips:)。省くと転送せずに切る

返り: 201 { id, username, password, realm, server, tenant_id, agent_id, name, transfer_to, created_at }。password はこのときだけ返ります。username は id(sipc_…)、realm は voicast、server は sip.voicast.jp です。

SIP の接続情報の一覧#

GET /v1/tenants/{id}/sip-credentials

返り: { data: [...] }。パスワードは返りません。

SIP の接続情報の変更#

PATCH /v1/tenants/{id}/sip-credentials/{credential}

name・agent_id(null でテナントのエージェント)・transfer_to(空か null で転送しない)を変えます。渡した項目だけ変わります。パスワードは変わりません。

返り: 接続情報(パスワードなし)。

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 はその日を含む)か Unix ミリ秒
cursor 任意。続きの位置(前の応答の next_cursor をそのまま渡す)
limit 任意。1〜100(既定 50)
before 任意。以前の形のページ送り(この started_at より前に始まったもの)。同じミリ秒に始まった会話を飛ばすことがあるので cursor を使います。cursor と一緒には使えません(422)

返り: { data: Call[], has_more, next_cursor }(始まった時刻の新しい順)。会話が終わってから環境の保存期間(初期値 30 日)を過ぎた会話は自動で削除済みで、出ません(保存期間)。has_more が true のあいだ、next_cursor を cursor に渡して続きを読みます(has_more が false なら next_cursor は null)。

ts
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 は、残高から引いた額(秒数 × 契約の 1 分の値段 ÷ 60)です(料金と請求)。

会話の取得#

GET /v1/calls/{id}

返り: Call。会話が終わってから環境の保存期間を過ぎて削除した会話は 404 not_found(ほかの環境の会話と同じ。保存期間)。文字起こし・ツールの呼び出し・送信の状態・録音も同じです。

サービスの側の ID で会話を引く#

GET /v1/calls/by-provider/{providerCallId}

Twilio の CallSid(CA…)か、セッションの ID(sess_…)で引きます。Twilio の <Connect> の action で結果を見るのに使います。返り: Call。記録が無ければ 404。

文字起こし#

GET /v1/calls/{id}/transcript

返り: { call_id, turns: [{ role: 'assistant' | 'user', text }] }。会話が終わってから作られます。無ければ 404。

会話中のツールの呼び出し#

GET /v1/calls/{id}/tool-calls

返り: { data: [{ name, status, error, started_at }] }(呼び出した順)。status は ok(成功)・error(失敗)・running(実行中)、error は失敗の種類(timeout・not_connected など。成功と実行中は null)です。ツールに渡した引数と返した結果は、個人情報を含むため返しません。会話のあとの通知(Slack など)は入りません。

会話の Webhook の送信の状態#

GET /v1/calls/{id}/webhooks

その会話で送ったイベント(call.*)と、会話のあとの Slack・Chatwork・Microsoft Teams への通知(voicast.notify。連携)ごとの、送信の状態です。管理画面の会話記録の詳細の[Webhook の送信]と同じものです。

返り:

ts
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 には、ほかに held(保留。送信先を一時停止している)と waiting(取得待ち。取りに来る送信先が、まだ取りに来ていない)があります。

Webhook を送っていない環境は enabled: false です。送ったイベントが無ければ data は空です。状態を読めなかったイベントだけが unknown になり、ほかのイベントは返ります。詳しい配信記録の確認と再送は、送り先を登録する画面(Webhook の設定画面のリンク)で行います。

録音の取得#

GET /v1/calls/{id}/recording

返り: 録音の音声(audio/mpeg)。Range に対応します(206・Content-Range。録音の外は 416)。Cache-Control: private, no-store。録音していない会話は 404 not_found、保存期間を過ぎたら 410 recording_expired、削除したら 410 recording_deleted。ほかの環境の会話は 404。結果の受け取り。

録音の削除#

DELETE /v1/calls/{id}/recording

返り: 204。元に戻せません。会話記録と文字起こしは残ります。すでに無ければ 410(期限切れ・削除済み)か 404(録音していない)。管理画面では admin 以上が削除できます。

録音の再生と削除の記録#

GET /v1/calls/{id}/recording/accesses

返り: { data: [{ action: 'play' | 'delete', actor: { kind: 'user' | 'api_key', id, email }, at }] }(新しい順に 100 件)。再生は最初から読んだとき(Range が無いか 0 から)に残ります。管理画面では admin 以上。

セッションの作成#

POST /v1/sessions
入力 型 内容
tenant_id string テナントの ID
agent_id string 任意。省くとテナントの既定
output audio・text 任意。既定 audio

返り: 201 { id, tenant_id, agent_id, output, client_token, expires_at, webrtc_url, ice_servers }。client_token(vct_…)は 2 分・1 回だけ。ice_servers([{ urls, username?, credential? }])は RTCPeerConnection の iceServers にそのまま渡します(STUN と、使えるときは期限の短い TURN)。client_token・webrtc_url・ice_servers だけをブラウザやアプリに渡します。

エラー: 402 balance_depleted(残高が 0 以下)、409 tenant_disabled、422 no_agent・invalid_request。

利用の内訳#

GET /v1/usage?from=&to=&group_by=&channel=&tenant_id=&external_id=
クエリ 内容
from・to 日付(YYYY-MM-DD、日本時間。to はその日を含む)か Unix ミリ秒(to はその時刻を含まない)。省くと今月の始まりから今まで。366 日まで
group_by 任意。tenant・day・channel
channel 任意。phone・web に絞る
tenant_id・external_id 任意。テナントに絞る(external_id は今あるテナント)。合うものが無ければ 0

返り:

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 })[];  // group_by が無ければ []
  note: string;
};

絞り込みは一緒に使えます(group_by=tenant&channel=phone でテナントごとの電話の分数)。値の誤りは 422 です。数えるのは期間内に終わった会話です。保存期間を過ぎて削除した会話も数えます(いつ削除しても同じです。日本時間の日ごとにまとめて残すため、保存期間より前の期間を Unix ミリ秒で日の途中から区切ると、その日の会話は日の始まりの時刻で数えます)。amount_yen は税抜の目安です(料金と請求)。

Webhook の設定画面のリンク#

POST /v1/webhooks/portal
入力 型 内容
frame_origin string 任意。iframe で埋め込む親のオリジン
locale ja・en 任意。画面の言葉(既定 ja)

返り: 201 { url, expires_at }(15 分有効)。送り先の URL・受け取るイベント・署名シークレットを登録する画面です(結果の受け取り)。Webhook の送信が使えないときは 503 unavailable。

請求の状態#

GET /v1/billing

API キーの組織の請求の状態を返します(本番とテストの環境で共通)。管理画面の「請求」と同じ内容です。

ts
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 チャージの金額(税抜の円、500〜300,000)

返り: 201 { url, amount_yen, tax_yen }。url は Stripe の支払いの画面です。利用者がブラウザで開いて払うと、残高に足されます。範囲の外は 422。オートチャージ・月の上限・カードの変更は管理画面で行います(料金と請求)。

ツールの署名シークレット#

GET /v1/tools/secret

返り: { secret, previous_secret_expires_at }。secret(whsec_…)は環境の会話中のツールの呼び出しに付く署名シークレットです。previous_secret_expires_at は再発行したあと古いシークレットも並べる期限(無ければ null)。

ツールの署名シークレットの再発行#

POST /v1/tools/secret/rotate

返り: { secret, previous_secret_expires_at }。再発行してから 24 時間は、古いシークレットの署名も並べて送ります。そのあいだに自社の側のシークレットを差し替えます。

保存期間#

GET /v1/retention

返り: { retention_days, choices }。retention_days はキーの環境の会話の記録と録音の保存期間(日)、choices は選べる値([1, 7, 14, 30])です。初期値は 30 です。会話の記録は会話が終わってから、録音は保存してから数えます(保存期間)。

保存期間の変更#

PATCH /v1/retention
項目 型 内容
retention_days integer 1・7・14・30 のどれか(日)。30 日より長くはできません

返り: { retention_days, choices }。ほかの値は 422 invalid_request。変えるのはキーの環境だけです(本番とテストは別)。管理画面では[環境の設定]で admin 以上が変えられます。

短くすると、新しい保存期間を過ぎた会話の記録と録音は、次の削除(毎日 1 回)で削除され、元に戻せません。まだ期限の来ていない録音の recording.expires_at は、保存した時刻 + 新しい保存期間になります。長くすると、まだ削除していない記録は新しい保存期間まで残ります。利用の内訳(GET /v1/usage)と請求は変わりません。

ツールを試す#

POST /v1/tools/try

エージェントのツールを 1回だけ呼び、相手の応答を返します。会話の中で AI が呼ぶときと同じ処理(署名・API キー・8秒の打ち切り)です。会話の料金はかからず、会話の記録にも残りません。

入力 型 内容
tool string | AgentTool 保存したツールの名前(agent_id が必要)か、保存の前のツールの定義
agent_id string 任意。ツールのあるエージェント(tool が名前のときは必須)。預けたキーは、名前で渡したときだけ使います。定義で渡すときに auth があって auth.value が無ければ 422 missing_api_key
arguments object 任意。ツールの引数(既定 {})
tenant_id string 任意。本文の call.tenant に入るテナント。省くと call.tenant は null
ts
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[] }。使える連携先は 連携 を見てください。

ts
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= (空)で環境の連携だけに絞れます。

ts
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 と API キーで連携する連携先
secret string API キー(1〜2,000 文字)
input object { base_url, header }(呼び出す API の URL と、API キーを付けるヘッダーの名前)

返り: 201 Connection(設定待ち needs_setup)。保存の前に URL とヘッダーの名前を確認し、誤りは 422 verify_failed。環境の連携だけなので、tenant_id を付けると 422 invalid_request。

連携の取得#

GET /v1/connections/{id}

返り: Connection。

連携の設定#

PATCH /v1/connections/{id}
入力 型 内容
config object 連携先ごとの設定(URL と API キーは tools)。渡した項目だけ変わります

返り: Connection。設定待ち(needs_setup)の連携は active になります。誤りは 422 invalid_config。設定の形は連携を見てください。

連携の設定の選択肢#

GET /v1/connections/{id}/options

連携先に問い合わせて、設定で選択できるものを返します。Google カレンダーは { calendars: { id, name, primary }[] }、kintone は { apps: { id, name }[], fields: { code, label }[] }(?app= で選んだアプリの項目)、LINE WORKS は { users: { id, name }[] }、Google スプレッドシートは { spreadsheets: { id, name }[], sheets: string[], headers: string[] }(voicast が作成したスプレッドシート、選んだスプレッドシートのシート、選んだシートの 1 行目の見出し)で、?spreadsheet= と ?sheet= で選んだものを渡します。URL と API キー(http)の連携には選択肢が無いので {} を返します(ツールは config.tools に書きます)。連携が切れていれば 409 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 任意。iframe で埋め込む親のオリジン(https)

返り: 201 { url, expires_at }。リンクの有効期限は 15 分です。使い方は連携を見てください。


電話(Twilio Media Streams)#

wss://voice.voicast.jp/ws

Twilio の <Connect><Stream> の接続先です。<Parameter> で次を渡します。

Parameter 内容
tenant テナントの ID
secret テナントの接続シークレット(vts_…)
agent 任意。エージェントの ID
from 任意。かけてきた番号

鍵が違う・テナントが止まっている・料金の都合で断るときは、すぐに閉じます。手順は電話でつなぐ。

WebRTC の offer#

POST https://voice.voicast.jp/v1/webrtc/offer
入力 型 内容
sdp・type string WebRTC の offer
token string セッションの client_token(RTVI に対応したクライアントは requestData.token でも可)
pc_id・restart_pc string・boolean つなぎ直しのときだけ(token は要らない)

返り: { sdp, type, pc_id }。トークンが違う・期限切れ・使用済みは 403。料金の都合で断るときは POST /v1/sessions と同じ 402 で、本文の error が balance_depleted です。音声サーバーが混み合っていて同時の会話が上限のときは 503 で、error が busy(Retry-After: 30。トークンは使われないので、同じトークンでつなぎ直せます)。

つないだら、データチャンネルで RTVI の client-ready を送り、そのあと 1 秒ごとに ping の文字列を送ります(Web・アプリでつなぐ)。

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 は 404。