# Getting started

> From creating an account to your first call: organization, environments, API key, agent, tenant.

Source: https://voicast.jp/en/docs/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](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.

| Role | Can |
| --- | --- |
| Owner | Everything, including top-ups, billing management and the monthly cap |
| Admin | Invite members, manage API keys and the tools signing secret, view billing |
| Developer | Create and change agents, tenants and connections |
| Viewer | Read only |

## 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.

| Environment | API key | Price |
| --- | --- | --- |
| Live | `vk_live_…` | ¥6 per minute (excl. tax) |
| Test | `vk_test_…` | Counted the same as live |

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](https://voicast.jp/en/docs/pricing.md).

## 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.

```bash
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.

```bash
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](https://voicast.jp/en/docs/agents.md).

## 7. Tenant

A tenant is the business that actually takes the calls (one of your customers). Put your own customer ID in `external_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": "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](https://voicast.jp/en/docs/phone.md).
- **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](https://voicast.jp/en/docs/web.md).

The MCP tool `create_session` and `voicast/web` in the [SDK](https://voicast.jp/en/docs/sdk.md) 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.

```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
}
```

To be notified after every call, register a webhook endpoint. See [Results](https://voicast.jp/en/docs/results.md).

## Next

- [Agents](https://voicast.jp/en/docs/agents.md): FAQ, voices and speaking rate
- [Tools](https://voicast.jp/en/docs/tools.md): check free slots with your own API during the call
- [Connections](https://voicast.jp/en/docs/connectors.md): connect Google Calendar or Slack
- [MCP](https://voicast.jp/en/docs/mcp.md): do all of the above by chatting with Claude Code or another agent