API Reference

Visão geral

Um único endpoint. Dois provedores. A mesma interface.

A API suporta conexões dos tipos WAPI (WhatsApp Web não-oficial) e Meta Cloud API (API oficial do WhatsApp Business). O provedor é detectado automaticamente pela API Key — você não precisa especificar qual está usando.

ℹ Todas as requisições devem ser feitas via HTTPS. Requisições HTTP retornam 403 Forbidden.

Base URL

https://b24.falefacilchat.com.br/api.php

Formatos de requisição aceitos

A API aceita tanto application/json quanto application/x-www-form-urlencoded. JSON é recomendado por ser mais legível e evitar problemas de encoding em caracteres especiais.

Estrutura da resposta

{
  "success": true,         // bool — resultado da operação
  "ts":      1718000000,    // int  — timestamp Unix
  "data":    { ... }         // object — payload (omitido em erros)
}
// Em erros:
{
  "success": false,
  "error":   "Mensagem de erro descritiva",
  "ts":      1718000000
}

Autenticação

API Key por conexão, enviada em cada requisição.

Cada API Key está vinculada a uma conexão específica. A chave identifica o cliente, o provedor e o número de WhatsApp a ser usado.

Formas de envio

Método	Como enviar	Recomendado
X-Api-Key	Header HTTP	✓ sim
Authorization	Header: `Bearer {api_key}`	alternativa
api_key	Query string (aparece em logs de servidor)	✗ evitar

Exemplo

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{"action":"status"}'

$ch = curl_init('https://b24.falefacilchat.com.br/api.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => 1,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Api-Key: sua-chave-aqui',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode(['action' => 'status']),
]);
$res = json_decode(curl_exec($ch), true);

import requests

resp = requests.post(
    'https://b24.falefacilchat.com.br/api.php',
    headers={'X-Api-Key': 'sua-chave-aqui'},
    json={'action': 'status'}
)
data = resp.json()

const resp = await fetch('https://b24.falefacilchat.com.br/api.php', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sua-chave-aqui',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ action: 'status' })
});
const data = await resp.json();

Rate limit

120 requisições por minuto, por chave.

120

requisições / minuto

60s

janela deslizante

429

HTTP ao exceder

Headers retornados em cada resposta:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1718000060    # timestamp Unix

# Ao exceder:
HTTP/1.1 429 Too Many Requests
Retry-After: 23                  # segundos até liberar

⚠Implemente backoff exponencial ao receber 429. Respeite o header Retry-After antes de tentar novamente.

Erros

Códigos HTTP e mensagens padronizadas.

400 Parâmetro ausente ou inválido.

401 API key não informada ou inválida.

402 Assinatura da conexão vencida. Regularize o pagamento.

403 API key inativa, IP não autorizado ou requisição sem HTTPS.

405 Método HTTP incorreto (use POST para envios).

413 Arquivo de mídia maior que 20 MB.

422 URL de mídia inacessível ou download retornou erro.

429 Rate limit excedido. Aguarde o intervalo em Retry-After.

500 Erro interno ao processar a requisição.

502 Falha na API de destino (WAPI ou Meta Graph API).

503 Conexão WhatsApp inativa. Reconecte antes de enviar.

Status da conexão

Verifica se o WhatsApp está conectado.

GET api.php ?action=status

WAPIMeta

▼

Para WAPI, consulta o servidor em tempo real. Para Meta, verifica o status registrado na conexão.

Exemplo

curl "https://b24.falefacilchat.com.br/api.php?action=status" \
  -H "X-Api-Key: sua-chave-aqui"

$ch = curl_init('https://b24.falefacilchat.com.br/api.php?action=status');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-Api-Key: sua-chave-aqui'],
]);
$data = json_decode(curl_exec($ch), true);

import requests

resp = requests.get(
    'https://b24.falefacilchat.com.br/api.php',
    params={'action': 'status'},
    headers={'X-Api-Key': 'sua-chave-aqui'}
)
print(resp.json()['data']['status'])

const resp = await fetch(
    'https://b24.falefacilchat.com.br/api.php?action=status',
    { headers: { 'X-Api-Key': 'sua-chave-aqui' } }
);
const { data } = await resp.json();

Resposta

200 Sucesso

{
  "success": true,
  "ts": 1718000000,
  "data": {
    "connection_id": 12,
    "provider": "wapi",
    "phone": "5511999990000",
    "internal_id": "Comercial 01",
    "status": "connected"
  }
}

Listar conexões

Retorna todas as conexões do cliente.

GET api.php ?action=list_connections

