Skip to main content
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

Use the Playground to test incoming messages without sending real SMS:
  1. Open the Playground in your dashboard
  2. Use a “User Phone Number” to simulate sending to your application
  3. Your webhook will receive the message in real-time

​
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.
⌘I