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.

Receive incoming messages by configuring webhooks on your application. When someone sends a message to your phone number, Chirp delivers it to your webhook endpoint in real-time.

​
Prerequisites

Before receiving messages, you need:
  • A phone number assigned to your application
  • A webhook configured for the MESSAGE_CREATED event
See Webhooks Setup for configuration details.

​
How It Works

  1. User sends an SMS or MMS to your Chirp phone number
  2. Chirp receives the message from the carrier
  3. Chirp creates a MESSAGE_CREATED event
  4. Chirp sends the event to your configured webhook URL
  5. Your application processes the message and responds

​
Webhook Payload

When an incoming message is received, Chirp sends a POST request to your webhook URL: 
{
  "event": "MESSAGE_CREATED",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": "+15559876543",
    "to": "+15551234567",
    "text": "Hello, this is an incoming message",
    "subject": null,
    "mediaUrls": [],
    "type": "SMS",
    "direction": "INBOUND",
    "status": "RECEIVED",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}

​
Payload Fields

event - The event type (MESSAGE_CREATED) data.id - Unique message identifier data.from - Phone number that sent the message data.to - Your Chirp phone number that received the message data.text - Message text content (null if MMS with no text) data.subject - MMS subject line (null for SMS) data.mediaUrls - Array of media URLs for MMS messages data.type - Message type (SMS or MMS) data.direction - Always INBOUND for received messages data.status - Message status (RECEIVED) data.createdAt - ISO 8601 timestamp

​
Handling MMS Messages

MMS messages may include media attachments: 
{
  "event": "MESSAGE_CREATED",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "from": "+15559876543",
    "to": "+15551234567",
    "text": "Check out this photo",
    "subject": "My Photo",
    "mediaUrls": ["https://media.chirp.com/messages/abc123/image.jpg"],
    "type": "MMS",
    "direction": "INBOUND",
    "status": "RECEIVED",
    "createdAt": "2024-01-15T12:00:00.000Z"
  }
}
Media files are hosted by Chirp and accessible via the URLs in mediaUrls.

​
Responding to Your Webhook

Your webhook endpoint should:
  1. Respond with a 200 OK status code
  2. Respond within 5 seconds
  3. Process the message asynchronously if needed
// Example Express.js webhook handler
app.post("/webhooks/sms", (req, res) => {
  const { event, data } = req.body;

  if (event === "MESSAGE_CREATED" && data.direction === "INBOUND") {
    // Acknowledge receipt immediately
    res.status(200).send("OK");

    // Process message asynchronously
    processIncomingMessage(data);
  }
});

​
Testing Incoming Messages

You have two options for testing incoming messages without sending a real SMS:
  • Browser-based Playground — open the Playground in your dashboard, pick a “User Phone Number”, and send. Your webhook fires in real-time.
  • API-based simulation — POST /v1/playground/sms/inbound with a test API key. Useful for end-to-end tests, CI, and local development. See Simulating Inbound Messages.

​
Webhook Retries

If your webhook endpoint fails to respond or returns an error:
  • Chirp will retry delivery
  • Retries use exponential backoff
  • Failed webhooks are logged in your dashboard
See Webhooks Setup for more details on retry behavior.