Lethall Hub API v1 • Documentação Oficial da API de Envio

Visão geral

i

O que esta API faz

Recebe número e mensagem, valida token e registra/processa o envio pela instância permitida.

Para desenvolvedores

Use o endpoint send e envie Authorization: Bearer.

Para painéis (HubSoft / SGP)

Use os manuais no final desta página.

Endpoints corretos

Uso	Endpoint	Quando usar
Dev / HubSoft	https://lethallhost.com.br/api/whatsapp/v1/public/send	Integração por código e mensageiro do HubSoft
SGP	https://lethallhost.com.br/api/whatsapp/v1/public/send	Usar no modo HTTP Genérico com JSON e Authorization Bearer
Chatbots	https://lethallhost.com.br/api/whatsapp/v1/public/bot_send	Respostas de bot/atendimento — sem o botão "Bloquear contato", com suporte a figurinha/gif/botões/lista/enquete/localização/contato/reação

Guia Dev (principal)

Autenticação

Preferência: header Authorization: Bearer SEU_TOKEN

Prioridade	Local	Campo
1	Header	Authorization: Bearer
2	Body/Query	token / apikey

Parâmetros

Campos obrigatórios + opcionais mais usados

Campo	Obrigatório	Aliases
to	Sim	número, number, phone
message	Sim	mensagem, msg, text
instance_id	Não	instância, instance
agendamento	Não	Recomendado: sim

Exemplos prontos

Os exemplos abaixo são os mais usados em produção. Copie e troque o token/número.

1) POST JSON (recomendado)

curl -X POST "https://lethallhost.com.br/api/whatsapp/v1/public/send" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "to": "5561999999999", "message": "Olá! Teste Lethall Hub (JSON).", "instance_id": 1, "agendamento": "sim" }'

2) POST FORM (x-www-form-urlencoded)

curl -X POST "https://lethallhost.com.br/api/whatsapp/v1/public/send" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/x-www-form-urlencoded; charset=utf-8" \ --data-urlencode "numero=5561999999999" \ --data-urlencode "mensagem=Teste Lethall Hub (FORM)" \ --data-urlencode "instance_id=1" \ --data-urlencode "agendamento=sim"

3) JavaScript (fetch)

async function lethallHubSend() { const url = "https://lethallhost.com.br/api/whatsapp/v1/public/send"; const payload = { to: "5561999999999", message: "Teste Lethall Hub (fetch).", instance_id: 1, agendamento: "sim" }; const r = await fetch(url, { method: "POST", headers: { "Authorization": "Bearer SEU_TOKEN_AQUI", "Content-Type": "application/json; charset=utf-8" }, body: JSON.stringify(payload) }); const data = await r.json().catch(() => null); console.log(r.status, data); return { status: r.status, data }; }

Respostas HTTP

Status	Significado	Ação
200	Envio aceito / registrado	OK
202	Fila (instância indisponível)	Aguarde / mantenha agendamento=sim
401	Token ausente/inválido	Corrigir token
403	Sem permissão/instância	Validar permissões do token
406	Bloqueio de segurança	Teste payload simples

Exemplos de retorno

200

{"ok":true,"id":1421,"status":"queued","message":"Mensagem na fila."}

202

{"ok":false,"error":"instance_not_online","instance_status":"qrcode","queue_id":456}

401

{"ok":false,"error":"missing_token"}

403

{"ok":false,"error":"instance_not_allowed"}

406

{"ok":false,"error":"not_acceptable_modsecurity"}

Boas práticas rápidas

• Número no padrão 55DDDNUMERO
• Comece com mensagem simples
• Prefira POST JSON em produção
• Não exponha token em prints

Chatbots (bot_send)

🤖

Endpoint dedicado para respostas de chatbot/atendimento

Mesma autenticação e mesmas travas do endpoint send (token, instância online, opt-out, horário comercial, teto diário) — mas nunca acrescenta o rodapé/botão "Bloquear contato" às mensagens, e aceita muito mais tipo de conteúdo.

Endpoint

https://lethallhost.com.br/api/whatsapp/v1/public/bot_send

Quando usar

Respostas de um fluxo conversacional (bot de atendimento, menu interativo, confirmação de agendamento etc.) — o contato já está numa conversa ativa, então o botão de descadastro não faz sentido em toda mensagem.

Quando usar send em vez deste

Disparo avulso/notificação (lembrete de fatura, aviso de manutenção) para alguém que não está numa conversa ativa — aí o botão de opt-out é importante.

Tipos suportados

type	Campo(s)	Observação
text	message	padrão quando nenhum outro campo é enviado
image / video / audio / document	image, video, audio, document (URL) + caption	mesmos campos do endpoint send
sticker	sticker (URL)	figurinha — webp estático ou animado
gif	gif (URL)	enviado como vídeo curto — é assim que o WhatsApp reproduz "gif" de verdade
buttons	payload.title/description/buttons[]	até 3 botões de resposta rápida ou 1 de URL
list	payload.title/description/buttonText/sections[]	menu de opções em lista
carousel	payload.cards[]	cartões com imagem + botões
poll	payload.question/options[]	enquete nativa
location	payload.latitude/longitude/name/address	localização
contact / vcard	payload.name/phone/org	cartão de contato (vCard)
reaction	payload.message_id/emoji	reage com emoji a uma mensagem já trocada
composite	payload.blocks[]	vários blocos (texto/mídia/botões/etc.) em sequência numa só chamada

