Conceitos

Visão geral

Toda integração começa com um Assistente virtual cadastrado e em estado Operacional. Você dispara mensagens chamando um único endpoint, autenticando-se por um token na URL. O endpoint valida o destinatário, enfileira o envio e responde imediatamente; o WhatsApp recebe a mensagem em seguida.

Envio assíncrono

O HTTP retorna assim que a mensagem entra na fila — sem bloquear seu sistema.

Token na URL

Autenticação simples via parâmetro ?token=… (mantenha o token em variável de ambiente).

Mídia + IA

Suporte a imagem, áudio, arquivo, TTS e reescrita de texto via IA.

Primeiros passos

Início rápido

1
Garanta um Assistente virtual Operacional
No painel administrativo, abra Assistentes, copie o id do Assistente que enviará a mensagem e confirme que o status é Operacional.
2
Reúna o token e o destinatário
Copie o token de API (vide Autenticação) e formate o telefone com país + DDD, sem +. Ex.: 5511999998888.
3
Faça a requisição
Envie um POST para https://api.fala.app.br/send-whatsapp-message com o JSON contendo sessionId + algum conteúdo (message, image, audio ou file).
4
Confirme a entrega
Se a primeira mensagem não chegar, alterne a presença do 9 antes do número (a regra muda por operadora). A resposta da API confirma apenas o enfileiramento, não a entrega final.

Referência

Endpoint

Toda a API reside em uma única rota.

POSThttps://api.fala.app.br/send-whatsapp-message

Pré-requisitos do número

Não inclua o caractere + antes do código do país.
Não adicione o 9 extra antes do número, salvo se a operadora do destinatário exigir.
Para validar, envie uma mensagem e observe a entrega — caso falhe, alterne a presença do 9.

Referência

Autenticação

A autenticação é feita por meio de um parâmetro token anexado à URL. Toda requisição sem token (ou com token inválido) é rejeitada com 401 Unauthorized.

Token de API

u9P8Rp2xXxhJm6yGxqzY4gF4vqA7G1BmKzH9O1D3aQ3pR8wD8hY4cT3uJ2qM5yB8

Mantenha o token em segredo

Nunca embuta o token em código de cliente público (web, app mobile). Use-o apenas a partir do seu backend ou de variáveis de ambiente em automações.

Referência

Parâmetros do corpo

O corpo é um objeto JSON. Os campos são opcionais individualmente, mas existem duas regras combinadas de obrigatoriedade — destacadas com obrigatório* e obrigatório**.

Regras de obrigatoriedade combinada

* — pelo menos um entre sessionId e customerId.
** — pelo menos um entre message, audio, file e image.

sessionIdobrigatório*

string

ID do Assistente virtual que enviará a mensagem, obtido no ambiente administrativo na seção Assistentes. O Assistente precisa estar com status Operacional. Se omitido, customerId deve ser informado.

customerIdobrigatório*

string

ID do cliente. Quando enviado sem sessionId, o FalaApp seleciona automaticamente uma sessão Operacional vinculada ao cliente. Útil quando a integração desconhece qual Assistente deve responder.

messageobrigatório**

string≤ 1000 caracteres

Corpo da mensagem de texto. Toda formatação (negrito, itálico, quebras de linha com \n) é respeitada pelo WhatsApp. Use junto comtts: true para envio como áudio sintetizado.

phoneopcional

string

Número do destinatário com código do país e DDD, sem o caractere +. Ex.: 5511999998888. Ignorado quando group é informado.

groupopcional

string

ID (JID) do grupo do WhatsApp que receberá a mensagem (formato [email protected]). Quando informado, prevalece sobrephone.

imageobrigatório**

string (URL)

URL pública de uma imagem (PNG, JPG, WEBP). Deve ser acessível pela infraestrutura do FalaApp via HTTP/HTTPS.

fileobrigatório**

string (URL)

URL pública de um documento (PDF, DOCX, XLSX, …). O arquivo é baixado e encaminhado ao destinatário como anexo.

audioobrigatório**

string (URL)

URL pública de um arquivo de áudio (MP3, OGG/Opus). O conteúdo é enviado como mensagem de voz no WhatsApp.

nameopcional

string

Nome do contato/destinatário. Se informado, é usado para personalização da resposta e para criar/atualizar o contato no CRM do FalaApp.

