FalaApp
v1•REST · JSON•Última atualização: maio/2026

Documentação da API

A API do FalaApp permite enviar mensagens via WhatsApp — texto, imagem, áudio ou documento — para qualquer número ou grupo, a partir de um Assistente virtual Operacional. As requisições são assíncronas: o endpoint enfileira o envio e retorna imediatamente uma confirmação.

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. 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. 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. 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. 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 API do FalaApp possui dois mecanismos de autenticação distintos, cada um usado em rotas diferentes. Não os confunda.

1. Token de API — Envio de mensagens

Usado no endpoint POST /send-whatsapp-message. Passado como parâmetro ?token=… na query string. Token fixo, gerado no painel administrativo.

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.

2. JWT Bearer — Rotas de consulta

Usado nas rotas GET /own/sessions e GET /own/sessions/:id. Passado no cabeçalho Authorization: Bearer <jwt>. Obtido via POST /sign-in — o mesmo e-mail e senha do painel administrativo.

Cabeçalho HTTP
Authorization: Bearer <seu-jwt>
Este token é diferente do token de API
O JWT de sessão e o token de API são credenciais distintas com escopos diferentes. O JWT autentica um usuário da plataforma; o token de API autentica uma integração de envio. Não os troque.

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.

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

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
OK
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.
Referência

Login (JWT)

Para chamar as rotas de consulta (listagem e detalhe de Assistentes), você precisa de um JWT. Obtenha-o autenticando com o mesmo e-mail e senha do painel administrativo do FalaApp.

POSThttps://api.fala.app.br/sign-in
Corpo da requisição
emailstringobrigatório
E-mail de acesso ao painel administrativo do FalaApp.
passwordstringobrigatório
Senha de acesso ao painel. Mínimo 6 caracteres.
curl -X POST 'https://api.fala.app.br/sign-in' \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","password":"suaSenha"}'
201Sucesso
application/json
{
  "message": "Login realizado com sucesso.",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": "7d",
    "roles": ["user"],
    "sessionsLimitsCount": [
      { "id": "a1b2c3d4-...", "limiteReached": false, "messagesSent": 142 }
    ]
  }
}
Onde usar o token
Copie o valor de data.token e envie-o no cabeçalho Authorization: Bearer <token> em todas as requisições às rotas de consulta. O token expira conforme o campo data.expiresIn — renove fazendo um novo login.
Credenciais inválidas retornam 409
Se o e-mail não existir ou a senha estiver errada, a API retorna 409 Conflict. Verifique as credenciais no painel antes de depurar a integração.

Use estas rotas para listar os Assistentes vinculados ao seu usuário e obter o sessionId necessário no endpoint de envio. Atenção: requerem autenticação JWT Bearer, não o token de API.

Autenticação diferente
Estas rotas usam o cabeçalho Authorization: Bearer <jwt>, obtido via login na plataforma. Veja a seção Autenticação para detalhes.

Listar Assistentes

GEThttps://api.fala.app.br/own/sessions

Retorna a lista paginada dos Assistentes do usuário autenticado. Apenas Assistentes não arquivados são retornados.

Query parameters
activebooleanopcional
Filtra por status ativo/inativo. Ex.: active=true
searchstringopcional
Filtra pelo nome do Assistente (substring, case-sensitive).
moduleNamestringopcional
Filtra por nome de módulo vinculado ao Assistente.
skipintegeropcional
Offset de paginação. Padrão: 0.
takeintegeropcional
Quantidade de registros por página. Padrão: 20. Máximo: 50.
curl -X GET 'https://api.fala.app.br/own/sessions?active=true&take=20' \
  -H 'Authorization: Bearer <seu-jwt>'
200Sucesso
application/json
{
  "message": ["Sessões encontradas com sucesso."],
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Assistente Suporte",
      "active": true,
      "archived": false,
      "type": "wppConnect",
      "currentPhoneNumber": "5511999998888",
      "timezone": -3,
      "isSubscriber": true,
      "trialExpiration": null,
      "createdAt": "2026-01-10T12:00:00.000Z",
      "updatedAt": "2026-05-14T08:30:00.000Z",
      "status": {
        "id": "s1",
        "name": "inChat",
        "label": "Operacional",
        "color": "#22c55e"
      },
      "customer": {
        "id": "c1",
        "name": "Empresa X",
        "partnerName": "Parceiro Y"
      },
      "modules": [
        { "id": "m1", "module": { "id": "mod1", "name": "whatsapp" } }
      ],
      "variables": [
        { "id": "v1", "key": "minha-variavel", "value": "valor" }
      ]
    }
  ],
  "total": 3
}

