Test voice in Sandbox

Test a voice integration in Sandbox two ways. Simulate the call with one API call, which suits CI. Or place a real call and read a test card to Natural’s agent. Set NATURAL_API_KEY to your Sandbox API key. The examples use https://api.sandbox.natural.com.

Simulate a call

Create a voice session, then send one action to simulate the call. No phone call is placed and no call minutes are billed.

Voice call simulation is in early access and subject to change. To request access, contact hi@natural.com.

cURL

curl -X POST https://api.sandbox.natural.com/simulations/voice-sessions/vos_019d0a1b2c3d4e5f60718293a4b5c6f0 \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "data": { "attributes": { "action": "pay" } } }'

`action`	What the simulated call does	Session after	Webhooks
`pay`	The caller pays with test card `4111 1111 1111 1111`, then the call ends.	`ended`, `payment.outcome` is `paid`	`cardPayment.succeeded`, `voiceSession.completed`
`decline`	The caller’s test card `4000 0000 0000 0002` declines, then the call ends.	`ended`, `payment.outcome` is `unpaid`	`cardPayment.failed`, `voiceSession.completed`
`sendLink`	Voice payment fails and the checkout link is recorded as sent. Natural texts nobody.	`ended`, `payment.outcome` is `linkSent`	`voiceSession.completed`
`hangUp`	The caller hangs up before paying.	`ended`, `payment.outcome` is `unpaid`	`voiceSession.completed`
`expire`	Nobody dials before `dialExpiresAt`.	`expired`, `payment.outcome` is `null`	`voiceSession.completed`

The response is the voice session, the same as Get voice session returns. Every action except expire ends its call, so the payment intent is free for the next session right away. An action needs a session that is still waiting for a call. Otherwise it answers 409 with code voice_session_simulation_refused, and detail says why. The same code covers a refused test card. After three failed card attempts on one payment intent, the next pay is refused with ATTEMPT_LIMIT_REACHED. To act for a customer, pass their party ID as customerPartyId in attributes.

Place a test call

Transfer a call to the session’s dialUri as in Take a payment over voice. When the agent asks for the card, read a test card:

Card number	Result
`4111 1111 1111 1111`	Approved
`4000 0000 0000 0002`	Declined

Use any future expiration date and any three-digit CVC.

Live session limit

In Sandbox, each developer can hold 10 live voice sessions at once. A session is live while it waits for a dial or its call is in progress. Past the limit, create voice session answers 429 with code voice_session_concurrency_limit. A slot frees when a call ends or a session expires. Simulated calls end right away, so they never hold a slot.

Overview

Common use cases

Guides

Simulate a call

Place a test call

Live session limit

​Simulate a call

​Place a test call

​Live session limit

Simulate a call

Place a test call

Live session limit