ページの一覧

ドキュメント

結果の受け取り

会話の結果・聞き取った項目・文字起こし・要約・録音を API と Webhook で受け取る方法。Webhook のイベントと中身、署名の検証(Node.js・Python・PHP・Go)。

Markdown で見る

会話が終わると、voicast は結果(outcome)・聞き取った項目(fields)・文字起こし・要約を残します。API で引くことも、Webhook で知らせを受けることもできます。

会話の記録は、会話が終わってから、環境ごとに設定した保存期間(1・7・14・30 日。初期値は 30 日)が過ぎると自動で削除します(保存期間)。長く残したいものは、Webhook で受けて自社のサービスに保存してください。

API で引く#

呼び出し 内容
GET /v1/calls 会話の一覧(新しい順)
GET /v1/calls/{id} 会話 1 件
GET /v1/calls/by-provider/{providerCallId} Twilio の CallSid か、セッションの ID(sess_…)で引く
GET /v1/calls/{id}/transcript 文字起こし
GET /v1/calls/{id}/tool-calls 会話中のツールの呼び出し(名前・成否・失敗の種類・時刻)
GET /v1/calls/{id}/webhooks その会話で送った Webhook の送信の状態(下)
GET /v1/calls/{id}/recording 録音(MP3。録音)

会話(Call)#

json
{
  "id": "call_…",
  "tenant_id": "ten_…",
  "agent": { "id": "agt_…", "version": 3 },
  "provider_call_id": "CA…",
  "from": "+819012345678",
  "started_at": 1790000000000,
  "ended_at": 1790000084210,
  "duration_ms": 84210,
  "outcome": "completed",
  "reason": "必須の項目がそろった",
  "fields": { "name": "山田太郎", "phone": "09012345678", "purpose": "予約の変更" },
  "summary": "予約の変更の依頼。来週火曜の午前を希望。",
  "category": "予約の変更",
  "has_transcript": true,
  "channel": "phone",
  "trial": false,
  "output": "audio",
  "billed_yen": 8.5,
  "has_recording": true,
  "recording": {
    "status": "available",
    "content_type": "audio/mpeg",
    "duration_ms": 84000,
    "size_bytes": 252000,
    "expires_at": 1792592084210
  }
}
項目 内容
outcome completed・answered・handoff・hangup・time_limit・error(エージェント設定)。会話中は null
reason AI がそう判断した理由(短い文)
fields 聞き取った項目(エージェント設定の fields の key ごと)。電話番号の項目は数字だけ
summary・category 会話のあとに AI が作る要約と用件の分類。少し遅れて入ります(call.summary_ready)。作れなかったときは null
has_transcript 文字起こしがあれば true
channel phone(電話)か web(Web・アプリ)
trial 管理画面の[ブラウザーで試す]の会話なら true(channel は web)
output audio(声で返した)か text(文章だけを返した)
has_recording・recording 録音(録音)。録音していない会話は has_recording: false・recording: null
billed_yen この会話の利用料(税抜の円、小数 3 桁まで)。残高から引いた額(秒数 × 契約の 1 分の値段 ÷ 60)。会話中は null(料金と請求)

一覧は ?tenant_id=(テナント)・?outcome=(結果)・?from=・?to=(始まった時刻)で絞り、?limit=(1〜100、既定 50)でページの件数を決めます。has_more が true のあいだ、応答の next_cursor を ?cursor= に渡して続きを読みます。

bash
curl "https://api.voicast.jp/v1/calls?limit=100&cursor=1790000000000.call_…" \
  -H "Authorization: Bearer $VOICAST_API_KEY"
# → { "data": [ … ], "has_more": true, "next_cursor": "1789999000000.call_…" }

文字起こし#

json
{
  "call_id": "call_…",
  "turns": [
    { "role": "assistant", "text": "お電話ありがとうございます。さくら歯科です。ご用件をお話しください。" },
    { "role": "user", "text": "来週の予約を変えたいんですが" }
  ]
}

文字起こしは会話が終わってから作られます。音声認識の結果なので、聞き間違いが混ざることがあります。

録音#

エージェント設定で録音する(recording: true。エージェント設定)会話は、相手と AI の両方の声を MP3(モノラル。電話は 8kHz、Web・アプリは 16kHz)で保存します。会話が終わって少しすると取れるようになり、Webhook の call.recording_ready が届きます。

