Enviar uma mensagem

O endpoint que põe um SMS na fila de um dos teus telemóveis.

POSThttps://api.droidsender.com/api/v1/sms/send

A mensagem entra na fila do telemóvel e sai por ordem de chegada. A resposta não espera pelo envio: queued quer dizer aceite.

Corpo do pedido

Campo	Tipo	Obrigatório	Descrição
`to`	string	sim	Número em formato E.164, com indicativo de país
`message`	string	sim	Texto da mensagem, até 1530 caracteres (10 segmentos)
`deviceId`	string	não	Telemóvel a usar. Sem ele, escolhemos o que tiver menos fila
`reference`	string	não	O teu identificador, devolvido nos webhooks desta mensagem

Pedido

bash

curl -X POST https://api.droidsender.com/api/v1/sms/send \
  -H "Content-Type: application/json" \
  -H "X-API-Key: DS-live-a-tua-chave" \
  -d '{
    "to": "+351912345678",
    "message": "Confirmamos a sua consulta de dia 10/08 as 11h15.",
    "deviceId": "dev_oppo_cph2577",
    "reference": "consulta_8841"
  }'

Resposta

json

{
  "id": "msg_01H8X2",
  "status": "queued",
  "to": "+351912345678",
  "deviceId": "dev_oppo_cph2577",
  "reference": "consulta_8841",
  "segments": 1,
  "encoding": "GSM-7",
  "quota": { "used": 128, "included": 5000, "remaining": 4872 },
  "deviceOnline": true,
  "createdAt": "2026-08-16T14:22:05Z"
}

Repetir sem enviar duas vezes

Manda o cabeçalho Idempotency-Key. Repetir um pedido com a mesma chave devolve a resposta original em vez de um segundo SMS. As chaves duram 24 horas; um corpo diferente com a mesma chave devolve 409 idempotency_conflict.

bash

curl -X POST https://api.droidsender.com/api/v1/sms/send \
  -H "X-API-Key: DS-live-a-tua-chave" \
  -H "Idempotency-Key: marcacao_8841_lembrete" \
  -H "Content-Type: application/json" \
  -d '{ "to": "+351912345678", "message": "Lembrete" }'

Ler uma conversa

GEThttps://api.droidsender.com/api/v1/conversations/:id/messages

Devolve o fio por ordem cronológica. O conversationId chega no webhook received. O limit aceita 1 a 100, por omissão 20.

json

{
  "conversationId": "conv_9f21",
  "phone": "+351912345678",
  "deviceId": "dev_oppo_cph2577",
  "messages": [
    {
      "id": "msg_01H8X",
      "direction": "outbound",
      "body": "A tua marcacao de 10/08 as 11:15 esta confirmada.",
      "status": "delivered",
      "reference": "marcacao_8841",
      "at": "2026-08-14T09:02:11Z"
    },
    {
      "id": "msg_01H8Z",
      "direction": "inbound",
      "body": "Quinta de manha, se for possivel.",
      "status": "delivered",
      "reference": null,
      "at": "2026-08-14T10:30:44Z"
    }
  ]
}

Consultar uma mensagem mais tarde

GEThttps://api.droidsender.com/api/v1/messages/:id

Devolve o estado atual de uma mensagem. Serve para reconciliar quando um webhook não chegou.

json

{
  "id": "msg_01H8X2",
  "status": "delivered",
  "to": "+351912345678",
  "deviceId": "dev_oppo_cph2577",
  "segments": 1,
  "encoding": "GSM-7",
  "reference": "marcacao_8841",
  "createdAt": "2026-08-16T14:22:05Z",
  "deliveredAt": "2026-08-16T14:22:41Z",
  "error": null
}

Um SMS pode custar mais do que um SMS

Cada segmento conta como um envio. O campo segments da resposta diz quantos a mensagem usou.