Referência da API

API REST do Falia (atendimento com IA no WhatsApp). Base: https://falia.com.br/api/v1. Erros em application/problem+json (RFC 9457) com request_id. Datas em milissegundos UTC. Paginação por cursor. Aceita e devolve trace W3C (traceparent / X-Trace-Id). Webhooks assinados com HMAC-SHA256 (X-Proton-Signature). MCP em https://falia.com.br/mcp.

Versão 0.3.0. Gerado de openapi.json — não edite à mão.

Conexão do número de WhatsApp

Estado da conexão com o WhatsApp

GET /api/v1/status

Autenticação: api_key (conversations:read)

Respostas: 200 ConnectionStatus · 401 · 502

Conversas e mensagens

Listar conversas

GET /api/v1/conversations

Da mais recente para a mais antiga. Paginação por cursor.

Autenticação: api_key (conversations:read)

Parâmetro	Onde	Tipo	Descrição
limit	query	integer	1 a 100 (padrão 50).
cursor	query	string

Respostas: 200 ConversationPage · 400 · 401 · 403

Mensagens de uma conversa

GET /api/v1/conversations/{id}/messages

As mensagens mais recentes, da mais antiga para a mais nova.

Autenticação: api_key (conversations:read)

Parâmetro	Onde	Tipo	Descrição
id	path	string	id da conversa (ex.: 5511999990000@s.whatsapp.net)
limit	query	integer	Quantas das mensagens mais recentes: 1 a 100 (padrão 40).

Respostas: 200 MessageList · 400 · 401 · 403

Mudar o status da conversa

POST /api/v1/conversations/{id}/status

open (aberta), pending (aguardando o cliente) ou resolved (resolvida). Mensagem nova do cliente reabre a conversa.

Autenticação: api_key (messages:send)

Parâmetro	Onde	Tipo	Descrição
id	path	string	id da conversa (ex.: 5511999990000@s.whatsapp.net)

Corpo: StatusInput

Respostas: 200 ConversationStatus · 400 · 401 · 403

Enviar mensagem de texto ou modelo

POST /api/v1/messages

Aceita Idempotency-Key: repetir a chamada com a mesma chave em até 24 h devolve a mesma resposta sem enviar de novo. Limite: 1000 mensagens por dia por empresa. Na API oficial, texto livre só até 24 h depois da última mensagem do cliente (409 depois disso); fora da janela, envie template.

Autenticação: api_key (messages:send)

Parâmetro	Onde	Tipo	Descrição
Idempotency-Key	header	string (opcional)	Chave única da operação (até 100 caracteres)

Corpo: NewMessage

Respostas: 201 SentMessage · 400 · 403 · 409 · 429 · 502

Modelos aprovados (API oficial)

GET /api/v1/templates

Modelos aprovados pela Meta para a conta da empresa. Só para empresas na API oficial (409 nas demais).

Autenticação: api_key (conversations:read)

Respostas: 200 TemplateList · 401 · 403 · 409 · 502

Eventos enviados para o seu sistema: message.received, message.sent, connection.updated, conversation.handoff_requested, conversation.updated, conversation.rated, message.status_updated

Reenviar uma entrega

POST /api/v1/webhook-deliveries/{id}/retry

Autenticação: api_key (webhooks:manage)

Parâmetro	Onde	Tipo	Descrição
id	path	integer

Respostas: 202 · 404

Listar endpoints de webhook

GET /api/v1/webhooks

Autenticação: api_key (webhooks:manage)

Respostas: 200 Endpoint[] · 401 · 403

Cadastrar endpoint de webhook

POST /api/v1/webhooks

Eventos: message.received, message.sent, connection.updated, conversation.handoff_requested ou *. O secret volta só nesta resposta.

Autenticação: api_key (webhooks:manage)

Corpo: NewEndpoint

Respostas: 201 CreatedEndpoint · 400 · 403

Remover endpoint de webhook

DELETE /api/v1/webhooks/{id}

Autenticação: api_key (webhooks:manage)

Parâmetro	Onde	Tipo	Descrição
id	path	integer

Respostas: 204 · 404