Detalhe de um Assistente

GEThttps://api.fala.app.br/own/sessions/:id

Retorna os dados completos de um único Assistente. Inclui contextos, variáveis com label, e calendários Google integrados.

Path parameter
idstring (UUID v4)obrigatório
ID do Assistente, obtido no campo id da rota de listagem acima.
200Sucesso
application/json
{
  "message": ["Sessão encontrada com sucesso."],
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Assistente Suporte",
    "active": true,
    "archived": false,
    "type": "wppConnect",
    "currentPhoneNumber": "5511999998888",
    "QrCode": null,
    "timezone": -3,
    "isSubscriber": true,
    "isLinkedWithCrm": false,
    "trialExpiration": null,
    "createdAt": "2026-01-10T12:00:00.000Z",
    "updatedAt": "2026-05-14T08:30:00.000Z",
    "status": {
      "id": "s1",
      "name": "inChat",
      "label": "Operacional",
      "color": "#22c55e"
    },
    "customer": {
      "id": "c1",
      "name": "Empresa X",
      "alertDestination": "[email protected]",
      "users": [{ "id": "u1", "name": "João", "email": "[email protected]" }]
    },
    "modules": [
      { "id": "m1", "module": { "id": "mod1", "name": "whatsapp" } }
    ],
    "contexts": [
      { "id": "ctx1", "content": "Você é um assistente...", "type": { "id": "t1", "name": "system", "label": "Contexto principal", "description": "...", "optional": false } }
    ],
    "variables": [
      { "id": "v1", "key": "minha-variavel", "label": "Minha Variável", "value": "valor" }
    ],
    "googleCalendars": []
  }
}
404 Not Found
Retornado quando o ID não existe ou o Assistente não pertence ao usuário autenticado.

Use estas rotas para criar e arquivar/desarquivar Assistentes em nome do cliente autenticado. Disponíveis apenas quando o cliente tem a flag allowSessionManagement habilitada (configurada pela equipe FalaApp). Autenticação JWT Bearer (mesmo token de login da plataforma).

Pré-requisito: permissão liberada
Antes de usar estas rotas, peça à equipe FalaApp para liberar a permissão de gerenciamento de Assistentes para o seu cliente. Sem ela, qualquer chamada aqui retorna 403 Forbidden.

Criar Assistente

POSThttps://api.fala.app.br/own/sessions

Cria um novo Assistente vinculado ao cliente do usuário autenticado. O tipo de conexão é fixado em baileys (WhatsApp via QR Code) e o módulo only-send-campaing é aplicado automaticamente — qualquer outro campo enviado no corpo é ignorado.

Body (application/json)
namestringobrigatório
Nome do Assistente. Até 255 caracteres.
Exemplo de corpo
application/json
{
  "name": "Atendimento Loja A"
}
curl -X POST 'https://api.fala.app.br/own/sessions' \
  -H 'Authorization: Bearer <seu-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Atendimento Loja A"}'
201Created
application/json
{
  "message": ["Sessão criada com sucesso."],
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Atendimento Loja A",
    "active": true,
    "type": "baileys",
    "status": {
      "id": "s0",
      "name": "loading",
      "label": "Carregando",
      "color": "#94a3b8"
    },
    "customer": {
      "id": "c1",
      "name": "Empresa X"
    },
    "modules": [
      { "id": "m1", "module": { "id": "mod1", "name": "only-send-campaing" } }
    ],
    "contexts": [
      { "id": "ctx1", "content": "Você é um assistente virtual", "type": { "id": "t1", "name": "personality", "label": "Personalidade", "description": "...", "optional": false } }
    ]
  }
}
403 Forbidden
Retornado quando o cliente do usuário autenticado não tem a flag allowSessionManagement habilitada.

Arquivar / Desarquivar

POSThttps://api.fala.app.br/own/sessions/:id/archive
POSThttps://api.fala.app.br/own/sessions/:id/unarchive

Arquivar marca o Assistente como inativo e encerra a sessão de WhatsApp associada. Desarquivar restaura o Assistente. Ambas as rotas exigem que o Assistente pertença ao cliente do usuário autenticado.

Path parameter
idstring (UUID v4)obrigatório
ID do Assistente que será arquivado ou desarquivado.
# Arquivar
curl -X POST 'https://api.fala.app.br/own/sessions/<assistente-id>/archive' \
  -H 'Authorization: Bearer <seu-jwt>'

