Testlie
Menu

Reference

On this page

WhatsApp & push API

Endpoints for WhatsApp sandboxes and push inboxes, and the messages and notifications they capture. Authentication, roles, errors and paging are described in the API overview.

Your app sends through the provider-compatible APIs: the WhatsApp Cloud API with the sandbox's access token, and APNs and FCM with the push inbox's keys. The endpoints on this page are for your tests and tooling, with a team API key.

WhatsApp sandboxes

Method and path Role Description
GET /api/whatsapp-sandboxes Member Every sandbox of the team, with credentials and counts
POST /api/whatsapp-sandboxes Admin Create one: { "name", "projectId"?, "verifiedName"?, "outcomeRules"?, "errorMode"? }. 201 { whatsappSandbox }
GET /api/whatsapp-sandboxes/:id Member One sandbox
PATCH /api/whatsapp-sandboxes/:id Admin Change the fields above, plus webhookUrl (null removes it), verifyToken and skipVerification. A new webhookUrl is verified with Meta's GET handshake first; a failed handshake answers 400 with "code": "webhook_verification_failed"
DELETE /api/whatsapp-sandboxes/:id Admin Delete the sandbox and its messages. 204
POST /api/whatsapp-sandboxes/:id/rotate Admin { "secret": "accessToken" | "appSecret" | "verifyToken" } (default accessToken). The old value stops working at once
POST /api/whatsapp-sandboxes/:id/verify-webhook Admin Run the verification handshake again: { ok, status, error }. 400 without a callback URL
GET /api/whatsapp-sandboxes/:id/templates Member The sandbox's message templates
POST /api/whatsapp-sandboxes/:id/templates Admin Add a template. 409 if the name already exists in that language; at most 250 per sandbox
PATCH, DELETE /api/whatsapp-sandboxes/:id/templates/:templateId Admin Change a template (for example its status) or delete it
GET /api/whatsapp-sandboxes/:id/messages Member List messages: waId, direction (outbound or inbound), q, page, limit (default 100, max 500)
DELETE /api/whatsapp-sandboxes/:id/messages Member Clear the sandbox
GET /api/whatsapp-sandboxes/:id/messages/wait Member Long-poll (see below)
POST /api/whatsapp-sandboxes/:id/simulate Member Act as a test user: a text, a quick-reply tap, a button or list reply, a location, a reaction, or reading a message. See Simulate the user
GET /api/whatsapp-sandboxes/:id/media/:mediaId Member The bytes of media your app uploaded (kept 30 days)
GET /api/whatsapp/messages/:wamid Member One message, with the request as your app sent it
DELETE /api/whatsapp/messages/:wamid Member Delete one message. 204
GET /api/whatsapp/messages/:wamid/extract Member { wamid, codes, links }

outcomeRules (up to 20, first match wins) decide what happens to messages for a recipient; errorMode decides whether errors such as a closed 24-hour window come back in the API response (sync) or in a status webhook (webhook). Both are described in Outcomes per number.

Wait for a WhatsApp message

Parameter Notes
to The recipient's WhatsApp ID (digits; other characters are ignored)
contains Text the message contains (case-insensitive)
template A template name
type A message type (text, template, image, interactive, ...)
direction outbound (default: messages your app sent) or inbound (simulated users)
since ISO time; only messages captured at or after it match
timeout 1 to 120 seconds, default 30
bash
curl -f -H "Authorization: Bearer $TESTLIE_API_KEY" \
  "https://app.testlie.com/api/whatsapp-sandboxes/$SANDBOX_ID/messages/wait?to=15551234567&template=otp_code&timeout=30"

A match answers 200 { message } with extracted.codes (a copy-code button's value first) and extracted.links; a timeout answers 408.

Push inboxes

Method and path Role Description
GET /api/push-inboxes Member Every push inbox of the team, with its APNs key, service-account JSON and counts
POST /api/push-inboxes Admin Create one: { "name", "projectId"?, "apnsTopics"?, "unknownTokens"? }. apnsTopics lists up to 20 allowed bundle IDs; unknownTokens is accept (default) or reject. 201 { pushInbox }
GET /api/push-inboxes/:id Member One push inbox
PATCH /api/push-inboxes/:id Admin Change the fields above
DELETE /api/push-inboxes/:id Admin Delete the inbox and its notifications. 204
POST /api/push-inboxes/:id/apns-key Admin { "generate": true, "teamId"? } for a new key, or { "p8", "keyId", "teamId" } to use your own .p8 (only its public key is stored)
POST /api/push-inboxes/:id/fcm-key Admin Replace the service-account key. Access tokens issued for the old key stop working
GET /api/push-inboxes/:id/devices Member The inbox's test devices
POST /api/push-inboxes/:id/devices Member Register a device: { "platform": "apns" | "fcm", "token", "label"?, "topic"?, "outcome"? }. outcome is deliver (default), unregistered, bad_token or wrong_sender. At most 500 per inbox. 201 { device }
PATCH, DELETE /api/push-inboxes/:id/devices/:deviceId Member Change label, topic or outcome, or remove the device
GET /api/push-inboxes/:id/notifications Member List, newest first: service (apns or fcm), token, topic, q, page, limit (default 100, max 500)
PATCH /api/push-inboxes/:id/notifications Member Mark every notification read
DELETE /api/push-inboxes/:id/notifications Member Empty the inbox
GET /api/push-inboxes/:id/notifications/wait Member Long-poll: service, token, topic, contains, since, timeout (1 to 120 seconds). 200 { notification } or 408
GET /api/push/:id Member One notification with extracted codes and links
PATCH /api/push/:id Member { "isRead": true | false }
DELETE /api/push/:id Member Delete one notification. 204
GET /api/push/:id/extract Member { id, codes, links }

What each device outcome does to an APNs or FCM send is listed in Test devices and simulated outcomes.

Limits

WhatsApp sandboxes count toward the plan's SMS inbox limit, and a team can have as many push inboxes as SMS inboxes. Captured WhatsApp messages share the monthly SMS limit; push notifications have a monthly limit of the same size, counted separately. See Plans & limits.