# Test mode

Build and test against a separate set of test data with vk_test_ keys. Test calls never ring anyone.

Every Vocenya account has a test mode alongside live mode. Test mode uses the same API, endpoints and MCP server, but works on a separate set of test data and never affects anyone in the real world.

## Test keys

- Live keys start with `vk_live_`. Test keys start with `vk_test_`.
- Account owners create and revoke both on the **Developers** page of the portal. Use the **Live / Test** toggle to switch. Each key has its own scopes, and a key is shown only once.
- Test keys are available on every account, including free trials, accounts that have not started billing, and signups that have not finished setup. Live keys are available once your account is set up.
- `GET /me` tells you which kind of key you are using: `data.livemode` is `false` and `data.api_key.mode` is `"test"` for a test key.

## Test data

- A test key only sees and changes test data. A live key only sees and changes live data. An id from the other mode returns `404`.
- Every object in a response has a `livemode` field: `true` for live data, `false` for test data.
- Test data never shows in the portal and never counts toward usage, billing, partner commissions, notifications, analytics or cost reports.
- When you create your first test key, sample data is added: four calls (two with transcripts), three leads, a booking, a website chat with messages, a completed outbound call, AI-call consent for `+15125550142` and `+15125550133`, and a Do Not Call entry for `+15125550199`.
- **Reset test data** on the Developers page (Test tab) deletes every test record and adds the sample data again. Live data, test keys and test webhook endpoints are kept.

## Outbound calls in test mode

- `POST /outbound-calls` (and `POST /leads` with a `callback`) checks a test call exactly like a live one: account settings (outbound calling on, terms accepted, active service, an AI receptionist, HIPAA rules), the test Do Not Call list plus Vocenya's own list, test consents, calling hours, the daily limit and calls already in progress. The only rule not checked is the free trial's AI-minute allowance.
- Refusals return `422` with the same `code` and `decision` as in live mode. A call outside calling hours is accepted with `decision.retry_at` and waits until then.
- An allowed test call never rings anyone. It moves from `queued` to `in_progress` to `completed` within a few seconds, with a sample transcript and summary (see `GET /outbound-calls/{outboundCall}`), and sends `outbound_call.completed` to your test webhook endpoints.
- To try it, queue a call to `+15125550142` (it has test consent). A call to `+15125550199` is refused with `do_not_call`.
- A call to `+15125550133` (also with test consent) reaches voicemail: it ends with status `voicemail` and `answered_by: "machine"`, and follows your account's voicemail setting like a live call (see [Voicemail](https://vocenya.com/docs/outbound-calls#voicemail)): under "leave a message" the message appears in the transcript with `voicemail_left_at` set; under "try again later" a retry is scheduled.

```bash
curl -X POST https://vocenya.com/api/public/v1/outbound-calls \
  -H "Authorization: Bearer $VOCENYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone_number": "+15125550142", "contact_name": "Test caller", "purpose": "informational"}'
```

## Chats in test mode

- Replies and closes with a test key work on test chats only and never reach a real visitor.

## Webhooks in test mode

- Webhook endpoints belong to one mode. Endpoints created with a test key, or on the Test tab of the Developers page, are test endpoints.
- Test endpoints only receive events from test data. Live endpoints only receive events from live data.
- Every delivery body includes `"livemode": true` or `"livemode": false`: `{"id", "type", "livemode", "created_at", "data"}`.
- **Send a test event** works for both live and test endpoints.

## MCP server

- The MCP server at `/mcp/platform` follows the key's mode in the same way: a test key's tools only see and change test data, and records include `livemode`.