# はじめかた

> アカウントの作成から、会話の設定・テナントを作って最初の通話をするまでの手順。

Source: https://voicast.jp/docs/getting-started

アカウントを作り、API キーで会話の設定とテナントを作れば、電話か Web・アプリから AI と話せます。ここではテストの環境で、最初の通話までを進めます。

## 1. アカウント

[https://app.voicast.jp/login](https://app.voicast.jp/login) でメールアドレスを入れると、ログイン用のリンクが届きます（15 分有効、1 回だけ使えます）。ログインのあと、アカウントの設定でパスキーを登録すると、次からはパスキーでもログインできます。

## 2. 組織

最初のログインで組織（会社やチームの単位）を作ります。請求・メンバーは組織ごとです。組織を作ると、プロジェクトが 1 つと、その本番とテストの環境ができます。

メンバーの役割は 4 つです。

| 役割 | できること |
| --- | --- |
| オーナー（owner） | すべて。チャージ・請求の管理・月の上限 |
| 管理者（admin） | メンバーの招待、API キー、通話中の道具の署名の鍵、請求の確認 |
| 開発者（developer） | 会話の設定・テナント・連携の作成と変更 |
| 閲覧者（viewer） | 見るだけ |

## 3. 環境

プロジェクトには本番（live）とテスト（test）の 2 つの環境があります。会話の設定・テナント・通話・連携・API キーは環境ごとに分かれていて、ほかの環境からは見えません。

| 環境 | API キー | 料金 |
| --- | --- | --- |
| 本番 | `vk_live_…` | 1 分 6 円（税別） |
| テスト | `vk_test_…` | 本番と同じく数える |

テストの環境も通話の秒数を本番と同じく数えます（無料の分数はありません）。開発中の試しの通話はテストの環境で行い、本番の環境の記録と混ぜないようにします。

## 4. チャージ

料金は前払いのチャージ式です。残高が 0 以下のあいだは新しい通話を受けないので、最初にチャージします。管理画面の「組織の設定」→「請求」で、500〜300,000 円（税別）をカードで入れます。チャージの期限は 6 か月です。詳しくは[料金と請求](https://voicast.jp/docs/pricing.md)。

## 5. API キー

管理画面の「API キー」で、テストの環境のキーを作ります（管理者以上）。キーの値は作ったときに 1 回だけ表示されます。

```bash
export VOICAST_API_KEY=vk_test_…
```

API キーはサービスのサーバーだけに置きます。ブラウザやアプリには渡しません（Web・アプリには、使い捨ての `client_token` を渡します）。

## 6. 最初の会話の設定

会話の設定（agent）は、AI が何を話し、何を聞き取るかを決めるものです。

```bash
curl https://api.voicast.jp/v1/agents \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "歯科医院の受付",
    "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": "承知しました。担当者から折り返しご連絡します。"
    }
  }'
```

返りの `id`（`agt_…`）を使います。項目の説明は[会話の設定](https://voicast.jp/docs/agents.md)。

## 7. テナント

テナントは、実際に電話を受ける会社（サービスの顧客 1 社）です。`external_id` にはサービスの側の顧客の ID を入れます。

```bash
curl https://api.voicast.jp/v1/tenants \
  -H "Authorization: Bearer $VOICAST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "external_id": "clinic-123", "name": "さくら歯科", "agent_id": "agt_…" }'
```

返りの `secret`（`vts_…`）は電話をつなぐときの鍵で、このときだけ返ります。サービスのサーバーに保存します。

## 8. 最初の通話

つなぎ方は 2 つあります。

- **電話**: Twilio の番号の着信で、voicast の音声サーバーへ `<Connect><Stream>` する TwiML を返します。手順は[電話でつなぐ](https://voicast.jp/docs/phone.md)。
- **Web・アプリ**: サーバーで `POST /v1/sessions` を呼んで `client_token` を受け取り、ブラウザから WebRTC でつなぎます。手順は[Web・アプリでつなぐ](https://voicast.jp/docs/web.md)。

MCP の道具（`create_session`）や [SDK](https://voicast.jp/docs/sdk.md) の `voicast/web` を使うと、ブラウザからすぐに試せます。

## 9. 結果の確認

通話が終わると、結果・聞き取った項目・要約が残ります。

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

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

通話のたびに知らせを受けるには、Webhook の送り先を登録します。[結果の受け取り](https://voicast.jp/docs/results.md)を見てください。

## 次に読むもの

- [会話の設定](https://voicast.jp/docs/agents.md): よくある質問・声・話す速さ
- [通話中の道具](https://voicast.jp/docs/tools.md): 予約の空きを自社の API で調べる
- [連携](https://voicast.jp/docs/connectors.md): Google カレンダーや Slack とつなぐ
- [MCP](https://voicast.jp/docs/mcp.md): Claude Code などから、ここまでの手順を会話で進める