Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.buildwithchirp.com/llms.txt

Use this file to discover all available pages before exploring further.

The Playground is a browser-based testing environment where you can simulate SMS messaging scenarios without sending real messages or incurring charges. It allows you to test both inbound and outbound message flows, validate webhook configurations, and debug your integration logic in real-time.
The Playground works exclusively with test applications and is completely free to use.

​
What You Can Do

The Playground supports SMS messaging with the following capabilities:
  • Send test messages as a user to your application (inbound)
  • Send test messages from your application to simulated users (outbound)
  • View all messages in real-time
  • Test webhook delivery and payloads
  • Debug integration logic

​
User and System Phone Numbers

The Playground simulates messaging scenarios using two types of phone numbers:

System Phone Numbers

Simulate messages from your application to external users (outbound messages). Use this to test:
  • Sending notifications
  • Alert systems
  • Two-way conversations

User Phone Numbers

Simulate messages from external users to your application (inbound messages). Use this to test:
  • Webhook handling for incoming messages
  • Auto-reply logic
  • Message processing workflows

​
Simulating inbound messages from code

Want to drive the same simulation from a script or test suite instead of the browser? Use the Playground inbound API:
  • POST /v1/playground/sms/inbound
  • POST /v1/playground/whatsapp/inbound
These endpoints take a test app key (sk_test_app_*) and queue an inbound message that flows through the same processor as a real provider webhook. See Simulating Inbound Messages.

​
Managing Playground phone numbers from code

Listing and allocating the system / user phone numbers used in the Playground is exposed via two parallel API surfaces. Choose the one that matches who is calling:

App-key surface

Path prefix: /v1/playground/...Auth: test app key (sk_test_app_*)Use when: driving the Playground from your own application or a test script — the target app is implicit from the key.

Admin / session surface

Path prefix: /v1/organization/playground/...Auth: admin key (sk_admin_*) or a user sessionUse when: operating across apps (e.g. the dashboard, internal tools). Pass the target app via the x-app-id header.
Both surfaces expose the same four operations per platform (SMS and WhatsApp):
MethodPath (app surface)Path (admin surface)Purpose
GET/v1/playground/phone-numbers/system/v1/organization/playground/phone-numbers/systemList system (outbound) numbers linked to the test app.
POST/v1/playground/phone-numbers/system/v1/organization/playground/phone-numbers/systemPurchase a new system number for the test app.
GET/v1/playground/phone-numbers/user/v1/organization/playground/phone-numbers/userList user (inbound) numbers already used in simulations.
POST/v1/playground/phone-numbers/user/v1/organization/playground/phone-numbers/userGenerate a fresh user number to simulate a new sender.
The WhatsApp equivalents live under /whatsapp/phone-numbers/... in both surfaces.
Playground operations always target your test app, even if you pass a production app ID. Chirp resolves the linked test app automatically.

​
App-key example

List system WhatsApp numbers (app key)
curl https://api.buildwithchirp.com/v1/playground/whatsapp/phone-numbers/system \
  -H "Authorization: Bearer YOUR_TEST_API_KEY"

​
Admin-key example

List system WhatsApp numbers (admin key)
curl https://api.buildwithchirp.com/v1/organization/playground/whatsapp/phone-numbers/system \
  -H "Authorization: Bearer YOUR_ADMIN_API_KEY" \
  -H "x-app-id: app_xxx"
Both calls return the same response:
200 OK
{
  "numbers": ["+15551234567", "+15557654321"]
}

​
Moving to Production

To use your integration in production, replace your test API key (sk_test_app_*) with your live API key (sk_live_app_*). No other changes are required.