Skip to main content
Esta página é para quem vai disparar SMS a partir de um sistema (e-commerce, ERP, automação). Se você só usa o painel, o fluxo de envio é parecido, sem precisar montar esses pedidos na mão.

​
Antes de começar

Você vai precisar de:
  • Uma chave de API do workspace onde o SMS está habilitado. Cada chave pertence a um workspace — a API resolve isso sozinha.
  • Permissão para enviar e, se for listar ou consultar, permissão de leitura; para cancelar agendado, permissão de cancelamento (na doc técnica: sms:send, sms:read, sms:cancel).
  • Texto da mensagem com entre 9 e 160 caracteres (espaços nas pontas contam na regra de validação do produto).
  • Números no formato internacional (ex.: 5511999999999 para celular em São Paulo).
  • URL base da API (exemplos usam https://api.notifique.dev).
Substitua sk_live_xxxxx pela sua chave.

​
O caminho em três ideias

  1. Enviar com o texto e a lista de destinos → a API devolve ids e status (na fila ou agendado).
  2. Acompanhar listando ou abrindo um envio pelo id.
  3. Se estiver só agendado, ainda dá para cancelar a tempo.

​
1. Enviar SMS

Um pedido pode ir para vários números de uma vez (até o limite do produto). Pedido 
POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "to": ["5511999999999", "5521988887777"],
  "message": "Sua mensagem de teste (mín. 9, máx. 160 caracteres)."
}
Resposta (202) — entrou na fila 
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "smsIds": ["clxx123...", "clxx456..."]
  }
}
Resposta (202) — agendado Se você incluir data/hora de envio no corpo (schedule.sendAt), o status pode vir como agendado, com scheduledAt preenchido.

​
Extras úteis

  • Prioridade da fila (high, normal, low).
  • Webhook só daquele envio — URL HTTPS para receber eventos daquele lote.
  • Metadados — pares texto→texto para você achar depois no seu sistema.
Detalhes no OpenAPI, rota POST /v1/sms/messages.

​
2. Listar histórico

Pedido 
GET /v1/sms/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
Dá para filtrar por período e por status (vários separados por vírgula). A resposta traz lista + paginação. Resposta (200) — exemplo 
{
  "success": true,
  "data": [
    {
      "smsId": "clxx123...",
      "to": "5511999999999",
      "message": "Sua mensagem...",
      "status": "DELIVERED",
      "sentAt": "2025-02-20T14:00:00.000Z",
      "deliveredAt": "2025-02-20T14:00:30.000Z",
      "failedAt": null,
      "scheduledFor": null,
      "errorMessage": null,
      "createdAt": "2025-02-20T14:00:00.000Z"
    }
  ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
}

​
3. Ver um envio pelo id

Pedido 
GET /v1/sms/messages/:id
Authorization: Bearer sk_live_xxxxx
Resposta (200) — exemplo 
{
  "success": true,
  "data": {
    "smsId": "clxx123...",
    "to": "5511999999999",
    "message": "Sua mensagem...",
    "status": "DELIVERED",
    "sentAt": "2025-02-20T14:00:00.000Z",
    "deliveredAt": "2025-02-20T14:00:30.000Z",
    "createdAt": "2025-02-20T14:00:00.000Z"
  }
}

​
4. Webhooks (opcional)

Configure na conta eventos como “enviado”, “entregue” e “falhou”. Seu sistema recebe um POST e pode atualizar pedido, ticket ou relatório. O formato está em Eventos dos webhooks.

​
5. Agendar e cancelar

Agendar — no mesmo POST de envio, inclua schedule com a data/hora em formato internacional (ISO 8601). Cancelar — só vale para o que ainda está só agendado; depois que entrou na fila de envio, não dá para desfazer. 
POST /v1/sms/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx
Quando o cancelamento é aceito, os créditos daquele SMS costumam voltar para o workspace (conforme regra do produto).

​
Texto muito curto

Se a mensagem tiver menos de 9 caracteres (depois de limpar espaços nas pontas), a API responde 400 com código SMS_MESSAGE_TOO_SHORT. Vale também para texto montado por template ou enviado pelo painel — o limite é o mesmo conceito de “SMS curto demais”.

​
Evitar envio em duplicata

Na hora do POST de envio, use o cabeçalho Idempotency-Key (ou x-idempotency-key) com um valor único por tentativa lógica de envio. Se a rede repetir o mesmo pedido, o sistema pode reconhecer e não disparar de novo.

​
Continuar