bash
curl https://api.voicast.jp/v1/calls/call_…/recording \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -o call.mp3
  • 応答は audio/mpeg です。Range(例 Range: bytes=0-)に対応するので、再生の部品で早送りできます(206 と Content-Range)。録音の外の範囲は 416 です。
  • 応答は保存させません(Cache-Control: private, no-store)。録音の URL を利用者のブラウザーに直接渡さず、自社のサーバーで権限を確かめてから中継してください(API キーをブラウザーに渡さない)。
  • 取れるのは、その環境の API キーだけです。ほかの環境(本番とテストを含む)・ほかの組織の会話は 404 です。テナントの接続シークレットでは取れません。
  • 会話の recording.status は、available(取れる)・expired(保存期間を過ぎて削除済み)・deleted(削除済み)です。
状態 GET /v1/calls/{id}/recording
録音がある 200(Range のときは 206)
録音していない会話 404 not_found
保存期間を過ぎた 410 recording_expired
削除した 410 recording_deleted

録音は保存してから、環境の保存期間(初期値 30 日)が過ぎると自動で削除します。期限は会話の recording.expires_at で分かります。それより前に消すときは DELETE /v1/calls/{id}/recording(返り 204。元に戻せません。会話記録と文字起こしは、会話の保存期間まで残ります)。テナントを削除すると、そのテナントの会話の録音も削除します。

管理画面では、会話記録の詳細で再生できます(組織のメンバーならロールを問いません)。削除と、誰がいつ再生・削除したかの記録を見るのは admin 以上です。API の GET /v1/calls/{id}/recording/accesses でも記録を見られます。

録音することは、会話の最初に相手に知らせてください(エージェント設定)。

保存期間#

会話の記録は、会話が終わってから、環境の保存期間が過ぎると自動で削除します。元に戻せません。

保存期間は、環境(本番とテスト)ごとに 1・7・14・30 日 から選びます。初期値は 30 日で、30 日より長くはできません。変えられるのは管理者(admin)以上と、その環境の API キーです。

変える場所 方法
管理画面 [環境の設定]の「会話記録の保存期間」
API GET /v1/retention・PATCH /v1/retention(API リファレンス)
MCP get_retention・set_retention(MCP)
  • 短くすると、新しい保存期間を過ぎた記録は、次の削除で削除されます。録音の期限(recording.expires_at)もすぐに早まり、過ぎた録音はその時点で 410 recording_expired になります。
  • 長くすると、まだ削除していない記録と録音は、新しい保存期間まで残ります。削除した記録は戻りません。
  • 削除するもの: 会話(GET /v1/calls/{id} の中身。かけてきた番号・聞き取った項目・要約を含む)・文字起こし・録音・会話中のツールの呼び出し・Webhook の送信の状態。
  • 削除した会話は、GET /v1/calls/{id} などで 404 not_found になり、一覧にも出ません。管理画面の会話記録からも消えます。
  • 利用の内訳(GET /v1/usage)・請求の画面の分数・残高の動きは変わりません。会話の数と秒数を日ごとにまとめて残します(会話の中身や番号は残しません)。
  • 録音は、保存してから保存期間が過ぎると削除します(上)。会話の記録を削除するときは、残っている録音も削除します。
  • 削除は毎日 1 回、まとめて行います。期限を過ぎてから実際に消えるまで、1 日ほどかかることがあります。

Webhook#

会話の始まり・引き継ぎ・終わり・文字起こし・要約などを、登録した URL に送ります。送信と再送・署名・配信の記録は、voicast が受け持ちます。

送り先の登録#

POST /v1/webhooks/portal(MCP は create_webhook_portal_link)で、送り先を登録する画面のリンクを作ります(15 分有効)。画面では、送り先の URL・受け取るイベント・署名シークレット(whsec_…)の確認・試しの送信・配信の記録が扱えます。

bash
curl -X POST https://api.voicast.jp/v1/webhooks/portal \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
# → { "url": "https://…", "expires_at": 1790000900000 }