Importante: figurinha/gif/botões/lista/carrossel/enquete/localização/contato/reação/composta só existem em instâncias conectadas via Evolution (chip próprio) — canal oficial (Gupshup/360dialog) só suporta texto e mídia simples (imagem/vídeo/áudio/documento), a mesma limitação do WhatsApp Cloud API.

Exemplo — texto simples

curl -X POST "https://lethallhost.com.br/api/whatsapp/v1/public/bot_send" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "to": "5561999999999", "message": "Olá! Em que posso ajudar?", "instance_id": 1 }'

Exemplo — figurinha

curl -X POST "https://lethallhost.com.br/api/whatsapp/v1/public/bot_send" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "to": "5561999999999", "type": "sticker", "sticker": "https://exemplo.com/figurinha.webp", "instance_id": 1 }'

Exemplo — botões nativos

curl -X POST "https://lethallhost.com.br/api/whatsapp/v1/public/bot_send" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "to": "5561999999999", "type": "buttons", "instance_id": 1, "payload": { "title": "Atendimento", "description": "Como posso ajudar hoje?", "buttons": [ {"type": "reply", "displayText": "Falar com humano", "id": "falar_humano"}, {"type": "reply", "displayText": "Ver status do chamado", "id": "ver_status"} ] } }'

Exemplo — reação (emoji sobre uma mensagem)

message_id é o msg_id devolvido por um envio anterior (ou o id da mensagem recebida no seu webhook).

curl -X POST "https://lethallhost.com.br/api/whatsapp/v1/public/bot_send" \ -H "Authorization: Bearer SEU_TOKEN_AQUI" \ -H "Content-Type: application/json; charset=utf-8" \ -d '{ "to": "5561999999999", "type": "reaction", "instance_id": 1, "payload": { "message_id": "3EB0ABC123", "emoji": "👍" } }'

Manual HubSoft (passo a passo)

✓

HubSoft usa o endpoint DEV

Use https://lethallhost.com.br/api/whatsapp/v1/public/send e variáveis [[numero]] / [[mensagem]].

Passo a passo

Abra Integrações → SMS / Mensageiros.
Selecione Gateway de SMS: Outros.
Crie/edite uma integração e preencha os parâmetros abaixo.
Salve e faça um teste.

Parâmetros (modelo)

Parâmetro	Valor
url	https://lethallhost.com.br/api/whatsapp/v1/public/send
número	[[numero]]
mensagem	[[mensagem]]
agendamento	sim
token	SEU_TOKEN_REAL
key	Opcional (key public)
incluirAcentos	Opcional
limiteCaracteres	Opcional

Importante: HubSoft usa colchetes duplos: [[numero]] e [[mensagem]].

Modelo dinâmico pronto (lembrete de fatura)

Para o gatilho de cobrança/lembrete de vencimento, monte o texto do modelo no HubSoft usando as variáveis dele entre colchetes duplos — o HubSoft substitui pelos dados de cada cliente/fatura antes de chamar esta API. Exemplo pronto para copiar:

Oi, [[primeiro_nome_cliente]] 👋 Passando para lembrar que sua fatura está próxima do vencimento. 📅 Vencimento: [[data_vencimento]] 💰 Valor: R$ [[valor]] 👉 Para pagar agora, acesse: [[link_fatura]] Se o pagamento já foi realizado, por favor, desconsidere esta mensagem. 🙏

✨

Precisa de outro tipo de mensagem?

O Gerador de Modelos (menu do painel → Campanhas → Gerador de Modelos) tem mais de 10 modelos prontos — fatura vencida, boas-vindas, manutenção programada, visita técnica, pesquisa de satisfação e outros — para HubSoft, SGP ou qualquer outro sistema, já com a previsão de qual botão o link vai virar no WhatsApp.

O link vira botão sozinho: quando a mensagem final tiver exatamente 1 link (como o [[link_fatura]] do exemplo acima), o sistema troca automaticamente o link cru por um botão nativo "Pagar agora" no WhatsApp — não precisa configurar nada a mais. Se a mensagem tiver 2 ou mais links, ela é enviada normalmente como texto puro (sem risco de escolher o botão errado).

⚠️ Não escreva nenhuma nota sobre esse botão dentro do seu gatilho (nem algo tipo "[vira botão: Pagar agora]") — essa conversão é automática, o texto do gatilho deve ficar só com a mensagem que o cliente final deve ler. Qualquer anotação extra que você colar no corpo vira parte literal da mensagem enviada. Use o Gerador de Modelos pra ver o preview exato do botão de cada modelo antes de configurar o gatilho.

