Início rápido¶
1. Obtenha a chave¶
A chave de API está no portal, em Credenciais. Ela vai no cabeçalho Authorization de toda chamada:
Guarde a chave no servidor
Não coloque a chave em aplicativo, página web ou repositório público. Quem tem a chave envia em seu nome e consome seu saldo.
2. Envie um SMS¶
$ch = curl_init('https://sms.example.com/api/v1/sms');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHAVE'), 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode(['to' => '5511988887777', 'text' => 'Seu codigo e 4821']),
]);
echo curl_exec($ch);
Resposta:
{
"id": "a1b2c3d4-...",
"to": "5511988887777",
"status": "accepted",
"parts": 1,
"encoding": "GSM7",
"converted": false,
"price": 0.075,
"currency": "BRL"
}
Guarde o id: é por ele que você acompanha a mensagem.
3. Acompanhe a entrega¶
A mensagem passa por estes estados:
accepted → sent → delivered ou failed
- accepted: a plataforma aceitou e vai enviar.
- sent: a operadora aceitou.
- delivered / failed: o recibo do aparelho chegou.
- rejected: a mensagem não saiu da plataforma. O campo
errordiz o motivo (lista de erros).
Você pode consultar a qualquer momento:
Para não precisar consultar, configure um webhook: a plataforma avisa cada mudança.
Tamanho e codificação¶
| Codificação | Quando | 1 SMS | Por parte (mensagem longa) |
|---|---|---|---|
| GSM7 | Só caracteres do alfabeto GSM | 160 | 153 |
| UCS2 | Qualquer caractere fora dele | 70 | 67 |
Um único ã, ç, á ou emoji muda a mensagem inteira para UCS2 e reduz o limite para 70 caracteres. A cobrança é por parte. Use POST /sms/estimate para saber codificação, partes e preço antes de enviar.
Se a conversão de acentos estiver ativa na sua conta, a plataforma troca ã por a, ç por c e assim por diante quando isso faz o texto caber em GSM7. A resposta traz converted: true quando isso acontece.
Remetente¶
- Até 11 letras e números (
MINHAMARCA), ou um número de até 15 dígitos. - Só remetente numérico recebe respostas.
- Sem
from, a plataforma usa o remetente padrão da sua credencial.
Destino¶
Formato internacional, com código do país, de 8 a 15 dígitos. Espaços, +, pontos, traços e parênteses são ignorados: +55 (11) 98888-7777 vira 5511988887777.
Limite de velocidade¶
Cada credencial tem um limite de mensagens por segundo. Acima dele a API responde 429 throughput_exceeded; aguarde e tente de novo. Para campanhas, use POST /sms/batch, que controla o ritmo sozinho.