Test mode

An inf_test_ key calls the same routes as a live key, with the same request and response shapes. Anything that costs money or reaches a person is simulated instead: you can build and test your integration without placing a real call, without paid minutes and without a paid plan.

Simulated calls

POST /v1/calls with a test key creates a call with livemode: false and answers 201 at once. Nothing is sent to a carrier: the do-not-call list, the call window, the country and the concurrency and hourly limits are not applied, and runAt is ignored. The scheduler then plays the call, within about a minute and over a few seconds:

1. initiated, when the call is created.
2. ringing.
3. ongoing, with startedAt.
4. completed, with endedAt, a duration between 30 and 89 seconds, a fictitious transcript, a fictitious summary and fictitious collected data (appointment_date, reason), successful: true and the outcome answered_human.

Read the call with GET /v1/calls/{id} and its transcript with GET /v1/calls/{id}/transcript. A simulated call has no recording.

Simulated campaigns

POST /v1/campaigns with a test key creates a campaign with livemode: false. It is free: no paid plan and no plan minutes are required, which a live campaign needs. A test campaign calls at most 100 contacts. The campaign engine runs it like a live one (concurrency, retries, progress counters, completed status), but each contact is a simulated call that always ends answered.

Webhooks

Events caused by simulated activity carry livemode: false: call.started, call.ended, call.transcript_ready, call.analysis_ready, and campaign.started, campaign.completed, campaign.cancelled. Your endpoints receive them like any other event; filter on livemode to keep test traffic out of your production data.

Lists and single objects

• GET /v1/calls and GET /v1/campaigns return the objects of the same mode as the key: a test key lists simulated objects, a live key lists real ones. The optional livemode parameter is only accepted with the mode of the key: a test key sending livemode=true (or a live key sending livemode=false) gets 400 with invalid_query, because a key never reads the objects of the other mode.
• Every call and campaign carries a livemode field.
• A single call, transcript, recording or campaign of the other mode answers 404 not_found: a test key can never read or cancel a real campaign.
• GET /v1/tasks and DELETE /v1/tasks/{id} are not available with a test key: they answer 403 with test_mode_not_supported. Scheduled tasks have no test mode, so a test key could otherwise list or cancel a real scheduled call. Use a live key for these two routes.

Web call widget

POST /v1/web-call-sessions with a test key mints a token with livemode: false. When the widget or POST /api/v1/web-calls uses it, nothing is connected and no plan is needed: a call with livemode: false is created and played like the other simulated calls, and the answer is { simulated: true, livemode: false, callId, maxSeconds }. Publishable keys (inf_pub_) have no test mode.

What stays real

Contacts act on the real data of your organization, even with a test key: a contact created with a test key exists for real. The contact events (contact.created, contact.updated, contact.deleted) emitted for these writes carry livemode: false because of the key, but livemode: false does not mean that nothing was written: the data was really created, changed or deleted. Do not use livemode to decide whether to apply a contact event on your side. Knowledge bases are different, because indexing costs money: with a test key, POST /v1/knowledge-bases/{id}/documents validates the request, writes nothing, returns a fictitious documentId and sends a knowledge.document_ready event with livemode: false and a fictitious chunk count. The document does not exist afterwards.

Not counted

Simulated calls and campaigns are left out of the dashboard analytics, the agent statistics, the supervision alerts, the weekly summary, the usage and billing, and the concurrency and hourly limits of your live calls. No minute is ever deducted.