API de Mensagens

Envie mensagens por sistemas externos usando a API REST do WhatsBlast.

Use a API para integrar agendas, ERPs, lojas virtuais, CRMs e automações. A API externa aceita texto, arquivos, imagem por URL, mensagens interativas e consulta de número.

Disponibilidade O acesso depende do seu plano e das permissões da conta. A tela API de Mensagens também possui formulários para testar os principais formatos antes de programar a integração.

Obter o token

Acesse API de Mensagens no menu lateral.
Copie o token da conexão que realizará o envio.
Guarde-o em uma variável secreta no seu sistema.

Cada token representa uma conexão específica. Para enviar por outro número, use o token daquela conexão; não existe um campo no payload para trocar a conexão.

Autenticação

Authorization: Bearer SEU_TOKEN
Content-Type: application/json

Proteja o token Nunca coloque o token em JavaScript público, aplicativo distribuído, print, repositório Git ou página HTML. Faça a chamada pelo backend do seu sistema.

Formato do número

Envie somente dígitos, com DDI e DDD. Exemplo brasileiro: 5518999991234. Não use +, espaços, parênteses ou hífens.

Enviar texto

POST /api/messages/send

{
  "number": "5518999991234",
  "body": "Olá! Sua consulta foi confirmada para amanhã às 14h."
}

Campos opcionais

Campo	Tipo	Uso
`msdelay`	number	Atraso em milissegundos antes do envio.
`quotedMsg`	string	ID da mensagem que será citada.
`userId`	number	Atendente válido da mesma empresa.
`queueId`	number	Fila válida da mesma empresa.
`sendSignature`	boolean	Inclui assinatura quando existir um atendente aplicável.
`closeTicket`	boolean	Solicita o encerramento do ticket depois do envio.
`noRegister`	boolean	Envia sem criar contato/ticket, quando suportado pelo fluxo.

Use IDs da sua própria conta Se informar userId ou queueId, eles precisam existir na mesma empresa do token.

Enviar arquivo

Use o mesmo endpoint com multipart/form-data. O campo do arquivo é medias e pode receber mais de um item.

POST /api/messages/send
Content-Type: multipart/form-data

number=5518999991234
body=Segue o documento solicitado
medias=@arquivo.pdf

Enviar imagem por URL

POST /api/messages/send/linkImage

{
  "number": "5518999991234",
  "url": "https://exemplo.com/comprovante.jpg",
  "caption": "Segue o comprovante"
}

A URL precisa estar acessível pela internet e apontar diretamente para a imagem.

Enviar mensagem interativa

POST /api/messages/send/interactive

O campo type aceita buttons, list ou url.

Botões de resposta

{
  "number": "5518999991234",
  "type": "buttons",
  "title": "Escolha uma opção",
  "body": "Como podemos ajudar?",
  "footer": "Equipe de atendimento",
  "buttons": [
    { "id": "financeiro", "text": "Financeiro" },
    { "id": "suporte", "text": "Suporte" }
  ],
  "queueId": 3
}

Esse formato utiliza no máximo três botões.

Lista de opções

{
  "number": "5518999991234",
  "type": "list",
  "title": "Serviços",
  "body": "Selecione o serviço desejado",
  "buttonText": "Ver opções",
  "sections": [
    {
      "title": "Atendimento",
      "rows": [
        {
          "id": "segunda_via",
          "title": "Segunda via",
          "description": "Consultar cobrança"
        },
        {
          "id": "suporte",
          "title": "Suporte",
          "description": "Falar com a equipe"
        }
      ]
    }
  ],
  "queueId": 3
}

Cada seção precisa conter pelo menos uma opção.

Botão de URL

{
  "number": "5518999991234",
  "type": "url",
  "title": "Acompanhe seu pedido",
  "body": "Clique no botão para abrir o rastreio.",
  "buttonText": "Abrir rastreio",
  "buttonUrl": "https://exemplo.com/rastreio/123",
  "queueId": 3
}

Compatibilidade dos interativos No fluxo atual, conexões WuzAPI usam o tipo url. Os tipos buttons e list são destinados às conexões compatíveis que não sejam WuzAPI. Teste na tela API de Mensagens usando o mesmo tipo de conexão da produção.

Verificar um número

POST /api/messages/checkNumber

{
  "number": "5518999991234"
}

Use essa consulta antes de cadastrar ou enviar para números recebidos de outro sistema.

Templates da API Oficial

Envio disponível pelo painel O envio de template oficial atualmente é feito dentro do ticket autenticado do WhatsBlast. Ele não faz parte dos endpoints externos por token documentados nesta página. Veja Templates Oficiais.

Respostas e códigos de erro

Em caso de sucesso, a resposta contém os dados gerados pelo envio. Trate também os erros HTTP:

Código	Causa comum	O que fazer
`400`	Payload inválido, campo ausente ou formato incompatível.	Revise os campos, o número e o tipo interativo.
`401`	Token ausente ou inválido.	Confira o header Authorization.
`404`	Conexão, fila ou usuário não encontrado.	Confirme o token e os IDs usados.
`500`	Falha durante o envio.	Confira o status da conexão e tente novamente com controle de repetição.

Boas práticas de integração

Teste cada payload na tela API de Mensagens.
Defina timeout na chamada do seu sistema.
Registre status e resposta sem gravar o token nos logs.
Evite repetir automaticamente uma mensagem que já pode ter sido enviada.
Monitore se a conexão está ativa.
Use filas e atendentes válidos quando quiser criar o ticket já distribuído.

Casos de uso

Agenda — lembrete de consulta ou compromisso.
E-commerce — atualização de pagamento, separação ou entrega.
ERP/CRM — aviso de proposta, cobrança ou etapa do processo.
Formulário — confirmação de cadastro ou solicitação.
Autoatendimento — lista ou botões para escolher o próximo passo.