WAPIMeta

▼

Lista todas as conexões do cliente vinculado à API Key, independente de qual número a chave pertence.

Exemplo

curl "https://b24.falefacilchat.com.br/api.php?action=list_connections" \
  -H "X-Api-Key: sua-chave-aqui"

$ch = curl_init('https://b24.falefacilchat.com.br/api.php?action=list_connections');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-Api-Key: sua-chave-aqui'],
]);
$data = json_decode(curl_exec($ch), true);

import requests

resp = requests.get(
    'https://b24.falefacilchat.com.br/api.php',
    params={'action': 'list_connections'},
    headers={'X-Api-Key': 'sua-chave-aqui'}
)

const resp = await fetch(
    'https://b24.falefacilchat.com.br/api.php?action=list_connections',
    { headers: { 'X-Api-Key': 'sua-chave-aqui' } }
);
const { data } = await resp.json();

Resposta

200 Sucesso

{
  "success": true,
  "ts": 1718000000,
  "data": {
    "total": 2,
    "connections": [
      { "id": 12, "phone": "5511999990000", "internal_id": "Comercial 01",
        "provider": "wapi", "status": "active", "paid_until": "2025-12-31" },
      { "id": 15, "phone": "5511888880000", "internal_id": "Suporte",
        "provider": "meta", "status": "active", "paid_until": "2025-06-30" }
    ]
  }
}

Enviar texto

Envia uma mensagem de texto para um número.

POST api.php action=send_text

WAPIMeta

▼

Parâmetros

Parâmetro	Tipo		Descrição
action	string	obrig.	"send_text"
to	string	obrig.	Número destino com DDI, apenas dígitos. Ex: `5511999990000`. Para grupos (WAPI), use o JID: `120363041234567890@g.us` — ver seção Grupos.
message	string	obrig.	Texto a enviar. Máximo 4096 caracteres. Formatação WhatsApp suportada em WAPI (`negrito`, `_itálico_`).
sendtobitrix24	bool	opcl.	Se `true`, registra a mensagem enviada na conversa do Bitrix24. Apenas WAPI.

Exemplo

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_text",
    "to": "5511999990000",
    "message": "Olá! Seu pedido *#1234* foi confirmado. ✓",
    "sendtobitrix24": true
  }'

$ch = curl_init('https://b24.falefacilchat.com.br/api.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => 1,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Api-Key: sua-chave-aqui',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'action'          => 'send_text',
        'to'              => '5511999990000',
        'message'         => "Olá! Seu pedido *#1234* foi confirmado. ✓",
        'sendtobitrix24' => true,
    ]),
]);
$data = json_decode(curl_exec($ch), true);

import requests

resp = requests.post(
    'https://b24.falefacilchat.com.br/api.php',
    headers={'X-Api-Key': 'sua-chave-aqui'},
    json={
        'action':          'send_text',
        'to':              '5511999990000',
        'message':         'Olá! Seu pedido *#1234* foi confirmado. ✓',
        'sendtobitrix24': True
    }
)

const resp = await fetch('https://b24.falefacilchat.com.br/api.php', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sua-chave-aqui',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        action:          'send_text',
        to:              '5511999990000',
        message:         'Olá! Seu pedido *#1234* foi confirmado. ✓',
        sendtobitrix24: true
    })
});

Respostas

200 Mensagem enviada

{ "success": true, "ts": 1718000000, "data": { "message_id": "3EB0A12345ABCDEF", "to": "5511999990000" } }

503 Conexão inativa

{"success":false,"error":"Connection is not active. Connect WhatsApp first.","ts":1718000000}

Enviar mídia

Envia imagem, vídeo, áudio ou documento via URL.

POST api.php action=send_media

WAPIMeta

▼

Parâmetros

Parâmetro	Tipo		Descrição
action	string	obrig.	"send_media"
to	string	obrig.	Número destino com DDI (apenas dígitos) ou JID de grupo WAPI (`...@g.us`) — ver Grupos
url	string	obrig.	URL pública do arquivo. Deve retornar HTTP 200. Limite: 20 MB.
type	string	obrig.	`image` \| `video` \| `audio` \| `document`
caption	string	opcl.	Legenda. Suportada em image, video e document. Ignorada em audio.
sendtobitrix24	bool	opcl.	Se `true`, registra no Bitrix24 como mensagem enviada. Apenas WAPI.

