> ## 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.

# Receiving Messages

> Handle incoming SMS and MMS messages with webhooks

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](/sms/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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```javascript theme={null}
// 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](/concepts/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](/concepts/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](/sms/webhooks-setup) for more details on retry behavior.