API Developers Guia de integração
Referência da API

API para SMS e WhatsApp

Envie mensagens transacionais, campanhas, templates aprovados, mídias e acompanhe retornos de entrega com uma integração REST simples.

SMSEnvio simples, interativo e Flash.
WhatsAppTexto, mídia e templates aprovados.
ConsultasStatus, saldo e mensagens recebidas.
CallbacksAtualizações enviadas para sua URL.
Endpoint base
https://54.233.99.254/webservice-rest/

Todas as respostas da API são retornadas em JSON e podem ser acompanhadas por consulta ou callback.

20conexões simultâneas por usuário
5000mensagens por requisição em lote
32 diasjanela de consulta de histórico

Autenticação

Use usuário e senha da sua conta pelo header Authorization: Basic.

Obrigatório

O valor do Basic é formado por base64(usuario:senha). Também é possível enviar user e password por parâmetro, mas o header é a forma recomendada.

Header
Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==
UsoHeaders
Envio individual e consultasContent-Type: application/x-www-form-urlencoded
Envio em massa por loteContent-Type: application/json
Accept: application/json

Tipos de mensagem

O parâmetro type define o serviço usado no envio.

type
typeServiçoCampos principaisQuando usar
0SMS não interativocontentSMS simples, sem resposta.
1SMS interativo FlashcontentSMS interativo em modo Flash.
2SMS interativocontentSMS com possibilidade de resposta.
3WhatsApp Templatetemplate_name, contentTemplate aprovado do WhatsApp.
4WhatsApp áudiomediaEnviar áudio por URL.
5WhatsApp textocontentEnviar somente texto.
6WhatsApp imagemmedia, captionImagem JPG/JPEG com legenda opcional.
7WhatsApp documentomedia, captionDocumento PDF com legenda opcional.
8WhatsApp vídeomedia, captionVídeo MP4 com legenda opcional.
WhatsApp mídia: para type=4, type=6, type=7 e type=8, envie a URL no parâmetro media. O type=5 é apenas texto.

Envio individual

Use este endpoint para enviar uma mensagem para um único destinatário.

send-single
POSThttps://54.233.99.254/webservice-rest/send-single

Campos aceitos

CampoObrigatórioDescrição
userNão, se usar Basic AuthUsuário da conta.
passwordNão, se usar Basic AuthSenha da conta.
typeSimTipo da mensagem.
country_codeNãoDDI do país. Padrão Brasil: 55.
numberSimNúmero do destinatário sem DDI, sem espaços e sem símbolos.
senderSim para WhatsAppCanal remetente do WhatsApp, normalmente o phone_number_id.
contentSim para SMS, texto e template com variáveisTexto da mensagem ou variáveis do template.
mediaSim para WhatsApp mídiaURL pública HTTPS para áudio, imagem, documento ou vídeo.
captionNãoLegenda para imagem, documento ou vídeo. Áudio não aceita legenda.
template_nameSim para type=3Nome exato do template aprovado no WhatsApp.
campaign_idNãoIdentificador da mensagem no seu sistema.
scheduleNãoData de agendamento em YYYY-MM-DD HH:MM:SS.
timezoneNãoFuso horário, por exemplo -03:00.
utf8NãoUse 1 para SMS com acentos e caracteres especiais.
concatenationNãoUse 1 para permitir SMS longo.

Enviar SMS

cURL
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=2' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'content=Mensagem de teste' \
  --data-urlencode 'campaign_id=pedido-123'

Enviar WhatsApp texto

cURL
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=5' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'content=Olá! Sua solicitação foi recebida.' \
  --data-urlencode 'campaign_id=whatsapp-texto-001'

Enviar WhatsApp imagem, documento, vídeo ou áudio

TipoExtensão aceitaCampo da URLLegenda
type=4 áudio.mp3, .oggmediaNão
type=6 imagem.jpg, .jpegmediacaption opcional
type=7 documento.pdfmediacaption opcional
type=8 vídeo.mp4mediacaption opcional
Imagem
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=6' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'media=https://seudominio.com.br/imagens/produto.jpg' \
  --data-urlencode 'caption=Veja a imagem do produto solicitado.' \
  --data-urlencode 'campaign_id=whatsapp-imagem-001'
