Quick Start - Notifique

Do zero ao primeiro SMS na fila em poucos passos. Comece com sk_test_... no Sandbox.

Em poucas palavras

Envie texto curto (9 a 160 caracteres) para um ou vários números.
Consulte histórico ou um envio pelo id.
Cancele enquanto o status for QUEUED ou SCHEDULED.

Contexto: Introdução. Escopos: Escopos da API Key.

Antes de começar

Item	Obrigatório
Chave com `sms:send`	Sim
Números em formato internacional (sem `+`)	Sim
`sms:read` / `sms:cancel`	Só se for consultar ou cancelar

Base URL: https://api.notifique.dev. Substitua sk_live_xxxxx pela sua chave (sk_test_... no sandbox).

1. Enviar SMS

to é sempre um array (até 100 destinatários).

POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "to": ["5511999999999", "5521988887777"],
  "type": "text",
  "payload": {
    "message": "Seu código é 482910. Válido por 10 minutos."
  }
}

Resposta (202)

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "messageIds": ["clxx123...", "clxx456..."],
    "smsIds": ["clxx123...", "clxx456..."]
  }
}

messageIds é o campo canônico. smsIds é alias de compatibilidade.

Menos de 9 caracteres em payload.message → 400 (SMS_MESSAGE_TOO_SHORT).

Enviar com template

Se você já tem um template do workspace com canal SMS habilitado, use type: "template", o mesmo padrão de WhatsApp, Telegram e os demais canais:

{
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "ID_DO_TEMPLATE",
    "variables": { "code": "482910", "name": "Maria" }
  }
}

A API resolve o texto do template, substitui variáveis e enfileira o SMS.

2. Listar histórico

GET /v1/sms/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

{
  "success": true,
  "data": [
    {
      "smsId": "clxx123...",
      "to": "5511999999999",
      "message": "Seu código é 482910...",
      "status": "DELIVERED",
      "sentAt": "2025-02-20T14:00:00.000Z",
      "deliveredAt": "2025-02-20T14:00:30.000Z"
    }
  ],
  "pagination": { "total": 42, "page": 1, "limit": 20, "totalPages": 3 }
}

3. Consultar um envio

GET /v1/sms/messages/:id
Authorization: Bearer sk_live_xxxxx

Retorna o mesmo formato de um item da listagem. Requer sms:read.

4. Agendar e cancelar

Agendar, inclua no POST de envio:

{
  "to": ["5511999999999"],
  "type": "text",
  "payload": {
    "message": "Lembrete amanhã às 9h."
  },
  "schedule": { "sendAt": "2025-03-01T09:00:00.000Z" }
}

Cancelar (QUEUED ou SCHEDULED):

POST /v1/sms/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

Créditos do agendamento voltam para o workspace. Escopo: sms:cancel.

5. Evitar duplicata

Header Idempotency-Key no POST. Repetições em até 24 h não criam dois envios iguais. Veja Segurança e Confiabilidade.

6. Webhooks (opcional)

Configure sms.sent, sms.delivered, sms.failed e MO (sms.received, sms.replied) para acompanhar sem polling. Guia: Eventos dos webhooks.

Todos os tipos de envio

Na referência da API (aba SMS), abra Enviar SMS (POST /v1/...) e escolha o exemplo no playground: Texto, Template, Agendado, Opções.

Próximos passos

Introdução: quando usar e ciclo de status
Escopos: permissões da chave
Eventos dos webhooks: status em tempo real
Respostas de erro: códigos HTTP e code

​Em poucas palavras

​Antes de começar

​1. Enviar SMS

​Enviar com template

​2. Listar histórico

​3. Consultar um envio

​4. Agendar e cancelar

​5. Evitar duplicata

​6. Webhooks (opcional)

​Todos os tipos de envio

​Próximos passos

Em poucas palavras

Antes de começar

1. Enviar SMS

Enviar com template

2. Listar histórico

3. Consultar um envio

4. Agendar e cancelar

5. Evitar duplicata

6. Webhooks (opcional)

Todos os tipos de envio

Próximos passos