# Message Events


## lead.message_sent

Triggered when an outbound SMS message is sent to a lead. This fires when the vendor accepts the message for delivery, not when the lead receives it.

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.message_sent",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "message": "Hey John, ..."
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.message` | string | The message body that was sent |

---

## lead.message_received

Triggered when an inbound SMS message from a lead is received and processed. Fires once per inbound message, regardless of lead status.

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.message_received",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "message": "Yes I'm interested"
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.message` | string | The inbound message text |

---

## lead.message_delivered

Triggered when an outbound SMS message is confirmed delivered by the carrier. This fires when delivery is confirmed, not when the message is initially sent.

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.message_delivered",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:05.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "message": "Hey John, ..."
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.message` | string | The delivered message body |

---

## lead.conversation_started

Triggered when the first outbound message to a lead is confirmed delivered. This marks the beginning of outreach — the conversation is considered "started" when the first delivery is confirmed by the carrier.

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.conversation_started",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "message": "Hey John, ..."
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.message` | string | The first message that was delivered |

---

## lead.carrier_optout_received

Triggered when a lead sends an inbound SMS containing a carrier opt-out keyword (STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT). The downstream DNC creation (which triggers `dnc.created`) happens separately afterward.

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.carrier_optout_received",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "message": "STOP"
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.message` | string | The lead's opt-out message text |

---

## lead.carrier_optin_received

Triggered when a lead sends an inbound SMS containing a carrier opt-in keyword (START, YES, UNSTOP).

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.carrier_optin_received",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "message": "START"
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.message` | string | The lead's opt-in message text |

---

## lead.carrier_help_received

Triggered when a lead sends an inbound SMS containing a carrier help keyword (HELP, INFO).

```json
{
  "metadata": {
    "apiVersion": "2026-02-09",
    "eventType": "lead.carrier_help_received",
    "campaignId": "abc456xyz",
    "eventTime": "2024-01-28T12:00:00.000Z"
  },
  "data": {
    "phone": "+1234567890",
    "externalLeadId": "abc123",
    "message": "HELP"
  }
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `data.phone` | string | E.164 formatted phone number |
| `data.externalLeadId` | string? | Your external lead ID, if one was provided |
| `data.message` | string | The lead's help message text |