Documento PDF
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=7' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'media=https://seudominio.com.br/arquivos/boleto.pdf' \
  --data-urlencode 'caption=Segue o documento solicitado.' \
  --data-urlencode 'campaign_id=whatsapp-documento-001'
Vídeo MP4
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=8' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'media=https://seudominio.com.br/videos/apresentacao.mp4' \
  --data-urlencode 'caption=Assista ao vídeo de apresentação.' \
  --data-urlencode 'campaign_id=whatsapp-video-001'
Áudio
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=4' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'media=https://seudominio.com.br/audios/audio.mp3' \
  --data-urlencode 'campaign_id=whatsapp-audio-001'

Resposta de sucesso

JSON
{
  "success": true,
  "responseCode": "000",
  "responseDescription": "Success queued",
  "credit": "1",
  "balance": "99984",
  "id": "813831"
}

Template WhatsApp

O type=3 envia templates aprovados. A API grava as tags que o worker de disparo lê para montar o payload oficial do WhatsApp.

type=3
Obrigatório: informe sender, template_name, number e type=3. Se o template tiver variáveis, informe-as em content.

Como a API monta as tags internas

Quando você chama o endpoint, a API transforma os parâmetros em tags antes de gravar na fila. O worker de disparo lê essas tags.

Parâmetro enviadoTag gravadaUso no worker
template_name=pedido_status<template_name>pedido_status</template_name>Localiza o template aprovado do canal.
content=Willian;12345;enviado<variable>Willian;12345;enviado</variable>Preenche variáveis do corpo na ordem {{1}}, {{2}}, {{3}}.
content={...JSON...}<variable>{...JSON...}</variable>Preenche header, body e botões dinâmicos.

Template com variáveis simples no corpo

Se o template aprovado for Olá {{1}}, seu pedido {{2}} foi atualizado para {{3}}., envie os valores no content, separados por ponto e vírgula.

cURL
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=3' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'template_name=pedido_status' \
  --data-urlencode 'content=Willian;12345;enviado' \
  --data-urlencode 'campaign_id=whatsapp-template-001'
Tags gravadas na fila
<template_name>pedido_status</template_name>
<variable>Willian;12345;enviado</variable>

Template sem variáveis

Se o template não tiver campos dinâmicos, envie apenas template_name.

cURL
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=3' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'template_name=aviso_simples' \
  --data-urlencode 'campaign_id=whatsapp-template-002'

Template com header, body ou botão dinâmico

Quando o template tiver cabeçalho com mídia, cabeçalho com texto variável ou botão com parâmetro, envie o content em JSON.

Formato do content em JSON
{
  "header": {
    "text": ["valor do cabeçalho de texto"],
    "link": "https://seudominio.com.br/arquivo.pdf"
  },
  "body": ["valor de {{1}}", "valor de {{2}}"],
  "buttons": {
    "0": ["valor do botão 0"],
    "1": ["valor do botão 1"]
  }
}
Header com mídia: para template com cabeçalho de imagem, vídeo ou documento, envie a URL em content.header.link. O worker monta o componente do template a partir da tag <variable>.
Template com documento no header
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=3' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'template_name=boleto_cliente' \
  --data-urlencode 'content={"header":{"link":"https://seudominio.com.br/arquivos/boleto.pdf"},"body":["Willian","R$ 50,00","18/04/2026"]}' \
  --data-urlencode 'campaign_id=whatsapp-template-003'
Template com botão dinâmico
curl --location 'https://54.233.99.254/webservice-rest/send-single' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'type=3' \
  --data-urlencode 'sender=103888109342779' \
  --data-urlencode 'country_code=55' \
  --data-urlencode 'number=14999999999' \
  --data-urlencode 'template_name=acompanhar_pedido' \
  --data-urlencode 'content={"body":["Willian","12345"],"buttons":{"0":["12345"]}}' \
  --data-urlencode 'campaign_id=whatsapp-template-004'
Atenção: a ordem e a quantidade de valores precisam ser iguais ao template aprovado. Se o corpo tem {{1}}, {{2}} e {{3}}, envie três valores.

