Copy page

Getting started

Test mode

Test mode

Test mode lets you exercise the whole API without dialling a real phone or spending balance. Calls progress through realistic states on a compressed timeline and produce simulated transcripts, recordings and analysis, and webhooks fire just as they do in live mode. Every request made with a rai_test_ key is in test mode.

What test mode does and does not do

Test mode never contacts a phone network, never places a real call, never charges your workspace and never reads or changes your live data.

What is the same as live mode:

• The same operations, request validation, error codes, scopes, idempotency and rate limits.
• The same compliance checks, against your test-mode contacts and do-not-call list: a number on the test do-not-call list is refused with dnc_listed, a number that matches a contact without consent (when the workspace requires it) with consent_required (a number with no contact record is not checked for consent), and calling hours and the per-number daily limit apply. As in live mode, campaigns are screened when they start and resume, not again while they run.
• Webhook events, sent to test-mode endpoints with "livemode": false.

What does not apply in test mode:

• Balance, monthly spend limit and account status checks.
• The daily limit on calls placed through the API.
• Charges: cost.amount is always 0.

Test phone numbers

The destination number chooses the simulated result. Use these fictional numbers:

Calls that are not answered (+12025550101 to +12025550103) have no transcript, recording or analysis: their artifacts report absent. The voicemail case (+12025550104) has a recording but no transcript or analysis. Prefer the numbers above to any real number, even though test mode never dials it.

Sample agent and number

Every workspace has a Sample agent in test mode, id agent_1ZltiWzxrXmMprGD6q63, marked "sample": true, always switched on, published and ready. It calls from the sample number +12025550150 (id pn_6Vhm3sFrB5UpmXAnsvmDu, also "sample": true). Both appear in GET/agents and GET/phone-numbers for test keys only; with a live key they answer resource_not_found.

You can also test with your own agents. In test mode an agent must be switched on and saved for calling in the console; it does not need to be published or to have a phone number.

Timing

A test call reaches status: ended within about 20 seconds and settled: true within about 30 seconds of being accepted. The progress is computed from timestamps, so reading the call later gives the same result. duration_seconds is simulated too and does not match the wall-clock time the test call took (for example 42 seconds for +12025550100).

Test-mode campaigns use test-mode contacts only. When you start one, each recipient gets a simulated call whose result is chosen by the recipient's number (the table above), and campaign events fire with "livemode": false. Pause and stop take effect immediately.

Simulated results

• Transcripts and analysis are fixtures marked "simulated": true.
• Recordings are short synthetic audio files (audio/wav, about one second), served through the same short-lived link as live recordings, also with "simulated": true.
• Every simulated object has "livemode": false.

Do not use simulated content to test your own language processing: it is fixed sample content, not a real conversation.

Test data

Calls, campaigns, contacts, do-not-call entries and webhook endpoints that you create with a test key stay in test mode. They are invisible to live keys and to the console's normal screens. Use them freely: nothing in test mode affects real people or your balance.

Moving to live mode

Switch the key, not the code: deploy a rai_live_ key, check GET /v1/workspace says "livemode": true, and make sure your live agents are published and ready. See Going live.