自社の管理画面に iframe で埋め込むときは、frame_origin(例 https://app.example.com)を渡します。画面の言葉は locale(ja・en、既定 ja)で選べます。送り先は環境ごとです。本番の環境とテストの環境で、それぞれ登録します。

voicast の管理画面からは、左のメニューの[Webhook]で同じ画面を開けます。

届く形#

POST https://saas.example.com/webhooks/voicast
content-type: application/json
webhook-id: msg_2Zq8…
webhook-timestamp: 1790000090
webhook-signature: v1,K5oZfzN95Z9UVu1EsfQmfVNQhnkZ2pj9o9NDN/H/pI4=

{ "type": "call.ended", "timestamp": "2026-10-03T01:32:05.000Z", "data": { "id": "call_…", "outcome": "completed", … } }

本文は { type, timestamp, data } です。data の中身はイベントごとに下のとおりです。

イベント#

type いつ data
call.started 会話が始まった { call_id, provider_call_id, from, started_at, tenant }
call.handoff_requested 引き継ぐ条件に当たった { call_id, provider_call_id, reason, fields, tenant }
call.ended 会話が終わった 会話(Call)の全体と tenant
call.transcript_ready 文字起こしができた { call_id, provider_call_id, turns, tenant }
call.summary_ready 要約ができた { call_id, provider_call_id, summary, category, fields, tenant }
call.recording_ready 録音ができた(録音する設定の会話だけ) { call_id, provider_call_id, status, content_type, duration_ms, size_bytes, expires_at, tenant }。音声は載せません(GET /v1/calls/{id}/recording で取る)
connection.needs_reauth 連携が切れた(もう一度ログインが必要) { connection_id, connector, label, status, tenant }(環境の連携は tenant: null)
billing.balance_low 残高がしきい値を下回った(オートチャージを使っていないとき) { organization_id, balance_yen, threshold_yen }
billing.balance_depleted 残高が 0 以下になった(新しい会話を断り始めた) { organization_id, balance_yen, call_id }
billing.recharge_failed オートチャージがカードで断られた { organization_id, invoice_id, amount_yen, attempt, max_attempts, auto_recharge_disabled, decline_code, balance_yen }
billing.cap_reached オートチャージの月の上限に届き、オートチャージをしなかった(月に 1 回) { organization_id, kind: 'auto_recharge', month, spending_cap_yen, recharged_yen, amount_yen, balance_yen }

tenant は { id, external_id } です。external_id で自社の顧客を引けます。

  • call.* と connection.needs_reauth は、その会話・連携の環境の送り先に届きます。
  • billing.* は組織に 1 つの知らせなので、組織の本番の環境の送り先に届きます。
  • 1 つの会話では call.started → call.ended → call.transcript_ready → call.summary_ready の順に作りますが、届く順は保証しません。call.handoff_requested は記録と通知のためのもので、電話の転送の判断には使いません(電話でつなぐ)。

応答と再送#

  • 2xx を返すと成功です。それ以外の応答・時間切れ・接続の失敗は、間隔を空けて送り直します(既定で最大 8 回、約 28 時間)。
  • 同じ webhook-id が 2 回以上届くことがあります。処理済みの ID は捨てます。
  • 重い処理は先に 2xx を返してから行います。

送信の状態#

会話ごとの送信の状態は、管理画面の会話記録の詳細の[Webhook の送信]か、GET /v1/calls/{id}/webhooks(API リファレンス)で確かめられます。イベントごとに、状態(成功・再送待ち・失敗・送信待ち・取りやめ・送信先なし・拒否・不明)・試行の回数・最後の応答・時刻と、送信先ごとの結果を出します。

  • 「送信先なし」は、送信先が無いか、そのイベントを受け取る送信先が無かったときです。送信先を追加しても、前に送ったイベントは届きません。
  • 「不明」は、状態を読めなかったときです(記録の保存期間を過ぎた・一時的に接続できない)。
  • 詳しい配信記録の確認と再送は、[Webhook]の画面(送り先を登録する画面)で行います。

署名の検証#

Webhook には Standard Webhooks の署名が付いています。会話中のツールの呼び出しも同じ形です(鍵だけが違います)。

届くもの 鍵
Webhook 送り先の署名シークレット(送り先を登録した画面で見る whsec_…)
会話中のツール 環境のツールの署名シークレット(管理画面の環境の設定・GET /v1/tools/secret・MCP の get_tools_secret で見る whsec_…)

確かめ方:

  1. 署名する文字列は {webhook-id}.{webhook-timestamp}.{本文}。本文は届いたバイト列のまま使う(JSON に直してから並べ直さない)
  2. 鍵は whsec_ の後ろを base64 で戻したバイト列
  3. HMAC-SHA256 の結果を base64 にし、webhook-signature の空白区切りの v1,<署名> のどれか 1 つと一致すれば本物(シークレットを再発行してから 24 時間は 2 つ並びます)
  4. webhook-timestamp が今から 5 分以上ずれていれば断る(古い要求の使い回しを防ぐ)

Node.js#

公式のライブラリ(npm install standardwebhooks)か、voicast の SDK の verifyWebhook で確かめられます。

js
import express from 'express';
import { Webhook } from 'standardwebhooks';

const wh = new Webhook(process.env.VOICAST_WEBHOOK_SECRET); // whsec_…
const app = express();

// 署名は届いた本文そのもので確かめるので、JSON に変換する前の本文を受け取る
app.post('/webhooks/voicast', express.raw({ type: 'application/json' }), (req, res) => {
  let event;
  try {
    event = wh.verify(req.body, req.headers);
  } catch {
    return res.sendStatus(400);
  }
  if (event.type === 'call.ended') saveCall(event.data);
  res.sendStatus(204);
});

Python#

python
import os
from flask import Flask, request
from standardwebhooks import Webhook  # pip install standardwebhooks

wh = Webhook(os.environ["VOICAST_WEBHOOK_SECRET"])  # whsec_…
app = Flask(__name__)

@app.post("/webhooks/voicast")
def webhooks():
    try:
        event = wh.verify(request.get_data(), dict(request.headers))
    except Exception:
        return "", 400
    if event["type"] == "call.summary_ready":
        save_summary(event["data"])
    return "", 204

PHP#

php
<?php
function voicast_verify(string $secret, array $headers, string $body, int $tolerance = 300): bool
{
    $h = array_change_key_case($headers, CASE_LOWER);
    $id = $h['webhook-id'] ?? '';
    $ts = $h['webhook-timestamp'] ?? '';
    if (!ctype_digit($ts) || abs(time() - (int) $ts) > $tolerance) {
        return false;
    }
    $key = base64_decode(preg_replace('/^whsec_/', '', $secret));
    $expected = base64_encode(hash_hmac('sha256', "{$id}.{$ts}.{$body}", $key, true));
    foreach (explode(' ', $h['webhook-signature'] ?? '') as $part) {
        [$version, $sig] = array_pad(explode(',', $part, 2), 2, '');
        if ($version === 'v1' && hash_equals($expected, $sig)) {
            return true;
        }
    }
    return false;
}

$body = file_get_contents('php://input');
if (!voicast_verify(getenv('VOICAST_WEBHOOK_SECRET'), getallheaders(), $body)) {
    http_response_code(400);
    exit;
}
$event = json_decode($body, true);
http_response_code(204);

Go#

go
package voicast

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"errors"
	"net/http"
	"strconv"
	"strings"
	"time"
)

