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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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).

{
  "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).

{
  "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