Exemplo — imagem

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_media",
    "to": "5511999990000",
    "type": "image",
    "url": "https://exemplo.com/produto.jpg",
    "caption": "Confira nosso novo produto!"
  }'

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action'  => 'send_media',
    'to'      => '5511999990000',
    'type'    => 'image',
    'url'     => 'https://exemplo.com/produto.jpg',
    'caption' => 'Confira nosso novo produto!',
]));

requests.post(url, headers=headers, json={
    'action':  'send_media',
    'to':      '5511999990000',
    'type':    'image',
    'url':     'https://exemplo.com/produto.jpg',
    'caption': 'Confira nosso novo produto!'
})

body: JSON.stringify({
    action:  'send_media',
    to:      '5511999990000',
    type:    'image',
    url:     'https://exemplo.com/produto.jpg',
    caption: 'Confira nosso novo produto!'
})

Exemplo — documento PDF

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_media",
    "to": "5511999990000",
    "type": "document",
    "url": "https://exemplo.com/proposta.pdf",
    "caption": "Segue a proposta em anexo.",
    "sendtobitrix24": true
  }'

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action'          => 'send_media',
    'to'              => '5511999990000',
    'type'            => 'document',
    'url'             => 'https://exemplo.com/proposta.pdf',
    'caption'         => 'Segue a proposta em anexo.',
    'sendtobitrix24' => true,
]));

requests.post(url, headers=headers, json={
    'action':          'send_media',
    'to':              '5511999990000',
    'type':            'document',
    'url':             'https://exemplo.com/proposta.pdf',
    'caption':         'Segue a proposta em anexo.',
    'sendtobitrix24': True
})

body: JSON.stringify({
    action:          'send_media',
    to:              '5511999990000',
    type:            'document',
    url:             'https://exemplo.com/proposta.pdf',
    caption:         'Segue a proposta em anexo.',
    sendtobitrix24: true
})

Exemplo — áudio (mensagem de voz)

🎵

Requisitos de formato para áudio (WAPI)

Para que o áudio seja entregue como mensagem de voz — com forma de onda animada e botão de play — o arquivo deve ser:

  • Container: OGG (.ogg)
  • Codec: Opus
  • Canais: mono (1 canal)

Arquivos .mp3 também são aceitos mas aparecem como áudio simples, sem forma de onda. Formatos como .wav e .m4a não são suportados.

Para converter qualquer arquivo para o formato correto usando ffmpeg:

ffmpeg -i entrada.mp3 -ac 1 -c:a libopus -b:a 32k saida.ogg

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_media",
    "to": "5511999990000",
    "type": "audio",
    "url": "https://exemplo.com/mensagem.ogg"
  }'
# Nota: "caption" é ignorado para áudio

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action' => 'send_media',
    'to'     => '5511999990000',
    'type'   => 'audio',
    'url'    => 'https://exemplo.com/mensagem.ogg',
    // caption ignorado para áudio
]));

requests.post(url, headers=headers, json={
    'action': 'send_media',
    'to':     '5511999990000',
    'type':   'audio',
    'url':    'https://exemplo.com/mensagem.ogg'
    # caption ignorado para áudio
})

body: JSON.stringify({
    action: 'send_media',
    to:     '5511999990000',
    type:   'audio',
    url:    'https://exemplo.com/mensagem.ogg'
    // caption ignorado para áudio
})

Respostas

200 Mídia enviada

{ "success": true, "ts": 1718000000, "data": { "message_id": "3EB0A12345ABCDEF", "to": "5511999990000", "type": "image" } }

422 URL inacessível

{"success":false,"error":"Could not download media from the provided URL.","ts":1718000000}

413 Arquivo muito grande

{"success":false,"error":"Media file exceeds 20 MB limit.","ts":1718000000}

Tipos de mídia

Suporte e comportamento por tipo e provedor.

type	WAPI	Meta	Observações
image	✓ URL direta	✓ Upload + envio	jpg, jpeg, png, gif, webp
video	✓ URL direta	✓ Upload + envio	mp4, avi, mov
audio	✓ Base64 + Ptt	✓ Upload + envio	WAPI: requer OGG + Opus + mono para voz com forma de onda. ver nota acima
document	✓ Base64	✓ Upload + envio	PDF, DOCX, XLSX e outros. Nome do arquivo extraído da URL.

ℹ Para WAPI, áudios e documentos são baixados pelo servidor antes do envio e convertidos para base64. Garanta que a URL seja acessível e retorne o arquivo correto (HTTP 200, sem redirecionamentos problemáticos).

Provedores

Diferenças entre WAPI e Meta Cloud API.

WAPI