// Verify は Standard Webhooks の署名を確かめる。body は届いたバイト列のまま渡す
func Verify(secret string, h http.Header, body []byte) error {
	id, ts := h.Get("webhook-id"), h.Get("webhook-timestamp")
	t, err := strconv.ParseInt(ts, 10, 64)
	if err != nil {
		return errors.New("invalid timestamp")
	}
	if d := time.Since(time.Unix(t, 0)); d > 5*time.Minute || d < -5*time.Minute {
		return errors.New("timestamp out of range")
	}
	key, err := base64.StdEncoding.DecodeString(strings.TrimPrefix(secret, "whsec_"))
	if err != nil {
		return err
	}
	mac := hmac.New(sha256.New, key)
	mac.Write([]byte(id + "." + ts + "."))
	mac.Write(body)
	expected := base64.StdEncoding.EncodeToString(mac.Sum(nil))
	for _, part := range strings.Split(h.Get("webhook-signature"), " ") {
		if v, sig, ok := strings.Cut(part, ","); ok && v == "v1" && hmac.Equal([]byte(sig), []byte(expected)) {
			return nil
		}
	}
	return errors.New("signature mismatch")
}
go
http.HandleFunc("/webhooks/voicast", func(w http.ResponseWriter, r *http.Request) {
	body, _ := io.ReadAll(r.Body)
	if err := voicast.Verify(os.Getenv("VOICAST_WEBHOOK_SECRET"), r.Header, body); err != nil {
		w.WriteHeader(http.StatusBadRequest)
		return
	}
	w.WriteHeader(http.StatusNoContent)
})

自社の顧客に請求する#

GET /v1/usage?group_by=tenant で、テナントごとの会話の数・秒数・分数・金額の目安を引けます。サービスの側で自社の顧客に請求するときの内訳に使えます(料金と請求)。