API de Mensagens

A API de Mensagens do Sagazchat permite que sistemas externos enviem mensagens pelo canal conectado — texto, midia, audio e figurinhas — atraves de chamadas HTTP. Ideal para integrar o atendimento com CRMs, e-commerces, automacoes externas e ERPs.

Onde encontrar

Acesse Configurações > API na barra lateral. A pagina mostra a documentacao oficial com 7 secoes que podem ser expandidas individualmente.

Antes de comecar

1. Pegar o Token da conexão

A API autentica por token de conexao — cada canal conectado (WhatsApp QR, WhatsApp Oficial, Instagram, etc) tem o seu.

1. Va em Conexões.
2. Clique no botao de edicao da conexao que vai enviar.
3. Copie o Token.

Esse token entra no header de toda requisicao:

Authorization: Bearer <SEU_TOKEN>

Trate o token como senha. Quem tem o token consegue enviar mensagens em seu nome. Nao cole em codigo aberto, repositorios publicos, capturas de tela ou tickets de suporte.

2. Formato do numero

O numero do destinatario deve estar sem mascara:

<código do país><DDD><número>

Exemplo:

• Brasil (55), DDD 11, numero 975542679 → 5511975542679

Nada de +, parenteses, espacos ou tracos.

Endpoints

A URL base e:

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

Todos os endpoints sao POST e exigem Authorization: Bearer <Token>.

Texto

POST /send
Content-Type: application/json

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

Mídia por upload

Mesma rota /send, mas com multipart/form-data:

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

FormData:
  number: 5511975542679
  medias: <arquivo>

O mesmo endpoint /send aceita texto OU midia — a diferenca esta no Content-Type.

Mídia por link (com legenda)

POST /send/media
Content-Type: application/json

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

O backend baixa a midia da mediaUrl informada (sem upload).

Áudio gravado na hora

POST /send/audio-rec
Content-Type: application/json

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

Vai como audio nativo do WhatsApp (PTT — push-to-talk).

Áudio encaminhado

POST /send/audio-forward
Content-Type: application/json

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

Mesmo payload do anterior, mas vai como anexo encaminhado (nao PTT).

Figurinha

POST /send/sticker
Content-Type: application/json

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

Figurinhas do WhatsApp sao normalmente .webp.

Resumo dos endpoints

Endpoint	Tipo de mensagem	Content-Type
POST /send (com body)	Texto	application/json
POST /send (com medias)	Midia upload	multipart/form-data
POST /send/media	Midia por URL	application/json
POST /send/audio-rec	Audio PTT	application/json
POST /send/audio-forward	Audio anexo	application/json
POST /send/sticker	Figurinha	application/json

Exemplo completo (cURL)

curl -X POST https://backend.sagazchat.com/api/messages/send \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "5511975542679",
    "body": "Ola! Mensagem via API."
  }'

Cuidados de uso

• Token e secreto: trate como senha. Rotacione se vazar.
• Respeitar limites do WhatsApp: em contas comuns (nao-Business API), o WhatsApp pode bloquear envios em volume alto. Faca testes com numeros proprios antes de subir em massa.
• Testar antes de producao: envie para seu proprio numero para validar formato e comportamento.
• Numero deve existir no WhatsApp: se o numero nao tem WhatsApp, a mensagem nao chega — depende do retorno do endpoint para saber.
• Variaveis nao sao substituidas: a API envia texto literal — escrever Ola {nome} envia exatamente isso. Para mensagens personalizadas, monte o texto no seu sistema antes de chamar a API.

Para que usar

• Integrar com CRM: ao mover um lead de estagio no Pipedrive/HubSpot/RD Station, sua automacao chama a API e dispara uma mensagem pelo WhatsApp.
• Notificar pedidos: e-commerce fecha pedido, sistema dispara mensagem com numero do pedido e link de acompanhamento.
• Alertas internos: erro em producao, monitor envia mensagem para grupo de devops.
• Confirmacao de agendamento: sistema de agenda envia lembrete 24h antes pelo WhatsApp.
• Recuperacao de carrinho: ao detectar carrinho abandonado, chamar API com mensagem personalizada.

Diferenca para o Bate Papo / Fluxos

Cenario	Bate Papo	Fluxo de conversa	API
Quem aciona	Atendente humano	Cliente (entrada na jornada) ou agendamento	Sistema externo
Conteudo	Digitado na hora ou via atalho	Sequencia automatica com logica	Mensagem programada pelo seu sistema
Variaveis personalizadas	Aplicaveis se for fluxo	Sim (blocos com variaveis)	Voce monta o texto antes
Quando faz sentido	Atendimento ao vivo	Jornadas pre-definidas	Eventos externos que precisam virar mensagem

Pendencias da documentacao

• O retorno (status + body) dos endpoints nao esta documentado na pagina — capturar via testes reais.
• A diferenca pratica entre audio-rec e audio-forward precisa validacao.
• Webhook de recebimento (mensagens que chegam dos clientes) provavelmente existe mas nao esta nessa pagina — consultar Suporte.