Events

The five events and the shape of what you receive in each one.

SMS received

Fires when the Android device receives an SMS. This is the basis of chatbots and auto-replies.

json

{
  "event": "received",
  "createdAt": "2026-08-14T10:30:45.123Z",
  "data": {
    "from": "+351912345678",
    "message": "Thursday morning, if possible.",
    "receivedAt": "2026-08-14T10:30:44.000Z",
    "conversationId": "conv_9f21",
    "deviceId": "dev_oppo_cph2577",
    "inReplyTo": {
      "id": "msg_01H8X",
      "reference": "appointment_8841",
      "body": "Your appointment on 10/08 at 11:15 is confirmed.",
      "sentAt": "2026-08-14T09:02:11.000Z"
    }
  }
}

inReplyTo answers "yes to what?"

The last message that phone sent to that number, with the reference you set when sending. Null when there was none.

SMS sent

Fires when the phone hands the message to the network. sent, delivered and failed all carry the same shape.

json

{
  "event": "delivered",
  "createdAt": "2026-08-14T10:31:02.400Z",
  "data": {
    "id": "msg_01H8X",
    "status": "delivered",
    "to": "+351912345678",
    "deviceId": "dev_oppo_cph2577",
    "segments": 1,
    "encoding": "GSM-7",
    "reference": "appointment_8841",
    "createdAt": "2026-08-14T09:02:10.000Z",
    "deliveredAt": "2026-08-14T10:31:02.000Z",
    "error": null
  }
}

SMS delivered

Fires when the carrier confirms delivery to the recipient. This is the event that really confirms the message arrived.

SMS failed

Fires when the send fails. The error field carries the reason.

json

{
  "event": "failed",
  "createdAt": "2026-08-14T10:31:15.789Z",
  "data": {
    "id": "msg_01H8Y",
    "status": "failed",
    "to": "+351967880231",
    "deviceId": "dev_oppo_cph2577",
    "segments": 1,
    "encoding": "GSM-7",
    "reference": null,
    "createdAt": "2026-08-14T10:30:02.000Z",
    "deliveredAt": null,
    "error": "invalid number"
  }
}

Opted out

Fires when someone opts out. The whole message has to be one of the keywords, case-insensitive: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, SAIR or PARAR. "Please stop" does not count. From then on any send to that number returns 403 recipient_opted_out.

Re-subscribing does not fire an event

START, UNSTOP or SIM remove the opt-out, with no event fired. If you mirror opt-outs, check the opt-outs endpoint before assuming a number is still blocked.

json

{
  "event": "opted_out",
  "createdAt": "2026-08-14T10:32:00.000Z",
  "data": {
    "phoneNumber": "+351912345678",
    "at": "2026-08-14T10:32:00.000Z",
    "keyword": "STOP"
  }
}