additionalLearningopcional

string≤ 1000 caracteres

Contexto adicional injetado nos componentes de IA na hora de gerar a resposta. Útil para informações pontuais — ex.: “Cliente é Premium e prefere atendimento formal.”

generateNewTextopcional

booleandefault: false

Quando true, a IA reescreve o texto de message antes do envio, mantendo a intenção mas adaptando o tom. Quando false, a mensagem é enviada exatamente como recebida.

ttsopcional

booleandefault: false

Quando true, o conteúdo de message é convertido em áudio via Text-To-Speech e entregue como mensagem de voz — nesse caso o texto não é enviado.

ignoreOnOrderopcional

booleandefault: false

Quando true, o envio não é registrado em fluxos de pedido em aberto vinculados ao contato. Use para mensagens transacionais que não devem reabrir/avançar o funil.

additionalOverflowDataopcional

string (JSON)

JSON serializado com dados auxiliares anexados ao envio. É repassado ao consumidor da fila e fica disponível para integrações específicas (ex.: identificadores de campanha, origem do disparo). Precisa ser uma string JSON válida.

Implementação

Exemplos de requisição

A mesma requisição em diferentes linguagens. Substitua o token e os identificadores pelos seus.

Request

curl -X POST 'https://api.fala.app.br/send-whatsapp-message?token=u9P8Rp2xXxhJm6yGxqzY4gF4vqA7G1BmKzH9O1D3aQ3pR8wD8hY4cT3uJ2qM5yB8' \
  -H 'Content-Type: application/json' \
  -d '{
  "sessionId": "gqg5gq34g-g2422f-w1dw1dw1-12dw1dw-asdasdasd",
  "message": "Olá, *Tiago*!\nSeu pedido foi confirmado.",
  "phone": "5511999998888",
  "name": "Tiago Pedro",
  "additionalLearning": "Cliente Premium, atendimento formal.",
  "generateNewText": false,
  "tts": false,
  "ignoreOnOrder": false,
  "additionalOverflowData": "{\"campanha\":\"BlackFriday2026\",\"origem\":\"crm\"}"
}'

Referência

Respostas

A resposta é sempre um objeto JSON com a chave message (array de strings, mensagens humanas para log/UX). Quando o enfileiramento dá certo, vem também um campo data espelhando o conteúdo aceito.

200Sucesso

application/json

{
  "message": [
    "Sua mensagem foi adicionada à lista de envios e logo será encaminhada para o destinatário, se todos os parâmetros estiverem corretos."
  ],
  "data": {
    "type": "chat",
    "content": "Olá, *Tiago*!\nSeu pedido foi confirmado.",
    "isGroupMsg": false,
    "chatId": "FROM_API",
    "additionalLearning": "Cliente Premium, atendimento formal."
  }
}

4xxErro

application/json

{
  "message": ["Não foi possível adicionar a mensagem à lista de envios."],
  "error": "Error: Sessão não encontrada"
}

Referência

Erros comuns

A API retorna status HTTP padrão. Em casos de erro, o corpo normalmente traz a chave error com a descrição técnica.

200

Mensagem aceita e enfileirada para envio.

400

Bad Request

Faltam parâmetros obrigatórios (sessionId/customerId, ou nenhum conteúdo) — confira as regras combinadas.

401

Unauthorized

Token ausente ou inválido na query string.

403

Forbidden

Token sem permissão para o recurso ou Assistente indisponível para a operação.

500

Internal Server Error

Falha inesperada no FalaApp ao processar a requisição. Tente novamente; persistindo, contate o suporte.

Boas práticas

Limites e dicas

Sessão Operacional

Apenas Assistentes com status Operacional aceitam envio. Sessões em QR pendente ou desconectado retornam erro.

Texto + áudio TTS

Quando tts é true, o texto não é enviado — apenas o áudio sintetizado. Para enviar ambos, faça duas requisições.

Tamanho da mensagem

message e additionalLearning são limitados a 1000 caracteres cada. Conteúdos maiores devem ser quebrados em múltiplos envios.

Idempotência manual

A API não deduplica envios. Se o seu sistema pode reenviar o mesmo evento, controle a duplicidade do seu lado antes de chamar o endpoint.