All pages

Docs

Results

Getting the outcome, collected fields, transcript, summary and recording of each call through the API and webhooks, with signature verification in Node.js, Python, PHP and Go.

View as Markdown

When a call ends, voicast stores the outcome, the collected fields, a transcript and a summary. You can fetch them with the API or be notified by webhook.

Call records are deleted automatically once the retention period set for the environment (1, 7, 14 or 30 days; 30 days by default) has passed since the call ended (Retention). To keep anything longer, receive it by webhook and store it in your own service.

Fetching with the API#

Call Returns
GET /v1/calls Calls, newest first
GET /v1/calls/{id} One call
GET /v1/calls/by-provider/{providerCallId} A call by Twilio CallSid or session ID (sess_…)
GET /v1/calls/{id}/transcript The transcript
GET /v1/calls/{id}/tool-calls Tool calls during the call (name, result, failure kind, time)
GET /v1/calls/{id}/webhooks Delivery status of the webhooks sent for the call (below)
GET /v1/calls/{id}/recording The recording (MP3; see Recordings)

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
  }
}
Field Description
outcome completed, answered, handoff, hangup, time_limit or error (Agents). null while the call is in progress
reason Why the AI decided so (a short sentence)
fields Collected values, keyed by the agent's field key. Phone fields are digits only
summary, category A summary and a category the AI writes after the call. They arrive a little later (call.summary_ready) and are null if none could be made
has_transcript true when a transcript exists
channel phone or web (Web and apps)
trial true for a call made with Test in browser in the dashboard (channel is web)
output audio (the AI spoke) or text (text replies only)
has_recording, recording The recording (Recordings). Calls that were not recorded have has_recording: false and recording: null
billed_yen What this call costs you (yen before tax, up to 3 decimals): the amount taken from the balance (seconds × your per-minute price ÷ 60). null while the call is in progress (Pricing and billing)

Filter the list with ?tenant_id= (tenant), ?outcome= (outcome), and ?from= / ?to= (start time), and set the page size with ?limit= (1–100, default 50). While has_more is true, pass the response's next_cursor as ?cursor= to read on.

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_…" }

Transcript#

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

The transcript is created after the call ends. It comes from speech recognition, so it can contain mishearings.

Recordings#

Conversations whose agent records (recording: true; see Agents) are stored as MP3 (mono; 8 kHz for phone, 16 kHz for Web and apps) with both the caller and the AI. The recording becomes available shortly after the conversation ends, and a call.recording_ready webhook is sent.

bash
curl https://api.voicast.jp/v1/calls/call_…/recording \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -o call.mp3
  • The response is audio/mpeg. Range (for example Range: bytes=0-) is supported, so players can seek (206 with Content-Range). A range outside the recording returns 416.
  • Responses must not be cached (Cache-Control: private, no-store). Do not hand the recording URL to end users' browsers; check permissions on your server and relay it (never give the API key to a browser).
  • Only an API key of that environment can fetch it. Calls in other environments (including live vs. test) and other organizations return 404. A tenant's connection secret cannot fetch recordings.
  • The call's recording.status is available, expired (deleted after the retention period) or deleted.
State GET /v1/calls/{id}/recording
Recording exists 200 (206 for Range)
Conversation not recorded 404 not_found
Retention period ended 410 recording_expired
Deleted 410 recording_deleted

