Runbook - API de Mensagens do Sagazchat

Manual operacional para entender e usar a API de envio de mensagens do Sagazchat. Permite que sistemas externos enviem texto, midia, audio e figurinhas atraves do canal conectado.

8 min de leitura Atualizado em 1 de jun. de 2026

Manual operacional para entender e usar a API de envio de mensagens do Sagazchat. Permite que sistemas externos enviem texto, midia, audio e figurinhas atraves do canal conectado.

Status: documentacao da API capturada em 2026-05-11 da pagina /messages-api da conta exemplo. Nenhum request real disparado nesta sessao — apenas leitura da doc da plataforma.

1. Onde fica

  • Sidebar: Configurações > API
  • URL: https://app.sagazchat.com/messages-api
  • A pagina e documentacao da API integrada — exibe accordions com endpoints e exemplos.

Lista de endpoints

2. Pre-requisitos antes de usar a API

Da secao Instruções iniciais da propria UI:

  1. Obter o Token da conexao que vai enviar as mensagens:

    • Ir em Conexões.
    • Clicar no botao de edicao da conexao desejada.
    • Copiar o Token exibido.
    • Esse token e o Bearer que vai no header Authorization.

  2. Formato do numero (sem mascara, sem caracteres especiais):

    • <código do país><DDD><número>
    • Exemplo: 5511975542679 (Brasil 55 + DDD 11 + numero 975542679).

O token e por conexao, nao por usuario nem por empresa. Se houver multiplos canais, cada um tem seu token proprio.

3. Endpoints validados

Base URL: https://backend.sagazchat.com/api/messages

Todos exigem header Authorization: Bearer <Token>.

⚠️ No n8n (2026-06-01): NÃO autenticar o /api/messages/send com $env.SAGAZCHAT_WHATSAPP_TOKEN num header manual — dá Acesso não permitido. Usar a credencial salva httpBearerAuth id SEU_ID_DE_CREDENCIAL (“Bearer Auth account”) (authentication: genericCredentialType, genericAuthType: httpBearerAuth). É a mesma do agente WhatsApp SEU_ID_DE_AGENTE. Resposta de sucesso: {"mensagem":"Mensagem enviada"} — ⚠️ isso só confirma que o gateway aceitou, não que entregou. GOTCHA do 9º dígito: número com o 9 extra errado NÃO entrega (o Sagaz cria uma conversa nova “Aguardando” mas não chega no WhatsApp real). Mandar no formato real do número — ex: WhatsApp +55 (98) 8120-XXXX → enviar 55998120XXXX (12 dígitos, sem o 9 extra), NÃO 559998120XXXX (13). Conferir o número exato no contato do Sagaz.

Mensagem multilinha no n8n (gotcha 2026-06-01): NÃO usar \n dentro de string literal numa expressão n8n (={{ ... }}) — o \n vira newline cru e quebra a sintaxe JS (string não pode ter newline literal). Montar as linhas num array e juntar com String.fromCharCode(10): body: ["linha 1","",""+campo].join(String.fromCharCode(10)). Negrito no WhatsApp = *texto*. Padrão de alerta interno validado: título com emoji de status + campos com emoji-label (👤📧📦💰) + rodapé de status.

3.1 POST /send — Texto

POST https://backend.sagazchat.com/api/messages/send
Authorization: Bearer <Token>
Content-Type: application/json

{
  "number": "5511975542679",
  "body": "Sua mensagem"
}

3.2 POST /send — Mídia por upload

POST https://backend.sagazchat.com/api/messages/send
Authorization: Bearer <Token>
Content-Type: multipart/form-data

FormData:
  number: 5511975542679
  medias: <arquivo>

Quirk MAJOR: o mesmo endpoint /send serve para texto e midia. A diferenca esta no Content-Type: application/json (texto) vs multipart/form-data (midia upload).

3.3 POST /send/media — Mídia por link

POST https://backend.sagazchat.com/api/messages/send/media
Authorization: Bearer <Token>
Content-Type: application/json

{
  "number": "5511975542679",
  "mediaUrl": "https://siteImagem/minhafoto.png",
  "caption": "Legenda da foto"
}