Últimas 100 entregas de um endpoint

GET /api/v1/webhooks/{id}/deliveries

Autenticação: api_key (webhooks:manage)

Parâmetro	Onde	Tipo	Descrição
id	path	integer

Respostas: 200 Delivery[] · 404

Modelos

ApiMessage

Campo	Tipo	Obrigatório	Descrição
id	string	sim
from_me	boolean	sim
sent_at	integer	sim	Milissegundos UTC.
kind	string	sim	text, image, audio, video, document, sticker, poll…
text	string	sim
has_media	boolean	sim
author	string (opcional)	não	Quem enviou pelo Falia (atendente, robô ou API key), quando from_me.
sender	string (opcional)	não	Em grupos, quem mandou.

ApiTemplate

Campo	Tipo	Obrigatório	Descrição
name	string	sim
language	string	sim	Ex.: pt_BR.
category	string	sim	MARKETING, UTILITY ou AUTHENTICATION.
body	string	sim	Texto do corpo com as variáveis 1, 2…
params	integer	sim
supported	boolean	sim	false: cabeçalho ou botão variável; envie pelo Gerenciador do WhatsApp.

ConnectionStatus

Campo	Tipo	Obrigatório	Descrição
state	string	sim	open (conectado), connecting, close ou inexistente (nunca conectado).
provider	string	sim	evolution (QR code) ou cloud (API oficial da Meta).

Conversation

Campo	Tipo	Obrigatório	Descrição
id	string	sim	Identificador da conversa no WhatsApp (ex.: 5511999990000@s.whatsapp.net).
name	string	sim
is_group	boolean	sim
unread	integer	sim
last_message_at	integer	sim	Última mensagem (milissegundos UTC); 0 se desconhecido.
last_message_text	string (opcional)	não
last_message_from_me	boolean (opcional)	não
status	string	sim	open (cliente escreveu), pending (aguardando o cliente) ou resolved.
assignee	null | Person	não
tags	string[]	sim	Nomes das etiquetas da conversa.

ConversationPage

Campo	Tipo	Obrigatório	Descrição
data	Conversation[]	sim
next_cursor	string (opcional)	não	Passe em cursor para a próxima página; null quando acabou.

ConversationStatus

Campo	Tipo	Obrigatório	Descrição
id	string	sim
status	string	sim

CreatedEndpoint

Delivery

Campo	Tipo	Obrigatório	Descrição
id	integer	sim
event_id	string	sim
event_type	string	sim
status	string	sim	pending, delivered ou failed.
attempts	integer	sim
last_status	integer (opcional)	não
last_error	string (opcional)	não
created_at	integer	sim
delivered_at	integer (opcional)	não

Endpoint

Campo	Tipo	Obrigatório	Descrição
id	integer	sim
url	string	sim
events	string[]	sim
active	boolean	sim
created_at	integer	sim

MessageList

Campo	Tipo	Obrigatório	Descrição
data	ApiMessage[]	sim	Do mais antigo para o mais novo.

NewEndpoint

Campo	Tipo	Obrigatório	Descrição
url	string	sim	URL https:// pública que receberá os eventos.
events	string[]	sim	Eventos assinados; ["*"] para todos.

NewMessage

Campo	Tipo	Obrigatório	Descrição
to	string	sim	Número com DDD (11999990000, +55 11 99999-0000) ou id da conversa.
text	string (opcional)	não	1 a 4096 caracteres. Omitido quando vai template.
template	null | TemplateInput	não

Person

Campo	Tipo	Obrigatório	Descrição
id	integer	sim
name	string	sim

SentMessage

Campo	Tipo	Obrigatório	Descrição
id	string	sim
conversation_id	string	sim
sent_at	integer	sim

StatusInput

Campo	Tipo	Obrigatório	Descrição
status	string	sim	open, pending ou resolved.

TemplateInput

Campo	Tipo	Obrigatório	Descrição
name	string	sim
language	string	sim
params	string[]	não	Valores de 1, 2… (até 10, sem quebra de linha).

TemplateList

Campo	Tipo	Obrigatório	Descrição
data	ApiTemplate[]	sim