Ritmo de envio (proteção contra bloqueio do número): o sistema já espaça os envios sozinho — intervalo variável entre mensagens, simulação de "digitando..." e pausas periódicas — e mantém um teto diário de segurança por instância. Se um gatilho do HubSoft disparar muitos lembretes de uma vez (ex.: todos os vencimentos do dia), o que passar do teto é agendado automaticamente para o dia seguinte em vez de ser recusado ou arriscar o número. Nenhuma configuração extra é necessária; para ajustar os limites padrão, fale com o suporte.

HubSoft — Envio Oficial (HSM)

★

Para enviar pela API Oficial do WhatsApp (modelos HSM)

Use este modo quando precisar enviar mensagens com modelos aprovados (HSM) — inclusive fora da janela de 24h de conversa.

Este modo reaproveita um formato de integração que o HubSoft já traz pronto, evitando desenvolvimento adicional. O HubSoft envia para o endpoint abaixo e o sistema despacha pela sua instância oficial.

Endpoint (URL base)

https://lethallhost.com.br/api/whatsapp/v1/public

Passo a passo

No HubSoft, abra Configuração → Integração → SMS / Mensageiros.
Em Gateway de SMS, selecione SmartZAP V4 e ative Usa HSM.
Descubra o channel_id da sua instância oficial (ver abaixo).
Preencha os parâmetros da tabela e salve.
Faça um envio de teste.

Parâmetros (modelo)

Parâmetro	Valor
url	https://lethallhost.com.br/api/whatsapp/v1/public
usuário	e-mail do seu login no painel
senha	senha do seu login no painel
channel_id	id da instância oficial (ver abaixo)
número	[[numero]]
mensagem	[[mensagem]]
hsm_template_name	nome do modelo HSM aprovado
hsm_placeholders.1	1º valor do modelo — ex.: [[primeiro_nome_cliente]]
hsm_placeholders.2	2º valor do modelo (e assim por diante: .3, .4...)

Variáveis do modelo (HSM): cada campo {{1}}, {{2}}... do seu modelo aprovado recebe um parâmetro numerado hsm_placeholders.1, hsm_placeholders.2, na ordem. No valor desses campos de configuração do HubSoft, use as variáveis do HubSoft entre colchetes duplos — ex.: [[primeiro_nome_cliente]].

⚠️

Erro comum: colchetes duplos DENTRO do corpo do template — não faça isso

O corpo do template (criado em Admin/Painel → Gupshup → "Novo template", o texto que vai pra aprovação da Meta) precisa usar {{1}}, {{2}}... — nunca [[tag]]. Se o corpo tiver [[link_fatura]] escrito literalmente, a Meta aprova esse texto do jeito que está — estático, com colchetes de verdade — e o parâmetro que o HubSoft manda no disparo nunca substitui nada, porque não existe nenhum {{1}}/{{2}} ali pra receber ele. O cliente final recebe a mensagem com "[[link_fatura]]" escrito na tela, quebrado. Templates aprovados pela Meta não podem ser editados depois — se isso já aconteceu, apague o template e crie um novo, com {{1}}/{{2}} no lugar certo. Resumindo: [[tag]] só vale no valor que você digita nos campos de configuração do HubSoft (ex.: hsm_placeholders.1); {{1}}/{{2}} só vale dentro do corpo do template, na tela de criação deste sistema.

Como descobrir o channel_id

1) Gere um token com o seu login do painel:

curl -X POST "https://lethallhost.com.br/api/whatsapp/v1/public/auth/login" \ -H "Content-Type: application/json" \ -d '{"usuario":"SEU_EMAIL_DO_PAINEL","senha":"SUA_SENHA"}'

2) Liste seus canais usando o token recebido:

curl "https://lethallhost.com.br/api/whatsapp/v1/public/channels" \ -H "Authorization: Bearer SEU_TOKEN"

O campo _id da sua instância oficial é o valor do channel_id.

Importante: para envio HSM, o channel_id deve ser o da instância oficial e o modelo (HSM) precisa estar aprovado no seu painel. O HubSoft usa colchetes duplos: [[numero]] e [[mensagem]].

Manual SGP (HTTP Genérico)

✓

Formato oficial do SGP

Use o gateway HTTP Genérico com a URL oficial abaixo.

Passo a passo

Abra o SGP e vá em Administração → SMS Gateway.
Em Gateway, selecione HTTP Genérico.
No campo Config, cole o JSON abaixo.
Troque SEU_TOKEN_AQUI pelo token real.
Marque Ativo e salve.

Endpoint oficial

https://lethallhost.com.br/api/whatsapp/v1/public/send

Config oficial (JSON)

{ "url": "https://lethallhost.com.br/api/whatsapp/v1/public/send", "timeout": 60, "do_post": 1, "request_json": 1, "ignore_errors": 0, "headers": { "Authorization": "Bearer SEU_TOKEN_AQUI", "Content-Type": "application/json", "User-Agent": "Mozilla/5.0" }, "set_to": "to", "set_msg": "message" }

Área administrativa protegida.
Entre como admin para visualizar a configuração antiga de testes.

Entrar como admin

Checklist: Gateway em HTTP Genérico, URL oficial correta, envio JSON e header Authorization Bearer.

Suporte

Portal:

https://lethallhost.com.br/clientes/index.php/login

Ao abrir chamado, envie: data/hora do teste, status HTTP, retorno e print sem token.