Vantagens: Janela de conversas ilimitada. Suporte a formatação WhatsApp nativa. Sem aprovação de templates. sendtobitrix24 suportado.

Limitações: Sessão não-oficial — pode exigir re-pareamento após atualizações do WhatsApp.

Meta Cloud API

Vantagens: API oficial Meta. Alta disponibilidade. Número verificado com badge.

Limitações: Janela de 24h para mensagens livres. Fora da janela exige templates aprovados. sendtobitrix24 não suportado.

Formato de telefone

Como formatar o parâmetro to.

País	Formato	Exemplo
Brasil	55 + DDD + número	5511999990000
EUA / Canadá	1 + área + número	12125550100
Portugal	351 + número	351912345678

✓ A API remove automaticamente espaços, traços e parênteses. +55 (11) 99999-0000 e 5511999990000 são tratados como equivalentes.

⚠ Celulares brasileiros obrigatoriamente com nono dígito. O formato correto é 55 + DDD + 9 + 8 dígitos = 13 dígitos no total. Exemplo: 5511999990000 ✓ — 551199990000 ✗. A ausência do nono dígito resulta em falha de entrega silenciosa — a API processa a requisição normalmente, mas a mensagem nunca chega ao destinatário.

Enviar para grupos

Mensagens para grupos do WhatsApp — disponível apenas em WAPI.

WAPI — Suportado

Use send_text e send_media normalmente, apenas informe o JID do grupo no campo to no lugar do número. Todos os tipos de mídia funcionam (image, video, audio, document).

Meta — Não suportado

A WhatsApp Cloud API da Meta não permite envio para grupos — é uma limitação da própria Meta, não da nossa integração. Para mensagens em grupos, utilize uma conexão WAPI.

Formato do JID de grupo

Um grupo do WhatsApp é identificado por um JID no seguinte padrão (15–20 dígitos seguidos do sufixo @g.us):

120363041234567890@g.us

✓ A API também aceita o JID sem o sufixo, desde que tenha 16 ou mais dígitos — nesse caso, @g.us é adicionado automaticamente. Recomendamos sempre enviar o JID completo para evitar ambiguidades.

Como obter o JID de um grupo

A forma mais prática é configurar um webhook. Quando qualquer mensagem for enviada no grupo, o payload conterá o JID no campo event.Info.Chat, com event.Info.IsGroup = true. Armazene esse JID vinculado ao nome do grupo no seu sistema para uso posterior em disparos.

Exemplo — texto em grupo

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-wapi" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_text",
    "to": "120363041234567890@g.us",
    "message": "Bom dia, pessoal! ☀️"
  }'

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action'  => 'send_text',
    'to'      => '120363041234567890@g.us',
    'message' => 'Bom dia, pessoal! ☀️',
]));

requests.post(url, headers=headers, json={
    'action':  'send_text',
    'to':      '120363041234567890@g.us',
    'message': 'Bom dia, pessoal! ☀️'
})

body: JSON.stringify({
    action:  'send_text',
    to:      '120363041234567890@g.us',
    message: 'Bom dia, pessoal! ☀️'
})

Exemplo — mídia em grupo

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-wapi" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "send_media",
    "to": "120363041234567890@g.us",
    "type": "image",
    "url": "https://exemplo.com/comunicado.jpg",
    "caption": "Novidades da semana!"
  }'

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action'  => 'send_media',
    'to'      => '120363041234567890@g.us',
    'type'    => 'image',
    'url'     => 'https://exemplo.com/comunicado.jpg',
    'caption' => 'Novidades da semana!',
]));

requests.post(url, headers=headers, json={
    'action':  'send_media',
    'to':      '120363041234567890@g.us',
    'type':    'image',
    'url':     'https://exemplo.com/comunicado.jpg',
    'caption': 'Novidades da semana!'
})

body: JSON.stringify({
    action:  'send_media',
    to:      '120363041234567890@g.us',
    type:    'image',
    url:     'https://exemplo.com/comunicado.jpg',
    caption: 'Novidades da semana!'
})

⚠ Limitações: send_template não pode ser enviado para grupos — templates são exclusivos da Meta Cloud API, que não suporta grupos. Todas as regras de formato da seção Enviar mídia continuam valendo (inclusive OGG + Opus para áudios de voz com forma de onda).

ℹ sendtobitrix24 funciona normalmente em grupos — o chat do grupo é criado automaticamente no Bitrix24 e a mensagem enviada fica registrada na conversa correspondente.

Listar templates

Retorna os templates aprovados da conta Meta.

GET api.php ?action=list_templates

Parâmetro	Tipo		Descrição
action	string	obrig.	"list_templates"

