Skip to main content

​
O fluxo principal (visão geral)

  1. Enviar com POST /v1/sms/messages (texto entre 9 e 160 caracteres, números em E.164).
  2. Anotar os smsIds da resposta 202.
  3. Listar ou consultar por ID com sms:read; cancelar só se ainda estiver SCHEDULED.

​
Pré-requisitos

  • API Key com escopos: sms:send, sms:read (e opcionalmente sms:cancel para agendados).
  • Envie a API Key em toda requisição:
    • Header: Authorization: Bearer sk_live_xxxxx
    • ou Header: x-api-key: sk_live_xxxxx

​
1. Enviar SMS

Envie um ou mais SMS para os números informados. O texto da mensagem deve ter no mínimo 9 e no máximo 160 caracteres (espaços nas pontas são ignorados na validação). Cada destinatário consome créditos do plano. Request 
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)."
}
Response (202) — envio imediato 
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 2,
    "smsIds": ["clxx123...", "clxx456..."]
  }
}
Response (202) — agendado Se incluir schedule.sendAt: 
{
  "success": true,
  "data": {
    "status": "SCHEDULED",
    "count": 2,
    "smsIds": ["clxx123...", "clxx456..."],
    "scheduledAt": "2025-12-31T14:00:00.000Z"
  }
}

​
2. Listar SMS

Liste o histórico de SMS do workspace com paginação (mesmo escopo sms:read que a consulta por ID). Filtros opcionais: fromDate, toDate (ISO 8601, campo createdAt), status (vários separados por vírgula, ex.: DELIVERED,FAILED). Request 
GET /v1/sms/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "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. Consultar status

Obtenha o status e os dados de um SMS pelo ID. Request 
GET /v1/sms/messages/:id
Authorization: Bearer sk_live_xxxxx
Response (200) 
{
  "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)

Para receber notificações em tempo real, configure um webhook com eventos:
  • sms.sent — SMS aceito e enviado ao provedor.
  • sms.delivered — SMS entregue (DLR).
  • sms.failed — SMS falhou no envio ou foi reportado como falha.
No payload dos eventos SMS, o campo instanceId vem vazio; os dados vão em data (smsId, to, status, sentAt, deliveredAt, failedAt, etc.). Consulte WEBHOOKS_ESCOPOS.md para o formato completo.

​
5. Agendamento e cancelamento

Agendar: inclua no body do POST /v1/sms/messages: 
{
  "to": ["5511999999999"],
  "message": "Lembrete agendado.",
  "schedule": {
    "sendAt": "2025-12-31T14:00:00.000Z"
  }
}
Cancelar: use o escopo sms:cancel e chame: 
POST /v1/sms/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx
Os créditos do SMS cancelado são devolvidos ao workspace.

​
Validação da mensagem

Se message tiver entre 1 e 8 caracteres (após trim), a API responde 400 com code: SMS_MESSAGE_TOO_SHORT. O mesmo limite mínimo vale para SMS enviados pelo painel, por template (texto final após variáveis) e na fila (SMS já gravados com texto curto podem falhar ao processar).

​
Resumo do fluxo

  1. POST /v1/sms/messages com to e message → enfileirar ou agendar SMS.
  2. GET /v1/sms/messages → listar histórico com paginação e filtros (escopo sms:read).
  3. GET /v1/sms/messages/:id → consultar um envio pelo ID.
  4. (Opcional) Configurar webhook para sms.sent, sms.delivered, sms.failed.
  5. (Opcional) Para agendados: POST /v1/sms/messages/:id/cancel para cancelar.

​
Referências

  • Idempotência: use o header Idempotency-Key ou x-idempotency-key no envio para evitar duplicatas.