Eventos

Os cinco eventos e a forma do que recebes em cada um.

SMS recebido

Dispara quando o dispositivo Android recebe um SMS. É a base de chatbots e respostas automáticas.

json

{
  "event": "received",
  "createdAt": "2026-08-14T10:30:45.123Z",
  "data": {
    "from": "+351912345678",
    "message": "Quinta de manha, se for possivel.",
    "receivedAt": "2026-08-14T10:30:44.000Z",
    "conversationId": "conv_9f21",
    "deviceId": "dev_oppo_cph2577",
    "inReplyTo": {
      "id": "msg_01H8X",
      "reference": "marcacao_8841",
      "body": "A tua marcacao de 10/08 as 11:15 esta confirmada.",
      "sentAt": "2026-08-14T09:02:11.000Z"
    }
  }
}

O inReplyTo responde a "sim a quê?"

A última mensagem que aquele telemóvel enviou àquele número, com a referência que puseste no envio. Vem null quando não houve nenhuma.

SMS enviado

Dispara quando o telemóvel entrega a mensagem à rede. sent, delivered e failed trazem a mesma forma.

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": "marcacao_8841",
    "createdAt": "2026-08-14T09:02:10.000Z",
    "deliveredAt": "2026-08-14T10:31:02.000Z",
    "error": null
  }
}

SMS entregue

Dispara quando a operadora confirma a entrega ao destinatário. É o evento que confirma mesmo que a mensagem chegou.

SMS falhado

Dispara quando o envio falha. O campo error traz o motivo.

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": "numero invalido"
  }
}

Saída da lista (opted out)

Dispara quando alguém sai da lista. A mensagem inteira tem de ser uma das palavras, maiúsculas ou minúsculas: STOP, STOPALL, UNSUBSCRIBE, CANCEL, END, QUIT, SAIR ou PARAR. "Por favor parem" não conta. A partir daí qualquer envio para esse número devolve 403 recipient_opted_out.

A re-subscrição não dispara evento

START, UNSTOP ou SIM removem a saída, sem disparar evento. Se espelhas as saídas, confirma no endpoint de opt-outs antes de assumir que um número continua bloqueado.

json

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