Enviar template

Envia um template aprovado pela Meta para um número.

POST api.php action=send_template

Parâmetro	Tipo		Descrição
action	string	obrig.	"send_template"
to	string	obrig.	Número destino com DDI, apenas dígitos
template_name	string	obrig.	Nome exato do template no WhatsApp Business Manager (ex: `boas_vindas`)
template_lang	string	opcl.	Código de idioma do template. Padrão: `pt_BR`. Outros: `en_US`, `es`
components_json	string (JSON)	opcl.	Array JSON com os componentes de variáveis do template (corpo, botões). Ver exemplo abaixo.
header_media_url	string	opcl.	URL pública de mídia para o cabeçalho do template (image, video ou document)
header_media_type	string	opcl.*	Obrigatório se `header_media_url` for informado: `image` \| `video` \| `document`

Encerrar conversa

Finaliza o atendimento ativo no Bitrix24 para um número.

POST api.php action=close_chat

WAPIMeta

▼

Encerra o atendimento ativo no Canal Aberto do Bitrix24 vinculado ao número informado, chamando imopenlines.operator.finish. O chat_id é resolvido automaticamente a partir do histórico de mensagens da conexão — é necessário que ao menos uma mensagem tenha sido trocada após a instalação para que o chat_id esteja disponível.

⚠ Esta ação não funciona após uma transferência. Uma vez que o atendimento é transferido via transfer_chat, o encerramento passa a ser responsabilidade do agente receptor no Bitrix24 ou de um fluxo interno de automação — a API não consegue mais encerrar o chat remotamente.

Parâmetros

Parâmetro	Tipo		Descrição
action	string	obrig.	"close_chat"
to	string	obrig.	Número do cliente com DDI (apenas dígitos). Celulares brasileiros: sempre inclua o nono dígito (13 dígitos no total).

Exemplo

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{"action":"close_chat","to":"5511999990000"}'

$ch = curl_init('https://b24.falefacilchat.com.br/api.php');
curl_setopt_array($ch, [
    CURLOPT_POST           => 1,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => [
        'X-Api-Key: sua-chave-aqui',
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'action' => 'close_chat',
        'to'     => '5511999990000',
    ]),
]);
$data = json_decode(curl_exec($ch), true);

import requests

resp = requests.post(
    'https://b24.falefacilchat.com.br/api.php',
    headers={'X-Api-Key': 'sua-chave-aqui'},
    json={'action': 'close_chat', 'to': '5511999990000'}
)

const resp = await fetch('https://b24.falefacilchat.com.br/api.php', {
    method: 'POST',
    headers: {
        'X-Api-Key': 'sua-chave-aqui',
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({ action: 'close_chat', to: '5511999990000' })
});
const { data } = await resp.json();

Respostas

200 Conversa encerrada

{
  "success": true,
  "ts": 1718000000,
  "data": {
    "closed":     true,
    "to":         "5511999990000",
    "chat_id":    4821,
    "session_id": 312
  }
}

404 Conversa não encontrada

{"success":false,"error":"No active Bitrix24 chat found for this phone number. The chat_id may not have been captured yet — ensure at least one message was exchanged after the update.","ts":1718000000}

502 Erro no Bitrix24

{"success":false,"error":"Access denied","ts":1718000000}

Transferir conversa

Transfere o atendimento para outro usuário ou fila no Bitrix24.

POST api.php action=transfer_chat

WAPIMeta

▼

Transfere o atendimento ativo no Canal Aberto do Bitrix24 para um agente específico ou para uma fila de distribuição, chamando imopenlines.operator.transfer. Após a transferência, o endpoint close_chat deixa de funcionar para este atendimento — o encerramento deve ser feito pelo agente receptor ou por automação interna do Bitrix24.

ℹ O transfer_id é o ID numérico do usuário ou da fila no Bitrix24. Para localizar: usuários em Bitrix24 → Configurações → Usuários (coluna ID); filas em Bitrix24 → Contact Center → Canais Abertos → canal desejado → aba Fila.

Parâmetros

Parâmetro	Tipo		Descrição
action	string	obrig.	"transfer_chat"
to	string	obrig.	Número do cliente com DDI (apenas dígitos). Celulares brasileiros: sempre inclua o nono dígito (13 dígitos no total).
transfer_id	integer	obrig.	ID numérico do usuário ou da fila de destino no Bitrix24. Deve conter apenas dígitos.
transfer_type	string	opcl.	`user` para transferir a um agente específico; `queue` para uma fila de distribuição. Padrão: `user`.

Exemplo — transferir para usuário

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "transfer_chat",
    "to": "5511999990000",
    "transfer_id": "42",
    "transfer_type": "user"
  }'

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action'        => 'transfer_chat',
    'to'            => '5511999990000',
    'transfer_id'   => '42',
    'transfer_type' => 'user',
]));