# Desarquivar
curl -X POST 'https://api.fala.app.br/own/sessions/<assistente-id>/unarchive' \
  -H 'Authorization: Bearer <seu-jwt>'
200Sucesso
application/json
{
  "message": ["Sessão arquivada com sucesso."],
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "archived": true
  }
}
404 Not Found
Retornado quando o Assistente não existe ou não pertence ao cliente do usuário autenticado.

Sincronizar / Reconectar

POSThttps://api.fala.app.br/sessions/:id/fix

Força a sincronização do Assistente com o WhatsApp: encerra a instância atual e a recria em seguida, gerando um novo QR Code / Código de Pareamento. É a mesma ação do botão Sincronizar na lista de Assistentes. Use quando a conexão travar ou o status não atualizar.

Path parameter
idstring (UUID v4)obrigatório
ID do Assistente que será sincronizado/reconectado.
curl -X POST 'https://api.fala.app.br/sessions/<assistente-id>/fix' \
  -H 'Authorization: Bearer <seu-jwt>'
200Sucesso
application/json
{
  "message": "Processo de restart do browser da sessão iniciado com sucesso",
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Assistente Suporte",
    "archived": false
  }
}
Pode desconectar o WhatsApp
O restart derruba a conexão atual. Após a sincronização, reconecte escaneando o novo QR Code ou usando o Código de Pareamento. O QR/código atualizado chega via webhook qrcode.updated ou consultando GET /own/sessions/:id.
403 Forbidden
Requer a permissão de gerenciamento de Assistentes liberada para o seu cliente pela equipe FalaApp. Sem ela, a chamada retorna 403 Forbidden.

Configure uma URL por cliente para receber notificações automáticas de eventos do FalaApp — atualização de QR code e mudança de status de qualquer Assistente vinculado ao cliente. O FalaApp faz um POST para a sua URL com JSON toda vez que um evento ocorre.

Autenticação: JWT Bearer
Todas as rotas de gerenciamento de webhook usam Authorization: Bearer <jwt>. Veja a seção Login (JWT).

Gerenciar URL

GET/own/webhook

Retorna a URL de webhook configurada para o cliente.

PUT/own/webhook

Define ou atualiza a URL de webhook. Passe webhookUrl no corpo (string HTTP/HTTPS, máx 500 chars). Envie null para remover.

POST/own/webhook/test

Dispara um evento webhook.test imediatamente para validar a URL configurada.

GET/own/webhook/deliveries

Retorna as últimas 20 tentativas de entrega com status, código HTTP e trecho da resposta.

Exemplo para configurar a URL:

curl -X PUT 'https://api.fala.app.br/own/webhook' \
  -H 'Authorization: Bearer <seu-jwt>' \
  -H 'Content-Type: application/json' \
  -d '{"webhookUrl":"https://meusite.com/webhook"}'

Cabeçalhos enviados pelo FalaApp

Toda requisição de webhook enviada pelo FalaApp inclui os seguintes cabeçalhos:

Content-Typeapplication/json
User-AgentFalaApp-Webhook/1.0
X-FalaApp-Event<tipo-do-evento>
Retry automático
O FalaApp tenta a entrega até 5 vezes com backoff exponencial iniciando em 5 segundos. Sua URL deve retornar um status 2xx para confirmar o recebimento — qualquer outro código ou timeout (10 s) conta como falha e aciona a próxima tentativa.

Eventos

Todos os eventos seguem o mesmo envelope: event, occurredAt, customerId e data (payload específico do evento).

qrcode.updated

Disparado quando o QR code de um Assistente é atualizado. Use para exibir o QR code ao usuário em tempo real.

Payload enviado à sua URL
{
  "event": "qrcode.updated",
  "occurredAt": "2026-05-14T12:34:56.789Z",
  "customerId": "c1b2a3d4-...",
  "data": {
    "session": {
      "id": "a1b2c3d4-...",
      "name": "Assistente Suporte",
      "qrCodeUrl": "https://cdn.fala.app.br/qrcodes/abc123.png"
    }
  }
}
session.status_changed

Disparado quando o status de um Assistente muda (ex.: de QR pendente para Operacional, ou de Operacional para desconectado).

Payload enviado à sua URL
{
  "event": "session.status_changed",
  "occurredAt": "2026-05-14T12:34:56.789Z",
  "customerId": "c1b2a3d4-...",
  "data": {
    "session": {
      "id": "a1b2c3d4-...",
      "name": "Assistente Suporte"
    },
    "status": {
      "name": "inChat",
      "label": "Operacional"
    }
  }
}
webhook.test