Diferente do anterior: nao faz upload, o backend baixa da URL informada. Tem campo caption (legenda).

3.4 POST /send/audio-rec — Áudio gravado na hora

POST https://backend.sagazchat.com/api/messages/send/audio-rec
Authorization: Bearer <Token>
Content-Type: application/json

{
  "number": "5511975542679",
  "mediaUrl": "https://siteImagem/meuaudio.mp3"
}

Provavelmente vai como audio nativo do WhatsApp (PTT — push-to-talk). [a confirmar com o administrador]

3.5 POST /send/audio-forward — Áudio encaminhado

POST https://backend.sagazchat.com/api/messages/send/audio-forward
Authorization: Bearer <Token>
Content-Type: application/json

{
  "number": "5511975542679",
  "mediaUrl": "https://siteImagem/meuaudio.mp3"
}

Mesmo payload do /audio-rec mas vai como anexo encaminhado (nao PTT). [a confirmar com o administrador]

3.6 POST /send/sticker — Figurinha

POST https://backend.sagazchat.com/api/messages/send/sticker
Authorization: Bearer <Token>
Content-Type: application/json

{
  "number": "5511975542679",
  "mediaUrl": "https://siteImagem/meufigurinha.webp"
}

A doc original mostra .gif no exemplo — provavelmente typo, stickers do WhatsApp sao .webp.

4. Resumo dos endpoints

EndpointConteudoContent-TypeCampos
POST /sendTextoapplication/jsonnumber, body
POST /sendMidia uploadmultipart/form-datanumber, medias (arquivo)
POST /send/mediaMidia por URLapplication/jsonnumber, mediaUrl, caption
POST /send/audio-recAudio (PTT)application/jsonnumber, mediaUrl
POST /send/audio-forwardAudio (anexo)application/jsonnumber, mediaUrl
POST /send/stickerFigurinhaapplication/jsonnumber, mediaUrl

5. Acoes seguras e perigosas

AcaoImpactoRegra
Abrir /messages-apiLeituraSeguro.
Copiar tokenExpoe credencial sensivelTratar como senha — nao colar em logs/screenshots.
POST /send em ambiente de testeEnvia mensagem real para o numeroUsar numero proprio antes de subir para producao.
POST /send em volume sem rate-limitPode bloquear o numero no WhatsAppRespeitar limites do WhatsApp (300-1000 msgs/dia em conta nao-Business API).

6. Quirks consolidados

  • Mesmo endpoint /send faz texto OU midia upload — diferencia pelo Content-Type.
  • audio-rec vs audio-forward: dois endpoints separados, mesmo payload. Diferenca esta no comportamento de exibicao no WhatsApp (PTT vs anexo). [a validar]
  • Token e por conexao, nao por usuario/empresa. Trocar conexao = trocar token.
  • Formato do numero sem mascara: 5511975542679 (sem +, sem espacos, sem () ou -).
  • Sticker doc tem typo .gif em exemplo (deveria ser .webp).
  • Sem versionamento de API explicito (/v1, /v2 etc).
  • Doc nao mostra resposta dos endpoints — testes reais devem capturar o body de resposta para validar sucesso/erro.

7. Pendencias

  • Capturar response real de cada endpoint (status + body) com um envio de teste.
  • Validar diferenca pratica entre audio-rec e audio-forward.
  • Confirmar limites de rate (msgs/segundo, msgs/dia).
  • Validar comportamento de erro (numero invalido, token expirado, sem conexao).
  • Documentar webhook de recebimento — provavelmente existe mas nao esta nessa pagina.

8. Imagens

  • public/media/nova-ui/api-tela-inicial.png
  • public/media/nova-ui/api-tudo-expandido.png
  • public/media/nova-ui/api-instrucoes.png
  • public/media/nova-ui/api-exemplo-texto.png

9. Scripts validados

node scripts/sagaz-api-mapear.mjs       # estrutura da pagina
node scripts/sagaz-api-expandir.mjs     # expande accordions + captura conteúdo
node scripts/sagaz-api-screenshot.mjs   # screenshots com accordions abertos