requests.post(url, headers=headers, json={
    'action':        'transfer_chat',
    'to':            '5511999990000',
    'transfer_id':   '42',
    'transfer_type': 'user'
})

body: JSON.stringify({
    action:        'transfer_chat',
    to:            '5511999990000',
    transfer_id:   '42',
    transfer_type: 'user'
})

Exemplo — transferir para fila

curl -X POST "https://b24.falefacilchat.com.br/api.php" \
  -H "X-Api-Key: sua-chave-aqui" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "transfer_chat",
    "to": "5511999990000",
    "transfer_id": "7",
    "transfer_type": "queue"
  }'

curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'action'        => 'transfer_chat',
    'to'            => '5511999990000',
    'transfer_id'   => '7',
    'transfer_type' => 'queue',
]));

requests.post(url, headers=headers, json={
    'action':        'transfer_chat',
    'to':            '5511999990000',
    'transfer_id':   '7',
    'transfer_type': 'queue'
})

body: JSON.stringify({
    action:        'transfer_chat',
    to:            '5511999990000',
    transfer_id:   '7',
    transfer_type: 'queue'
})

Respostas

200 Conversa transferida

{
  "success": true,
  "ts": 1718000000,
  "data": {
    "transferred":   true,
    "to":            "5511999990000",
    "chat_id":       4821,
    "transfer_type": "user",
    "transfer_id":   42,
    "session_id":    312
  }
}

404 Conversa não encontrada

{"success":false,"error":"No active Bitrix24 chat found for this phone number. The chat_id may not have been captured yet — ensure at least one message was exchanged after the update.","ts":1718000000}

400 transfer_id inválido

{"success":false,"error":"\"transfer_id\" must be a numeric Bitrix24 user ID or queue ID.","ts":1718000000}

Webhooks

Receba eventos do WhatsApp em tempo real no seu sistema.

Webhooks permitem que o seu sistema seja notificado automaticamente sempre que uma mensagem for recebida no WhatsApp. Em vez de ficar consultando a API (polling), o seu endpoint recebe os dados assim que o evento acontece.

Como funciona

📱 WhatsApp

Mensagem recebida

→

⚙️ Fale Fácil

Processa + repassa

→

🔗 Seu endpoint

POST automático

→

🤖 Seu sistema

N8N, Make, código...

Configuração

Configure o endpoint de destino diretamente no painel, dentro das configurações de cada conexão — aba Desenvolvedor. Basta informar a URL e salvar. O repasse começa imediatamente, sem necessidade de reiniciar a conexão.

✓ O endpoint configurado precisa ser publicamente acessível via HTTPS e responder com HTTP 200 em até 10 segundos. Timeouts ou erros não bloqueiam o fluxo principal — o evento é processado normalmente no sistema mesmo se o repasse falhar.

Headers enviados em cada requisição

Content-Type: application/json

X-Webhook-Token: {seu_token}

O X-Webhook-Token é um token fixo por conexão, visível na aba Desenvolvedor. Use-o para validar que a requisição veio do sistema.

Exemplo de payload recebido (WAPI — mensagem de texto)

{ "connection_id": 12, "event": { "Info": { "Chat": "554599698247@s.whatsapp.net", "Sender": "554599698247@s.whatsapp.net", "IsFromMe": false, "IsGroup": false, "ID": "3EB0A12345ABCDEF", "Type": "text", "PushName": "João Silva", "Timestamp": "2026-04-16T14:30:00-03:00" }, "Message": { "conversation": "Olá! Gostaria de saber sobre os planos." } }, "type": "Message" }

Exemplo de payload recebido (Meta — mensagem de texto)

{ "connection_id": 15, "message": { "from": "5511999990000", "id": "wamid.HBgLNTU...", "timestamp": "1718000000", "type": "text", "text": { "body": "Oi, preciso de ajuda." } }, "contact": { "profile": { "name": "Maria Souza" }, "wa_id": "5511999990000" }, "metadata": { "phone_number_id": "123456789" } }

ℹ

O campo connection_id é sempre injetado pelo sistema no payload antes do repasse — independente do provedor. Use-o para identificar qual conexão originou o evento quando você tem múltiplas conexões apontando para o mesmo endpoint.

