SMS entrante

Una persona le escribió un SMS a tu código corto. Te llega como el evento sms.mo.{shortCode}.

3 min de lectura

Cuándo llega

Cada vez que llega un SMS a un código corto que tiene un destino registrado. El tipo termina en el código corto, en minúsculas y sin espacios: un SMS al 87654 llega como sms.mo.87654.

Quién lo recibe

Se registra un destino por código corto, nombrándolo: sms.mo.87654. Un destino que no nombra el código corto no recibe sus SMS. Si un código corto no tiene ningún destino registrado, los SMS que le lleguen se descartan: no se guardan ni se entregan después.

Para registrar tu código corto, sigue Activar los webhooks.

Qué trae

Campos de data
Campo	Tipo	Qué es	Ejemplo
`shortCode`	string	El código corto al que escribieron.	`87654`
`from`	string	El celular de quien escribió, en formato internacional y sin el signo `+`.	`573001234567`
`text`	string	El texto del mensaje, ya decodificado (con tildes y eñes).	`Hola, quiero más información`
`receivedAt`	string	Cuándo lo procesó Hablame para enviártelo, en UTC y con segundos (RFC 3339).	`2026-10-24T15:04:05Z`
`messageId`	string	Identificador del mensaje, con forma de UUID. Sin guiones y en minúsculas es el `id` del evento.	`0192f0c4-7b1e-7a3d-9c55-3e2a1b4c5d6e`

El mismo cuerpo, con sangría para leerlo. Lo que se firma es el texto exacto que llega, sin sangría.

{
  "id": "0192f0c47b1e7a3d9c553e2a1b4c5d6e",
  "type": "sms.mo.87654",
  "data": {
    "shortCode": "87654",
    "from": "573001234567",
    "text": "Hola, quiero más información",
    "receivedAt": "2026-10-24T15:04:05Z",
    "messageId": "0192f0c4-7b1e-7a3d-9c55-3e2a1b4c5d6e"
  }
}

El aviso completo

Lo que recibe tu destino (ejemplo firmado con el secreto de ejemplo)

POST /webhooks/hablame HTTP/1.1
Host: tu-dominio.com
Content-Type: application/json
User-Agent: Hablame-Webhooks/1
X-Hablame-Event-Type: sms.mo.87654
X-Hablame-Delivery-Id: wdl_01K8F3Q2Z9X7V4N6B5C2D1E0FA
X-Hablame-Timestamp: 1792854247
X-Hablame-Signature: sha256=333ed7a2b59cd8511cfefec69da4e04d6ef9925444f1225a97f729512b2ff04b
Idempotency-Key: wdl_01K8F3Q2Z9X7V4N6B5C2D1E0FA

{"id":"0192f0c47b1e7a3d9c553e2a1b4c5d6e","type":"sms.mo.87654","data":{"shortCode":"87654","from":"573001234567","text":"Hola, quiero más información","receivedAt":"2026-10-24T15:04:05Z","messageId":"0192f0c4-7b1e-7a3d-9c55-3e2a1b4c5d6e"}}

Repetidos y varios destinos

Un mismo aviso puede llegar más de una vez con el mismo X-Hablame-Delivery-Id. Descártalo si ya lo tienes.
Si registraste varios destinos para el mismo código corto, cada uno recibe su propio X-Hablame-Delivery-Id, pero el id del evento es el mismo en todos. Si esos destinos escriben en la misma base, usa el id para no guardar dos veces el mismo SMS.

Ten en cuenta

Un SMS largo llega en varios eventos, uno por fragmento, y hoy no trae datos para unirlos.
Los SMS entrantes llegan solo por webhook; no se reciben por la conexión SMPP.
Tras registrar el destino, los avisos pueden tardar hasta 30 segundos en empezar a llegar.