Desenvolvedores

Documentação

Envie SMS e RCS pela API HTTP ou por SMPP, acompanhe o status de cada mensagem e receba as atualizações no seu sistema.

Primeiros passos API de SMS RCS Webhooks SMPP Erros

Primeiros passos

Crie sua conta e adicione saldo via PIX ou USDT.
No painel, em Conexões API / SMPP, cadastre os IPs dos seus servidores. Só esses endereços conseguem usar a API e o SMPP.
Gere suas credenciais: o token da API e o usuário e a senha do SMPP. Eles aparecem uma única vez; guarde em local seguro.
Veja os seus SIDs/LAs (remetentes) no painel ou pela rota GET /api/v1/routes.

Autenticação

Todas as chamadas usam HTTPS e o token no cabeçalho Authorization:

Authorization: Bearer TOKEN
Content-Type: application/json

Nunca coloque o token em aplicativos, páginas web ou repositórios públicos. Se suspeitar de vazamento, gere novas credenciais no painel: as antigas deixam de funcionar na hora.

O endereço base da API é informado no painel, junto com as credenciais.

API de SMS

POST/api/v1/messages

Envia uma mensagem.

Campo	Obrigatório	Descrição
`sid`	sim	O SID/LA (remetente) da sua conta.
`to`	sim	Número de destino. No Brasil, com ou sem o 55 (5511999990000 ou 11999990000).
`text`	sim	Texto da mensagem.
`reference`	não	Seu identificador (até 128 caracteres). Reenviar a mesma referência não duplica o envio.
`channel`	não	sms (padrão) ou rcs.

curl -X POST https://[API]/api/v1/messages \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sid":"SID","to":"5511999990000","text":"Seu código é 482913","reference":"pedido-1001"}'

Resposta:

{ "id": "dx1234567", "status": "queued", "amount": 45000, "currency": "BRL" }

O campo amount é o valor cobrado em milionésimos da moeda (45000 = R$ 0,045).

Mensagens longas são aceitas: a Diamond X divide o texto e o aparelho mostra tudo junto, como uma mensagem só. Cada parte tem até 153 caracteres sem acento (ou 67 com acentos ou emojis), com limite de 20 partes. A cobrança é por parte; uma mensagem de até 160 caracteres (ou 70 com acentos) é uma parte só.

GET/api/v1/messages/{id}

Consulta o status de uma mensagem.

{ "id": "dx1234567", "status": "delivered", "phone": "5511999990000", "channel": "sms",
  "created_at": "…", "updated_at": "…", "delivered_at": "…" }

Status	Significado
`queued`	Na fila da Diamond X.
`sent`	Aceita pela operadora, aguardando confirmação.
`delivered`	Entregue no aparelho.
`undelivered`	A operadora não conseguiu entregar.
`failed`	Falhou ou foi recusada.
`unknown`	Sem confirmação final da operadora.

GET/api/v1/routes

Lista os SIDs/LAs ativos da sua conta, com canal (sms ou rcs), país, preço e moeda.

GET/api/v1/balance

Mostra o saldo disponível, o saldo reservado para envios em andamento e a moeda da conta.

RCS

Com um SID de RCS liberado na sua conta, use o mesmo endpoint de envio com "channel": "rcs":

{"sid":"SID_RCS","to":"5511999990000","text":"Sua compra saiu para entrega!","channel":"rcs"}

A mensagem chega com o nome, o logo e o selo de verificação da sua marca. Cards, carrossel e botões, e o cadastro do agente da sua marca, estão no guia de RCS dentro do painel.

Webhooks

Cadastre no painel uma URL HTTPS do seu sistema para receber as atualizações de status das mensagens, sem precisar consultar a API.

Cada chamada é assinada com HMAC-SHA256 no cabeçalho X-DiamondX-Signature, usando o segredo exibido no painel. Valide a assinatura antes de processar.
Responda com HTTP 2xx. Se o seu sistema estiver fora do ar, a Diamond X tenta de novo.
Use o id ou a sua reference para ligar o evento ao envio.

SMPP

Protocolo SMPP 3.4, com binds transmitter, receiver ou transceiver.
Até 3 conexões por conta, cada uma com usuário e senha próprios.
Relatórios de entrega (DLR) pelo deliver_sm, sempre que solicitados no registered_delivery.
Mensagens longas: envie as partes com UDH ou SAR; elas chegam juntas no aparelho.
Acesso liberado somente para os IPs cadastrados no painel.
O endereço, a porta, o usuário (system_id) e a senha aparecem no painel, em Conexões API / SMPP, depois do login.

Erros

Os erros voltam com o código HTTP e uma mensagem no campo error.

Código	Quando acontece
`400`	Campo inválido ou ausente, número inválido para o país do SID ou SID não ativo na conta.
`401`	Token ausente ou inválido.
`403`	Acesso não permitido: IP não cadastrado, conta inativa ou SID não liberado.
`404`	Mensagem não encontrada.

Dúvidas na integração? Fale com o suporte técnico: WhatsApp · site@diamondx.app