Test mode

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): under "leave a message" the message appears in the transcript with voicemail_left_at set; under "try again later" a retry is scheduled.

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.