Leve o envio de SMS
para o seu serviço.

Início rápido

1. Crie uma API KEY

   Após o cadastro, a aprovação e o login com OTP, acesseGerenciar chaves APIpara criar a chave.

2. Adicione créditos

   A API usa o saldo e os preços da sua conta. Os créditos são cobrados quando o envio é aceito.

3. Envie e acompanhe os resultados

   Guarde o ID do envio e use a API de status para acompanhar os resultados.

Cobertura

GET/api/v1/messages/countries

Use a API para consultar os países ativos e os preços aplicados. Ao enviar, informe o país em country e use números do mesmo país em cada requisição. Países sem preço configurado não são aceitos.

{ "currency": "USDT", "countries": [{ "country": "US", "unitPrice": 0.02 }] }

Autentique com uma API KEY

Inclua o cabeçalho abaixo em todas as requisições à API externa. Cookies de login e códigos OTP não são necessários.

Authorization: Bearer hex_live_SUA_CHAVE_AQUI

A chave completa é exibida só uma vez, na criação. Guarde-a em uma variável de ambiente do servidor e nunca no código do frontend. Chaves revogadas ou de contas suspensas não funcionam. Você pode criar até 5 chaves.

Envie para até 1.000 números de uma vez

Envie o mesmo texto para vários números. Validamos a requisição, colocamos na fila de envio e respondemos na hora. Para enviar conteúdos diferentes por número, use requisições separadas com um novo Idempotency-Key.

Se houver qualquer número inválido ou duplicado, a requisição inteira é recusada, sem envio nem cobrança. Os duplicados são verificados após a conversão para o formato internacional.

curl -X POST 'https://hexsms.com/api/v1/messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: notice-20261024-001' \
  -d '{
    "country": "US",
    "text": "Your verification code is 482913.",
    "recipients": ["+12025550123", "+12025550124"]
  }'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "RUNNING",
  "total": 2,
  "segments": 1,
  "unitPrice": 0.025,
  "cost": 0.05,
  "createdAt": 1792800000000,
  "note": null,
  "replayed": false
}

Como o valor é calculado

Destinatários × segmentos (segments) × preço unitário da contaé a fórmula. Caracteres UCS-2 cabem 70 em 1 segmento e depois 67 por segmento. Caracteres GSM-7 básicos cabem 160 em 1 segmento e depois 153 por segmento. Caracteres estendidos contam 2, e emojis usam o comprimento UTF-16. unitPrice e cost estão em USDT. O preço na resposta é o preço realmente aplicado; o 0.025 acima é só um exemplo.

Confira o resultado de cada número

Use o id retornado pela API de envio. Só é possível consultar envios feitos pela API com a mesma conta. A consulta retorna os resultados armazenados. Se precisar dos resultados mais recentes da operadora, chame antes a API de atualização de status.

curl 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd?limit=1&offset=0' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{
  "id": "35bed356-b84a-452a-8e94-98b538972ecd",
  "country": "US",
  "state": "DONE",
  "total": 2, "segments": 1,
  "unitPrice": 0.025, "cost": 0.05,
  "createdAt": 1792800000000, "note": null,
  "summary": { "DELIVERED": 1, "PENDING": 1 },
  "messages": [
    {
      "id": "d2787184-d8b8-49c6-9c15-1db90a6d5516",
      "to": "12025550123",
      "status": "DELIVERED",
      "statusName": "DELIVERED_TO_HANDSET",
      "description": "Message delivered to handset",
      "error": null,
      "updatedAt": 1792800005000
    }
  ],
  "pagination": { "limit": 1, "offset": 0, "nextOffset": 1 }
}

limit vai de 1 a 1.000 (padrão 100) e offset de 0 a 1.000 (padrão 0). Se nextOffset for null, é a última página. summary traz a contagem de todos os números por status. to vem no formato internacional sem +, e os horários em milissegundos Unix. A ordem da consulta pode ser diferente da ordem original do envio; identifique cada message pelo seu id.

Obtenha o status de entrega mais recente

Consulta os logs da operadora e atualiza os resultados armazenados. Não é preciso enviar corpo. Depois, leia os resultados novamente com GET. Cada envio pode ser atualizado uma vez a cada 30 segundos. Os logs da operadora ficam disponíveis por 48 horas após o envio. Em ambientes com webhook configurado, os resultados podem ser atualizados automaticamente.

curl -X POST 'https://hexsms.com/api/v1/messages/35bed356-b84a-452a-8e94-98b538972ecd/refresh' \
  -H 'Authorization: Bearer YOUR_API_KEY'

{ "id": "35bed356-b84a-452a-8e94-98b538972ecd", "updated": 2 }

updated é o número de linhas atualizadas. Pode ser 0 se as mensagens ainda estiverem na fila ou não houver resultados novos. Recomendamos chamar GET em intervalos de pelo menos 10 segundos e usar refresh só quando necessário.

Entenda os códigos de status

state do envio

PREPARING: preparando · RUNNING: processando · PAUSED: pausado · DONE: fila processada · CANCELED: cancelado

As operadoras podem adicionar novos códigos, então trate também valores de status desconhecidos. Veja o motivo da falha em statusName, description e error.

Como tratar erros

{ "error": "Créditos insuficientes. Recarregue e tente novamente.", "code": "INSUFFICIENT_CREDITS" }

Cada API KEY permite até 120 requisições por minuto, somando envio, consulta e atualização. Ao atingir o limite, confira o cabeçalho Retry-After. A API é para integração entre servidores; chamadas CORS pelo navegador não são suportadas.

Conecte com Node.js

const response = await fetch('https://hexsms.com/api/v1/messages', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer ' + process.env.HEXSMS_API_KEY,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'notice-20261024-001'
  },
  body: JSON.stringify({
    country: 'US',
    text: 'Your order is on its way.',
    recipients: ['+12025550123', '+12025550124']
  })
});
const result = await response.json();
if (!response.ok) throw new Error(result.code + ': ' + result.error);
console.log(result.id); // Use this ID to check delivery status.

Crie a chave de requisição uma vez por operação e reutilize o mesmo valor ao tentar de novo quando não houver resposta. Reenviar com uma nova chave uma operação que já deu certo gera um envio separado.