Recordings are deleted automatically once the environment's retention period (30 days by default) has passed since they were saved. The call's recording.expires_at tells you when. To delete one earlier, call DELETE /v1/calls/{id}/recording (returns 204; cannot be undone; the call record and transcript are kept until the call's retention period ends). Deleting a tenant also deletes the recordings of its conversations.

In the dashboard, any member of the organization can play recordings from the conversation details, whatever their role. Deleting recordings and viewing who played or deleted them requires admin or above. The API also returns that log at GET /v1/calls/{id}/recording/accesses.

Tell the caller at the start of the conversation that it is recorded (Agents).

Retention#

Call records are deleted automatically once the environment's retention period has passed since the call ended. This cannot be undone.

Choose the retention period per environment (live and test) from 1, 7, 14 or 30 days. The default is 30 days, and it cannot be longer than 30 days. Admins (admin or above) and the environment's API keys can change it.

Where How
Dashboard "Call record retention" in the environment settings
API GET /v1/retention, PATCH /v1/retention (API reference)
MCP get_retention, set_retention (MCP)
  • If you shorten it, records past the new period are deleted at the next cleanup. Recording deadlines (recording.expires_at) move earlier right away, and recordings already past the new deadline return 410 recording_expired from then on.
  • If you lengthen it, records and recordings not yet deleted are kept until the new period ends. Deleted records do not come back.
  • Deleted: the call (what GET /v1/calls/{id} returns, including the caller's number, collected fields and summary), the transcript, the recording, tool calls during the call and webhook delivery status.
  • Deleted calls return 404 not_found from GET /v1/calls/{id} and the other call endpoints, and no longer appear in lists or in the dashboard's conversation records.
  • The usage breakdown (GET /v1/usage), the minutes on the billing page and balance movements do not change. The number of calls and seconds are kept per day (without the conversation content or phone numbers).
  • Recordings are deleted once the retention period has passed since they were saved (above). Deleting a call record also deletes any recording still left.
  • Deletion runs once a day in bulk, so a call may remain for up to about a day after its retention period ends.

Webhooks#

voicast sends call start, handoff, end, transcript, summary and other events to the URLs you register. voicast handles delivery, retries, signatures and delivery logs.

Registering an endpoint#

POST /v1/webhooks/portal (MCP: create_webhook_portal_link) returns a link to a page where you register endpoints (valid for 15 minutes). On that page you can set the URL, choose events, see the signing secret (whsec_…), send test events and browse delivery logs.

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 }

To embed the page in your own dashboard in an iframe, pass frame_origin (e.g. https://app.example.com). Choose the page language with locale (ja or en, default ja). Endpoints are per environment; register them separately for live and test.

From the voicast dashboard, open the same page with Webhooks in the left menu.

Delivery format#

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", … } }

The body is { type, timestamp, data }; data depends on the event.

Events#

type When data
call.started A call started { call_id, provider_call_id, from, started_at, tenant }
call.handoff_requested A handoff rule matched { call_id, provider_call_id, reason, fields, tenant }
call.ended A call ended The whole Call plus tenant
call.transcript_ready The transcript is ready { call_id, provider_call_id, turns, tenant }
call.summary_ready The summary is ready { call_id, provider_call_id, summary, category, fields, tenant }
call.recording_ready The recording is ready (only for agents that record) { call_id, provider_call_id, status, content_type, duration_ms, size_bytes, expires_at, tenant }. The audio is not included; fetch it with GET /v1/calls/{id}/recording
connection.needs_reauth A connection needs to be signed in again { connection_id, connector, label, status, tenant } (tenant: null for environment connections)
billing.balance_low The balance fell below the threshold (without auto-recharge) { organization_id, balance_yen, threshold_yen }
billing.balance_depleted The balance reached zero or below (new calls are refused) { organization_id, balance_yen, call_id }
billing.recharge_failed An auto-recharge was declined { organization_id, invoice_id, amount_yen, attempt, max_attempts, auto_recharge_disabled, decline_code, balance_yen }
billing.cap_reached The auto-recharge monthly cap was reached and the auto-recharge was skipped (once a month) { organization_id, kind: 'auto_recharge', month, spending_cap_yen, recharged_yen, amount_yen, balance_yen }

tenant is { id, external_id }; use external_id to find your customer.

  • call.* and connection.needs_reauth go to the endpoints of the environment the call or connection belongs to.
  • billing.* concern the whole organization and go to the endpoints of the organization's live environments.
  • For one call, events are created in the order call.started → call.ended → call.transcript_ready → call.summary_ready, but delivery order is not guaranteed. call.handoff_requested is for records and notifications; do not use it to decide phone transfers (Phone).

Responses and retries#

  • A 2xx response is a success. Any other response, a timeout or a connection failure is retried with backoff (by default up to 8 attempts over about 28 hours).
  • The same webhook-id can arrive more than once. Drop IDs you have already processed.
  • Return 2xx first and do heavy work afterwards.

Delivery status#

See the delivery status for each call under Webhook deliveries on the call details page in the dashboard, or with GET /v1/calls/{id}/webhooks (API reference). For each event it shows the status (Succeeded, Retrying, Failed, Pending, Cancelled, No endpoint, Rejected, Unknown), the number of attempts, the last response and the time, plus the result for each endpoint.

  • No endpoint means there was no endpoint, or none receives that event. Adding an endpoint later does not deliver events that were already sent.
  • Unknown means the status couldn't be read (the log is past its retention period, or the service is temporarily unreachable).
  • To see the full delivery logs and retry, use the Webhooks page (the endpoint registration page).

Verifying signatures#

Webhooks are signed with Standard Webhooks. Requests from tools use the same scheme with a different secret.

What arrives Secret
Webhooks The endpoint's signing secret (whsec_…, shown on the endpoint page)
Tool calls The environment's tools signing secret (whsec_…, from the environment settings in the dashboard, GET /v1/tools/secret or the MCP tool get_tools_secret)

How to verify:

  1. The signed content is {webhook-id}.{webhook-timestamp}.{body}, using the raw body bytes (do not re-serialize parsed JSON)
  2. The key is the base64-decoded part after whsec_
  3. Base64-encode the HMAC-SHA256 and compare it with each space-separated v1,<signature> in webhook-signature; any match is valid (two appear for 24 hours after a secret is rotated)
  4. Reject requests whose webhook-timestamp is more than 5 minutes off (prevents replays)

Node.js#

Use the official library (npm install standardwebhooks) or verifyWebhook from the voicast SDK.

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

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

// Verify against the raw body, before any JSON parsing
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 checks a Standard Webhooks signature. Pass the raw body bytes.
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)
})

Billing your own customers#

GET /v1/usage?group_by=tenant returns calls, seconds, minutes and an estimated amount per tenant, which you can use to bill your own customers (Pricing and billing).