Testing your integration

Build and try your integration in test mode before going live. It's free and safe: nothing you do there reaches a real phone or a carrier, or shows on your bill. Test calls go through the same engine as real ones, so when a test passes, the real thing works.

1. Use your test credentials

Every account has two sets of credentials. The test set reaches only test data: test tenants, agents, lines and calls that your live keys never see.

	Live	Test
API key	ck_<slug>_…	ck_test_<slug>_…
Signing key (agent tokens)	kid k1, k2…	kid test_k1, test_k2…
Webhook	your production URL and secret	its own URL and secret: your development server, or a tunnel to it

Put the test set in your development environment. Everything else stays the same: the API address, the SDKs, the requests, and the agent token's claims (iss is still your slug). To go live, swap in the live set.

You got your first test API key and signing key with your live ones. You can make more on your dashboard: turn on Test mode in the top bar, then open Developers. (The first time, a short guide to test mode opens; How it works in the test-mode strip opens it again.) Your test webhook is set from the test key (PUT /v1/webhook) or on that same page. Every test event says "livemode": false, so your production endpoint can refuse one that reaches it by mistake.

In test mode you can't add SIP trunks or WhatsApp and SIP numbers, and you can't make billing changes. Those are live only.

2. Set up a test tenant

Create a tenant, its agents and a queue with your test key, as your product will (Tenants, Agents, Queues). Then add a test line:

PUT /v1/tenants/demo/channels/test-line
Authorization: Bearer ck_test_yourproduct_…

{ "type": "TEST", "display_name": "Test line", "inbound_queue_ref": "support" }

Calloop picks the line's number (+1 555 2…). A test line works like any line: it can route to a queue, an IVR flow or one agent.

3. Connect your app as an agent

Have your token endpoint sign the agent token with the test signing key (The agent token), and sign in to your app as one of the test tenant's agents. Make the agent available.

4. Call the line

A simulated customer calls your test line:

POST /v1/tenants/demo/test-calls

{ "line": "test-line" }

Your app rings, just as it will for a real customer. Answer it. You hear three beeps, then your own voice a moment later: the caller repeats what it hears. That proves audio goes both ways. Your webhook receives call.created, call.assigned, call.answered and, at the end, call.ended.

Calloop also checks the audio itself:

GET /v1/calls/42/test

test.audio.caller and test.audio.agent are heard once the caller's sound and your agent's microphone reached the call. If agent stays not_heard, your app isn't sending the microphone (a permission, a mute, the wrong device).

While the call is up:

• Press keys as the caller, for your IVR menus: POST /v1/calls/42/test/digits { "digits": "1" }.
• Hang up as the caller: POST /v1/calls/42/test/hangup.

You can also script the caller when you place the call. audio is echo (the default), tone or silent (to try your app's "no audio" handling). digits with digits_after_ms presses keys after the answer, and hangup_after_s makes it hang up by itself (Test calls).

On the dashboard, all of this is one button: in test mode, open a tenant's Setup → Test calls (or Lines) and press Call. The dialog follows the call live, with a keypad, and says whether the test passed.

Be the customer yourself: your test phone

To hear a call as your customers will, use your own mobile as the customer. It's free, and nothing reaches a real phone network.

1. In test mode, open Setup → Test calls and scan the QR code under Your test phone with your phone's camera. Your test phone opens in the phone's browser; keep it open.
2. Call in: on the phone, press one of your test lines. It rings your agents in your app, or in the dashboard while Answer in this browser is on.
3. Call out: call your test phone's number (+1 555 4…, shown with the QR code) from a test line, as in Call out. It rings on your phone.

The phone has a keypad for your IVR menus. New link on the dashboard ends the old link, for example after you shared it.

5. Call out

Outbound calls from a test line go to test numbers. Each acts out one outcome, so you can try how your app handles it:

Number	Outcome
+15550100000	Answers after 2 s, beeps, then echoes
+15550100001	Busy
+15550100002	Rings, never answers
+15550100003	Unreachable: the call fails
+15550100004	Answers, then hangs up after 5 s
+15550100005	Answers and sends no audio
+15550100006	Answers and presses 1 after 3 s

Place the call as you will in production (Outbound calls), with a test line as channel_ref. Your test phone's number works too: the call rings on your phone.

6. Check you're ready

GET /v1/test/checklist checks your integration from what actually happened in test mode:

• your backend used the test key;
• a tenant has an agent and a test line;
• your app connected as an agent;
• your webhook answered 2xx to the call events;
• a test call was answered with audio both ways;
• a call out was answered.

Push (a device token registered) is optional. When ready is true, you're done. Your dashboard's Developers page in test mode shows the same list, ticking each step as it happens and saying what to do next. Its Deliveries tab shows every event sent to your webhook, what your endpoint answered, the exact body, and lets you send one again.

Then go through the go-live checklist and swap in your live credentials.

Limits

Limit	Test mode
API requests	300 a minute (live: 1200)
Calls at once	3
Test calls	200 a day
One call	at most 10 minutes

Test calls and their events are deleted after 30 days, test recordings after 7. A call refused over a limit says why: 409 with too_many_calls or too_many_test_calls.