Getting started

Create an account, use an API key to create an agent and a tenant, and you can talk to the AI by phone or from a browser. This guide uses the test environment all the way to the first call.

1. Account#

Enter your email at https://app.voicast.jp/login and we send you a sign-in link (valid for 15 minutes, single use). Once signed in, you can register a passkey in your account settings and use it next time.

2. Organization#

On first sign-in you create an organization (your company or team). Billing and members belong to the organization. Creating one also creates a project with a live and a test environment.

Members have one of four roles.

3. Environments#

Each project has a live and a test environment. Agents, tenants, calls, connections and API keys live in one environment and are not visible from the other.

Calls in the test environment are counted exactly like live calls; there are no free minutes. Use the test environment for trial calls during development so they stay out of your live records.

4. Top up#

voicast is prepaid. While your balance is zero or below, new calls are refused, so top up first: in the dashboard go to Organization settings → Billing and add ¥500–¥300,000 (excl. tax) by card. Each top-up expires after 6 months. See Pricing and billing.

5. API key#

Create a key for the test environment under API keys in the dashboard (admin or above). The key is shown once, when you create it.

export VOICAST_API_KEY=vk_test_…

Keep the API key on your server. Never ship it to a browser or a mobile app; for those you hand out a single-use client_token instead.

6. Your first agent#

An agent decides what the AI says and what it collects.

curl https://api.voicast.jp/v1/agents \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Dental reception",
    "config": {
      "greeting": "お電話ありがとうございます。さくら歯科です。ご用件をお話しください。",
      "persona": "落ち着いた丁寧な受付。1 回の発話は 2 文まで",
      "fields": [
        { "key": "name", "label": "お名前", "required": true },
        { "key": "phone", "label": "折り返しの電話番号", "required": true, "type": "phone" },
        { "key": "purpose", "label": "ご用件", "required": true }
      ],
      "handoff_when": ["人と話したいと言われた", "急な痛みや腫れがある"],
      "closing": "承知しました。担当者から折り返しご連絡します。"
    }
  }'

Conversations are in Japanese today, so the greeting, labels and rules are written in Japanese. Keep the returned id (agt_…). Every field is described in Agents.

7. Tenant#

A tenant is the business that actually takes the calls (one of your customers). Put your own customer ID in external_id.

curl https://api.voicast.jp/v1/tenants \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "clinic-123", "name": "Sakura Dental", "agent_id": "agt_…" }'

The returned secret (vts_…) is the connection secret for phone calls and is returned only this once. Store it on your server.

8. First call#

There are two ways to connect.

• Phone: when a call comes in on your Twilio number, return TwiML that <Connect><Stream>s to the voicast voice server. See Phone.
• Web and apps: call POST /v1/sessions on your server to get a client_token, then connect from the browser over WebRTC. See Web and apps.

The MCP tool create_session and voicast/web in the SDK are the quickest ways to try it from a browser.

9. Check the result#

When the call ends, the outcome, the collected fields and a summary are stored.

curl "https://api.voicast.jp/v1/calls?limit=5" \
  -H "Authorization: Bearer $VOICAST_API_KEY"

{
  "data": [
    {
      "id": "call_…",
      "tenant_id": "ten_…",
      "channel": "phone",
      "outcome": "completed",
      "fields": { "name": "山田太郎", "phone": "09012345678", "purpose": "予約の変更" },
      "summary": "予約の変更の依頼。来週火曜の午前を希望。",
      "category": "予約の変更",
      "duration_ms": 84210
    }
  ],
  "has_more": false
}

To be notified after every call, register a webhook endpoint. See Results.

Next#

• Agents: FAQ, voices and speaking rate
• Tools: check free slots with your own API during the call
• Connections: connect Google Calendar or Slack
• MCP: do all of the above by chatting with Claude Code or another agent