Envio em massa por lote

Use send-multiple para enviar mensagens em lote por JSON.

send-multiple
POSThttps://54.233.99.254/webservice-rest/send-multiple
Limite: envie no máximo 5000 mensagens por requisição. Use defaultValues para campos comuns e messages para os destinatários.

Estrutura do JSON

Modelo
{
  "defaultValues": {
    "type": 5,
    "country_code": 55,
    "sender": "103888109342779"
  },
  "messages": [
    {
      "number": "14999999999",
      "content": "Mensagem 1",
      "campaign_id": "wa-001"
    }
  ]
}

SMS em lote

cURL
curl --location 'https://54.233.99.254/webservice-rest/send-multiple' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "defaultValues": {
      "type": 2,
      "country_code": 55
    },
    "messages": [
      {
        "number": "14999999999",
        "content": "Mensagem SMS 1",
        "campaign_id": "sms-001"
      },
      {
        "number": "14988888888",
        "content": "Mensagem SMS 2",
        "campaign_id": "sms-002"
      }
    ]
  }'

WhatsApp texto em lote

cURL
curl --location 'https://54.233.99.254/webservice-rest/send-multiple' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "defaultValues": {
      "type": 5,
      "country_code": 55,
      "sender": "103888109342779"
    },
    "messages": [
      {
        "number": "14999999999",
        "content": "Olá! Esta é uma mensagem de WhatsApp.",
        "campaign_id": "wa-001"
      },
      {
        "number": "14988888888",
        "content": "Olá! Seu atendimento foi registrado.",
        "campaign_id": "wa-002"
      }
    ]
  }'

WhatsApp mídia em lote

Para mídia em lote, mantenha o mesmo padrão do envio individual: type conforme a mídia e URL no campo media.

cURL
curl --location 'https://54.233.99.254/webservice-rest/send-multiple' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ==' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "defaultValues": {
      "type": 6,
      "country_code": 55,
      "sender": "103888109342779"
    },
    "messages": [
      {
        "number": "14999999999",
        "media": "https://seudominio.com.br/imagens/produto-1.jpg",
        "caption": "Imagem do produto 1",
        "campaign_id": "wa-img-001"
      },
      {
        "number": "14988888888",
        "media": "https://seudominio.com.br/imagens/produto-2.jpg",
        "caption": "Imagem do produto 2",
        "campaign_id": "wa-img-002"
      }
    ]
  }'

Resposta do lote

JSON
{
  "success": true,
  "responseCode": "001",
  "responseDescription": "Batch processed",
  "credit": "2",
  "balance": "87018",
  "totalProcessed": "2",
  "totalSuccess": "2",
  "messages": [
    {
      "success": true,
      "responseCode": "000",
      "responseDescription": "Success queued",
      "credit": "1"
    }
  ]
}

Consultas

Consulte status, saldo e mensagens recebidas.

GET ou POST

Status por identificador

GEThttps://54.233.99.254/webservice-rest/mt_id
Por campaign_id
curl --location 'https://54.233.99.254/webservice-rest/mt_id?campaign_id=wa-001,wa-002&timezone=-03:00' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ=='
Por id
curl --location 'https://54.233.99.254/webservice-rest/mt_id?id=813831,813832&timezone=-03:00' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ=='

Status por período

GEThttps://54.233.99.254/webservice-rest/mt_date
Por período
curl --location 'https://54.233.99.254/webservice-rest/mt_date?start_date=2026-04-01%2000:00:00&end_date=2026-04-16%2023:59:59&type=5&status=0,1,2&timezone=-03:00' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ=='

Novas mensagens recebidas

GEThttps://54.233.99.254/webservice-rest/mo_new
Depois que uma mensagem é retornada em mo_new, ela não aparece novamente como nova em uma próxima consulta.
Recebidas novas
curl --location 'https://54.233.99.254/webservice-rest/mo_new?type=5&timezone=-03:00' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ=='

Mensagens recebidas por período