Disparado manualmente via POST /own/webhook/test. Use para validar que sua URL está recebendo corretamente.

Payload enviado à sua URL
{
  "event": "webhook.test",
  "occurredAt": "2026-05-14T12:34:56.789Z",
  "customerId": "c1b2a3d4-...",
  "data": {
    "message": "Teste de webhook do FalaApp. Se você recebeu esta mensagem, sua URL está configurada corretamente."
  }
}

Cada Assistente pode ter webhooks individuais configurados diretamente no painel administrativo (seção Assistentes → Editar). Esses webhooks são acionados por eventos de conversa e permitem integrar o FalaApp com qualquer plataforma externa — CRM, ERP, automações, etc.

Módulo necessário
O módulo Encaminhar informações de contato precisa estar ativo no Assistente para que os webhooks de assistente funcionem. Ative-o no painel em Assistentes → Módulos.

Configuração

Cada webhook de assistente é configurado com:

event

Evento que aciona o webhook: onNewMessage ou onBlockAssistant.

url

URL da sua aplicação. Deve ser acessível publicamente (HTTP ou HTTPS).

method

Método HTTP: POST, GET, PUT ou DELETE. Padrão: POST.

headers

Até 3 cabeçalhos customizados (chave + valor). Content-Type: application/json é sempre incluído.

Eventos

onNewMessage

Disparado ao receber uma nova mensagem de um contato. Enviado no máximo uma vez a cada 10 minutos por contato para evitar disparos duplicados.

Payload enviado à sua URL
{
  "sessionId": "a1b2c3d4-...",
  "name": "João Silva",
  "phone": "5511999998888",
  "whatsapp": "5511999998888"
}
onBlockAssistant

Disparado quando um contato bloqueia o Assistente via chat. Inclui o histórico completo da conversa — ideal para capturar leads que desistiram do atendimento automático.

Payload enviado à sua URL
{
  "event": "onBlockAssistant",
  "sessionId": "a1b2c3d4-...",
  "sessionName": "Assistente Suporte",
  "contactId": "ct1b2c3-...",
  "contactName": "João Silva",
  "contactPhone": "5511999998888",
  "conversationId": "conv123-...",
  "blockedAt": "2026-05-14T13:00:00.000Z",
  "messages": [
    {
      "id": "msg1",
      "content": "Quero cancelar meu pedido",
      "origin": "contact",
      "createdAt": "2026-05-14T12:55:00.000Z",
      "isFile": false,
      "isImage": false,
      "isAudio": false,
      "isLocation": false
    }
  ],
  "conversationMetadata": {
    "totalMessages": 5,
    "firstMessageAt": "2026-05-14T12:50:00.000Z",
    "lastMessageAt": "2026-05-14T12:59:00.000Z"
  }
}
Múltiplos webhooks por evento
Um Assistente pode ter vários webhooks configurados para o mesmo evento — cada um disparado independentemente. Use isso para notificar diferentes sistemas ao mesmo tempo.

O FalaApp expõe um servidor MCP (Model Context Protocol) somente leitura que permite a um modelo de IA — Claude, ChatGPT ou qualquer cliente compatível com MCP — consultar contatos e mensagens do WhatsApp da sua conta em linguagem natural. Útil para gerar resumos de negociações, criar oportunidades em CRMs externos ou pesquisar conversas sem sair do seu assistente de IA.

Somente leitura
O servidor não envia mensagens nem altera dados — apenas consulta o histórico.
Stateless por requisição
Transporte Streamable HTTP sem sessão persistente. Cada chamada é independente.
Escopo por customerId
O customerId na URL limita as consultas aos dados daquele cliente — nada vaza entre contas.

Endpoint

POST
https://api.fala.app.br/mcp/<customerId>?token=<server-token>

GET e DELETE retornam 405 — este servidor é stateless e aceita apenas POST.

Autenticação

Mesmo padrão do endpoint de envio: passe o token global na query string ?token=<server-token>. O customerId da URL escopa todas as ferramentas para os dados daquele cliente.

Trate o token como segredo
Qualquer pessoa com o token e um customerId válido pode ler o histórico daquele cliente. Não exponha o token em código cliente — use sempre num cliente MCP local ou em backend controlado.

Configuração no Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json no macOS). O utilitário mcp-remote faz a ponte do stdio do Claude para o servidor HTTP do FalaApp.