Validando o token no seu endpoint

<?php
// Valida que a requisição veio do sistema
$token = $_SERVER['HTTP_X_WEBHOOK_TOKEN'] ?? '';
if ($token !== 'seu-webhook-token-aqui') {
    http_response_code(403);
    exit;
}

// Lê o payload
$payload = json_decode(file_get_contents('php://input'), true);
$connId  = $payload['connection_id'];

// WAPI: mensagem no campo event.Message.conversation
// Meta:  mensagem no campo message.text.body

// Responde 200 rapidamente para não bloquear o repasse
http_response_code(200);
echo 'ok';

// Seu processamento aqui...

from flask import Flask, request, abort
import json

app = Flask(__name__)
WEBHOOK_TOKEN = "seu-webhook-token-aqui"

@app.route("/webhook", methods=["POST"])
def webhook():
    token = request.headers.get("X-Webhook-Token", "")
    if token != WEBHOOK_TOKEN:
        abort(403)

    payload = request.get_json()
    conn_id = payload.get("connection_id")

    # WAPI: payload["event"]["Message"]["conversation"]
    # Meta: payload["message"]["text"]["body"]

    return "ok", 200

const express = require("express");
const app = express();
app.use(express.json());

const WEBHOOK_TOKEN = "seu-webhook-token-aqui";

app.post("/webhook", (req, res) => {
    const token = req.headers["x-webhook-token"];
    if (token !== WEBHOOK_TOKEN) {
        return res.status(403).send("Forbidden");
    }

    const { connection_id, event, message } = req.body;

    // WAPI: event.Message.conversation
    // Meta: message.text.body

    res.send("ok"); // responder 200 rapidamente
});

Caso de uso com N8N

Configure um nó Webhook no N8N como trigger. Cole a URL gerada no campo de endpoint da aba Desenvolvedor da conexão. A partir daí, cada mensagem recebida no WhatsApp dispara o workflow automaticamente — você pode responder usando um nó HTTP Request apontando para a send_text desta API, criando um fluxo completo de atendimento automatizado.

⚠ Webhooks são disparados para todas as mensagens recebidas, incluindo mensagens enviadas pelo próprio número (IsFromMe: true em WAPI). Filtre pelo campo IsFromMe ou equivalente Meta para evitar loops de resposta automática.

Nodes para n8n

Automatize workflows com WhatsApp usando nosso community node oficial.

O pacote n8n-nodes-falefacilchat traz todos os endpoints desta API como nodes nativos do n8n, além de um Trigger que recebe mensagens em tempo real via webhook. Funciona com ambos os provedores (WAPI e Meta Cloud API) e entrega um output normalizado — você escreve o workflow uma vez e ele funciona com qualquer conexão.

Instalação via n8n

No n8n, acesse Settings → Community Nodes → Install a community node e informe o nome do pacote:

n8n-nodes-falefacilchat

Instalação via npm (self-hosted)

# Dentro da pasta do n8n
cd ~/.n8n
npm install n8n-nodes-falefacilchat

# Reinicie o n8n após a instalação

Nodes disponíveis

Node	Recurso	Operação
Fale Fácil Chat	Mensagem	Enviar texto para número ou grupo
Fale Fácil Chat	Mídia	Enviar imagem, vídeo, áudio ou documento
Fale Fácil Chat	Template	Listar e enviar templates aprovados (Meta)
Fale Fácil Chat	Conexão	Status e listagem de conexões do cliente
Fale Fácil Chat	Atendimento	Encerrar ou transferir o atendimento ativo no Bitrix24 — para usuário específico ou fila de distribuição
Fale Fácil Chat Trigger	Webhook	Recebe mensagens do WhatsApp em tempo real

Configuração em 3 passos

1

Crie a credencialNo n8n, adicione uma credencial do tipo Fale Fácil Chat API colando a API Key gerada no painel.

2

Configure o TriggerAdicione o node Fale Fácil Chat Trigger, ative o workflow e copie a URL gerada pelo n8n.

3

Cole no painelAbra a aba Desenvolvedor da conexão no painel, cole a URL em Endpoint de webhook e salve.

✓ Opcionalmente, configure também o campo Webhook Token no node — o Trigger validará automaticamente o header X-Webhook-Token, garantindo que só requisições legítimas disparem seu workflow.

Output normalizado do Trigger

O Trigger entrega um objeto com campos unificados entre WAPI e Meta, eliminando a necessidade de tratar cada provedor separadamente:

{ "provider": "wapi", "connection_id": 12, "from": "5511999990000", "fromName": "João Silva", "messageId": "3EB0A12345ABCDEF", "messageType": "text", "timestamp": "2026-04-16T14:30:00-03:00", "isGroup": false, "isFromMe": false, "text": "Olá! Gostaria de saber sobre os planos.", "raw": { ... } }

O campo raw preserva o payload original completo do provedor — use-o quando precisar de algum campo específico não incluído no objeto normalizado.

Casos de uso comuns

Cenário	Fluxo no n8n
Resposta automática	Trigger → IF (texto contém "horário") → Enviar Texto
Relatório agendado em PDF	Schedule → Gerar PDF → Enviar Mídia (document)
Disparos em massa	Planilha → Loop → Enviar Template (Meta)
Chatbot com IA	Trigger → OpenAI/Claude → Enviar Texto
Transferência por palavra-chave	Trigger → IF (texto contém "falar com atendente") → Atendimento: Transferir (fila)
Encerramento automático	Trigger → IF (texto = "obrigado" ou "resolvido") → Atendimento: Encerrar

ℹ O recurso Atendimento exige que ao menos uma mensagem tenha sido trocada na conversa antes de encerrar ou transferir — o sistema precisa ter registrado o chat_id interno do Bitrix24. Após uma transferência, o node Encerrar Atendimento deixa de funcionar para o mesmo número — o encerramento passa a ser responsabilidade do agente receptor ou de automação interna do Bitrix24.

⚠ Ative a opção Ignorar mensagens próprias no node Trigger (ou filtre por isFromMe === false) para evitar loops infinitos — sem isso, o workflow responde às próprias respostas automáticas.

Collection Postman

Teste todos os endpoints em segundos, sem escrever uma linha de código.

Fale Fácil Chat — API v1.1

Collection completa com todos os endpoints, variáveis de ambiente pré-configuradas e exemplos de resposta salvos. Inclui WAPI, Meta Cloud API e templates.

Baixar collection

Como importar

1

Baixe o arquivoClique em "Baixar collection" acima e salve o arquivo .json em qualquer pasta.

2

Importe no PostmanAbra o Postman → clique em Import → arraste o arquivo ou clique para selecionar.

3

Configure as variáveisVá em Collections → Fale Fácil Chat → Variables e substitua os valores marcados com SUBSTITUA_....

Variáveis da collection

Variables — edite antes de executar

{{api_key}} obrig.

Sua API Key (visível no painel após geração)

{{to}} obrig.

Número de destino com DDI, apenas dígitos. Ex: 5511999990000

Nome exato do template aprovado no WhatsApp Business Manager

Idioma do template. Padrão: pt_BR

URL de imagem pública para testes (pré-preenchida com exemplo)

URL de documento PDF público para testes (pré-preenchida)

URL de áudio público para testes (idealmente .ogg Opus)

✓ As requests de mídia já têm URLs de exemplo públicas pré-preenchidas para você testar imediatamente após configurar api_key e to. As respostas esperadas estão salvas em cada request como exemplos de referência.

ℹ Requests de Templates funcionam apenas com chaves de conexões Meta Cloud API. Ao usar uma chave WAPI nesses requests, a API retorna erro 400 explicando a limitação — comportamento esperado e documentado na collection.

Próximos recursos

Funcionalidades planejadas para as próximas versões da API.

📍

Localização

Envie coordenadas geográficas que abrem diretamente no Google Maps dentro do WhatsApp. Ideal para endereços de entrega, pontos de atendimento e rastreamento em tempo real.

★ Em breve

👤

Contato (vCard)

Compartilhe cartões de contato com nome, telefone e e-mail. O destinatário poderá salvar o contato diretamente pelo WhatsApp com um único toque.

★ Em breve

🔘

Mensagem com botões

Mensagens interativas com botões de resposta rápida (WAPI) e listas de seleção ou botões de call-to-action (Meta via templates aprovados).

★ Em breve

ℹ Todos os novos endpoints seguirão o mesmo padrão de autenticação, envelope de resposta e suporte a JSON body da API atual. A documentação é atualizada automaticamente ao liberar cada recurso.

Integrador oficial de WhatsApp para Bitrix24

Visão geral

Autenticação

Rate limit

Erros

Status da conexão

Listar conexões

Enviar texto

Enviar mídia

Tipos de mídia

Provedores

Formato de telefone

Enviar para grupos

Listar templates

Enviar template

Encerrar conversa

Transferir conversa

Webhooks

Nodes para n8n

Collection Postman

Fale Fácil Chat — API v1.1

Próximos recursos