GEThttps://54.233.99.254/webservice-rest/mo
Recebidas por período
curl --location 'https://54.233.99.254/webservice-rest/mo?start_date=2026-04-01%2000:00:00&end_date=2026-04-16%2023:59:59&type=5&campaign_id=wa-001&timezone=-03:00' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ=='

Saldo

GEThttps://54.233.99.254/webservice-rest/balance
Consultar saldo
curl --location 'https://54.233.99.254/webservice-rest/balance' \
  --header 'Authorization: Basic U2V1VXN1YXJpbzpTdWFTZW5oYQ=='
Resposta
{
  "success": true,
  "responseCode": "200",
  "responseDescription": "Successful search",
  "sms": "7289",
  "whatsapp": "606",
  "activation": "2026-03-30 12:10:59",
  "expiration": "2027-03-30 23:59:59"
}

Callbacks

Configure uma URL para receber status de entrega e mensagens recebidas.

HTTP GET

Status de entrega

Exemplo recebido pelo seu sistema
https://suaurl.com/callback.php?campaign_id=abc123&id=150&status=0&date=2026-04-16+10:00:00&carrier=Whatsapp

Mensagem recebida

Exemplo recebido pelo seu sistema
https://suaurl.com/callback.php?number=5514999999999&content=Recebido&campaign_id=abc123&id=150&status=4&date=2026-04-16+10:05:00&carrier=Whatsapp
CampoDescrição
campaign_idIdentificador enviado por você na requisição.
idID interno da mensagem na plataforma.
statusStatus da mensagem, ou 4 para mensagem recebida.
dateData do evento.
carrierOperadora ou canal, como Whatsapp.
numberNúmero do cliente que respondeu.
contentConteúdo recebido do cliente.
Responda HTTP 200 rapidamente. Grave o evento e processe em fila se precisar executar tarefas pesadas.

Status

As chamadas retornam responseCode. As mensagens possuem status próprio de envio.

Referência

Status de chamada

responseCodeDescriçãosuccess
000Success queuedtrue
001Batch processedtrue
002Scheduledtrue
010User or password is invalidfalse
020Empty or invalid typefalse
030Empty message contentfalse
040Scheduling date invalid or incorrectfalse
050Empty or invalid numberfalse
060International sending not allowedfalse
070Message rejected by serverfalse
080Insufficient or expired balancefalse
090Blocked account - Please contact supportfalse
100This service is currently under maintenancefalse
110There was an error processing, please try again, or contact usfalse
120Message array cannot exceed 5000false
130Message array is emptyfalse
140Incorrect time zonefalse
150File extension not allowedfalse
160Unknown method or unknown parameterfalse
170Invalid search attributesfalse
200Successful searchtrue

Status de envio

StatusDescriçãoCallback
-1Mensagem enfileirada.Não
3Preparando para envio.Não
6Mensagem pausada.Não
-9Bloqueado, sem cobertura.Sim
-8Bloqueado, conteúdo não permitido.Sim
-7Número sem WhatsApp ou indisponível.Sim
-6Mensagem cancelada.Sim
-5Bloqueado, lista negra.Sim
-4Bloqueado, número fixo.Sim
-3Bloqueado, número inválido.Sim
-2Erro na rede ou falha de entrega.Sim
0Enviado.Sim
1Entregue.Sim
2Lido no WhatsApp.Sim
4Mensagem recebida do cliente.Sim
7Expirada.Sim
8Rejeitada.Sim
9Não recebida no aparelho.Sim

Problemas comuns

Verificações rápidas para falhas frequentes de integração.

Checklist

WhatsApp não envia mídia

  • A URL precisa abrir sem login.
  • O servidor não pode retornar 403 Forbidden.
  • Use as extensões aceitas pela API.
  • O certificado HTTPS precisa ser válido.
  • Áudio WebM não é aceito para envio no WhatsApp.

Erro de saldo

Quando a API retornar responseCode=080, o saldo está insuficiente ou os créditos estão vencidos para o serviço solicitado.

Template não envia

  • Use o nome exato do template aprovado.
  • Confira se o template pertence ao canal informado no sender.
  • Envie a mesma quantidade de variáveis exigida pelo template.
  • Para header, body e botões dinâmicos, use JSON no content.