claude_desktop_config.json
{
  "mcpServers": {
    "falaapp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.fala.app.br/mcp/<seu-customer-id>?token=<server-token>"
      ]
    }
  }
}
Outros clientes MCP
Para o Claude na web, ChatGPT, Cursor ou qualquer cliente que aceite servidores MCP via HTTP, basta cadastrar a URL completa com o token na query string. Não há cabeçalhos especiais — autenticação é só pelo token.

Ferramentas (tools) disponíveis

O servidor anuncia duas ferramentas. Use sempre search_contacts primeiro para obter um conversationId válido — depois passe esse id para get_conversation_messages.

search_contacts

Busca contatos por telefone ou nome (match parcial, case-insensitive). Retorna a lista paginada de contatos, cada um com até 5 conversas mais recentes (não arquivadas).

querystringobrigatório

Telefone ou nome do contato (match parcial).

limitintegeropcional

Itens por página. Default 20, máx 50.

offsetintegeropcional

Deslocamento para paginação. Default 0.

Resposta (conteúdo de text)
{
  "contacts": [
    {
      "contactId": "ct-1b2c3d-...",
      "name": "João Silva",
      "phone": "5511999998888",
      "senderId": "[email protected]",
      "conversations": [
        {
          "conversationId": "conv-abc123-...",
          "sessionId": "a1b2c3d4-...",
          "assistant": "Assistente Vendas",
          "totalMessages": 42,
          "updatedAt": "2026-05-14T18:30:00.000Z"
        }
      ]
    }
  ],
  "total": 1,
  "offset": 0,
  "limit": 20,
  "hasMore": false
}
get_conversation_messages

Lê mensagens de uma conversa em ordem cronológica (mais antigas primeiro dentro da página). Paginação por cursor — passe o nextBefore retornado para ver mensagens mais antigas.

conversationIdstringobrigatório

ID da conversa, obtido em search_contacts. Validado contra o customerId — IDs de outros clientes retornam erro.

limitintegeropcional

Mensagens por página. Default 50, máx 100.

beforestring (ISO date)opcional

Cursor de paginação. Passe o nextBefore retornado para buscar mensagens anteriores.

Campos de cada mensagem:

origin

user (contato), assistant (IA), operator (atendente humano) ou api (envio via integração).

type

text, image, audio, file ou location. Áudios entram já transcritos no campo content.

content

Conteúdo da mensagem em texto (transcrição no caso de áudio).

isDeleted

true quando o contato apagou a mensagem do WhatsApp.

reactions

Reações registradas na mensagem (ou null).

operatorName

Nome do atendente humano, presente apenas quando origin = operator.

createdAt

Timestamp ISO 8601.

Resposta (conteúdo de text)
{
  "conversation": {
    "conversationId": "conv-abc123-...",
    "contact": {
      "contactId": "ct-1b2c3d-...",
      "name": "João Silva",
      "phone": "5511999998888"
    },
    "sessionId": "a1b2c3d4-...",
    "assistant": "Assistente Vendas"
  },
  "messages": [
    {
      "id": "msg-001",
      "origin": "user",
      "type": "text",
      "content": "Oi, queria saber sobre o imóvel da rua X",
      "isDeleted": false,
      "reactions": null,
      "createdAt": "2026-05-14T12:55:00.000Z"
    },
    {
      "id": "msg-002",
      "origin": "assistant",
      "type": "text",
      "content": "Olá! Posso te passar mais detalhes...",
      "isDeleted": false,
      "reactions": null,
      "createdAt": "2026-05-14T12:55:08.000Z"
    },
    {
      "id": "msg-003",
      "origin": "user",
      "type": "audio",
      "content": "[transcrição do áudio do contato]",
      "isDeleted": false,
      "reactions": null,
      "createdAt": "2026-05-14T12:56:30.000Z"
    }
  ],
  "hasMore": false,
  "nextBefore": null
}

Invocação direta (sem cliente MCP)

Em casos em que você não usa um cliente MCP pronto (Claude/ChatGPT), é possível chamar as ferramentas via JSON-RPC 2.0 — útil para scripts, automações e testes.

# Invocação direta via JSON-RPC (search_contacts)
curl -X POST 'https://api.fala.app.br/mcp/<seu-customer-id>?token=<server-token>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_contacts",
      "arguments": { "query": "joão", "limit": 10 }
    }
  }'
