Eventos y payloads de los webhooks de SMS

Los cinco eventos y la forma de lo que recibes en cada uno.

Última actualización 18 de octubre de 2026

SMS recibido

Se dispara cuando el dispositivo Android recibe un SMS. Es la base de los chatbots y las respuestas automáticas.

{
  "event": "received",
  "createdAt": "2026-08-14T10:30:45.123Z",
  "data": {
    "id": "msg_01H8Z",
    "from": "+14155550100",
    "message": "El jueves por la mañana, si puede ser.",
    "receivedAt": "2026-08-14T10:30:44.000Z",
    "conversationId": "conv_9f21",
    "deviceId": "dev_oppo_cph2577",
    "inReplyTo": {
      "id": "msg_01H8X",
      "reference": "appointment_8841",
      "body": "Tu cita del 10/08 a las 11:15 está confirmada.",
      "sentAt": "2026-08-14T09:02:11.000Z"
    }
  }
}

SMS enviado

Se dispara cuando el móvil entrega el mensaje a la red. sent, delivered y failed tienen todos la misma forma.

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

SMS entregado

Se dispara cuando la operadora confirma la entrega al destinatario. Es el evento que confirma de verdad que el mensaje ha llegado.

SMS fallido

Se dispara cuando falla el envío. El campo error indica el motivo.

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

Se dispara cuando alguien se da de baja. El mensaje entero tiene que ser una de las palabras clave, sin distinguir mayúsculas de minúsculas: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, SAIR o PARAR. "Please stop" no cuenta. A partir de ese momento, cualquier envío a ese número devuelve 403 recipient_opted_out.

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