Comportamento e limites
Ferramentas retornam isError: true com mensagem explicativa em caso de falha. Conversas que não pertencem ao customerId da rota retornam erro claro em vez de vazar dados. Como o transporte é stateless, não há suporte a notificações server-push (SSE).

Suba documentos (PDF, DOCX, MD, TXT, CSV, HTML ou JSON) diretamente para o aprendizado de um Assistente. O FalaApp envia o arquivo para a OpenAI, cria um vector store dedicado àquele Assistente e o modelo passa a consultar esse conteúdo automaticamente nas conversas — via a ferramenta nativa file_search da Responses API. Ideal para alimentar o assistente com catálogos, políticas, FAQs e bases de conhecimento que mudam com frequência.

Autenticação: JWT Bearer
As rotas de aprendizado por arquivo usam Authorization: Bearer <jwt>. Obtenha o JWT na rota /sign-in — o token é vinculado ao usuário do FalaApp e tem TTL (renove via login quando expirar).

Rotas

POST/sessions/:id/learning-files

Envia um arquivo (multipart/form-data, campo file, até 25MB) para o aprendizado do Assistente. Cria o vector store na primeira chamada. Retorna o registro do arquivo com status processing — a indexação é assíncrona.

GET/sessions/:id/learning-files

Lista os arquivos do Assistente. Sincroniza automaticamente o status dos arquivos em processing com a OpenAI antes de responder.

DELETE/sessions/:id/learning-files/:fileId

Remove o arquivo do vector store e o apaga da OpenAI. Use o campo id retornado nas rotas POST/GET (não confunda com openaiFileId).

Status do arquivo

processing

Upload concluído, OpenAI ainda está indexando. Pode levar de segundos a alguns minutos dependendo do tamanho.

ready

Indexado e disponível para o modelo consultar nas próximas conversas.

failed

Indexação falhou (ex.: arquivo corrompido, formato não suportado). O campo errorMessage traz o detalhe retornado pela OpenAI.

Enviar arquivo

curl -X POST 'https://api.fala.app.br/sessions/<sessionId>/learning-files' \
  -H 'Authorization: Bearer <seu-jwt>' \
  -F 'file=@./catalogo.pdf'
201Criado
application/json
{
  "data": {
    "id": "f0e9c3ab-1d2e-4b3f-9c5d-6a7b8c9d0e1f",
    "openaiFileId": "file_abc123XyZ",
    "name": "catalogo.pdf",
    "size": 487213,
    "mimeType": "application/pdf",
    "status": "processing",
    "createdAt": "2026-05-26T18:42:11.000Z"
  }
}

Listar arquivos

curl -X GET 'https://api.fala.app.br/sessions/<sessionId>/learning-files' \
  -H 'Authorization: Bearer <seu-jwt>'
200Sucesso
application/json
{
  "data": [
    {
      "id": "f0e9c3ab-1d2e-4b3f-9c5d-6a7b8c9d0e1f",
      "openaiFileId": "file_abc123XyZ",
      "name": "catalogo.pdf",
      "size": 487213,
      "mimeType": "application/pdf",
      "status": "ready",
      "createdAt": "2026-05-26T18:42:11.000Z"
    },
    {
      "id": "11d2e394-4b3f-9c5d-6a7b-8c9d0e1f0e9c",
      "openaiFileId": "file_xyz789AbC",
      "name": "politica-de-trocas.docx",
      "size": 23145,
      "mimeType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "status": "processing",
      "createdAt": "2026-05-26T18:45:02.000Z"
    }
  ]
}

Remover arquivo

curl -X DELETE 'https://api.fala.app.br/sessions/<sessionId>/learning-files/<fileId>' \
  -H 'Authorization: Bearer <seu-jwt>'
Sincronização programada
Para manter o aprendizado em dia, agende o seu sistema para listar os arquivos, apagar versões obsoletas e enviar as atualizadas — o assistente passa a usar a base nova nas próximas conversas, sem reiniciar nada.
Storage cobrado por dia
Arquivos ficam armazenados no vector store da OpenAI enquanto o Assistente existir. Storage é cobrado por GB/dia — apague arquivos que não são mais úteis via DELETE para evitar custos silenciosos.
Limite por arquivo
25 MB por upload. Documentos maiores devem ser quebrados em partes menores antes de enviar. Cada Assistente pode ter quantos arquivos couberem no plano.
Cleanup automático
Quando o Assistente é excluído, o FalaApp apaga o vector store e todos os arquivos associados na OpenAI — você não precisa fazer cleanup manual.
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.