Flwchat API

API flw.chat — referência rápida

Gerado de https://flwchat.readme.io (109 endpoints, 3 serviços). Specs completos em openapi/.

⚠️ Base URL (erro nº 1)

https://api.wts.chat/{core|chat|crm}/{versão}/{recurso}

• O prefixo de serviço é obrigatório. https://api.wts.chat/v1/channel → 400 badrequest. O correto é https://api.wts.chat/chat/v1/channel.
• api.flw.chat é alias válido do mesmo backend (também exige o prefixo), mas api.wts.chat é o host canônico — é o que está nos specs. (Verificado por requisição real em 2026-09-15; o exemplo de curl do guia "Criar token" mostra api.flw.chat/v1/channel, que está errado — não copie de lá.)
• Nunca invente api.flw.chat/v1/... nem flwchat.readme.io como host de API.

Autenticação

Token permanente gerado em Ajustes > Integrações > Integração via API. Em toda requisição:

Authorization: Bearer pn_xxxxxxxxxxxxxxxxxxxxxx

Sem Bearer, ou com token inválido/revogado → 401 com key: ERROR_UNAUTHORIZED.

Paginação

Listagens usam pageNumber e pageSize (máx. 100) — query string nos GET, corpo nos POST /filter. Mantenha pageSize constante ao iterar, senão pageNumber devolve resultados deslocados.

// resposta
{ "pageNumber": 1, "pageSize": 50, "totalPages": 5, "totalItems": 250,
  "hasMorePages": true, "items": [ /* ... */ ] }

Itere enquanto hasMorePages === true.

Rate limiting — dois regimes distintos

Excedeu → 429 Too Many Requests. Implemente backoff exponencial; não repita imediatamente.

Envelope de erro

Todos os erros (4xx e 5xx) voltam nesta forma — guarde id.shortValue para abrir suporte:

{ "id": { "value": "c44bf0cc-...", "shortValue": "c44bf0cc" },
  "httpStatusCode": 401, "error": true, "date": "2026-09-15T19:41:56Z",
  "key": "ERROR_UNAUTHORIZED", "text": "Acesso negado", "isUnsolvableError": false }

Nos specs aparece como InternalException; ProblemDetails (RFC 7807) é o formato de validação em alguns 400. Atenção: rota inexistente sem token retorna 401, não 404 — a autenticação roda antes do roteamento.

Convenções

• Telefone: +55|11999999999 (DDI, pipe, número sem máscara) — formato de phonenumber.
• to = número de telefone ou @usuarioinstagram do destinatário. from = número/@usuario do canal da conta que envia (liste em GET /chat/v1/channel); omitido, a plataforma resolve o canal.
• IDs: UUID v4. Datas: ISO-8601 UTC (2026-09-15T19:41:56.925079Z).
• senderId: seu ID próprio, opcional em qualquer envio — serve para rastrear a mensagem depois sem guardar o ID da plataforma.
• sessionMetadata: chave-valor livre, acessível como variável no chatbot e devolvido nos webhooks.

Qual endpoint de envio usar

São três superfícies sobrepostas. Regra prática:

Regras que valem para todos os envios:

1. No WhatsApp, conversa só pode ser iniciada com template (regra repetida em todos os endpoints de envio). Sem conversa aberta, POST /chat/v1/send/text é recusado — use POST /chat/v1/send/template com um templateId de GET /chat/v1/template e parameters preenchido. Texto livre só depois que o contato responde (janela de atendimento do WhatsApp, 24 h).
2. Contato inexistente é criado automaticamente antes do envio. Não precisa criar antes.
3. Envio é assíncrono por padrão: a resposta traz id e status inicial, não a entrega. Acompanhe por GET /chat/v1/send/message/{id} (ou GET /chat/v1/message/{id}/status), ou passe callbackUrl no corpo e receba o webhook de entrega/falha. status de mensagem ∈ PROCESSING | SAVED | QUEUED | SENT | DELIVERED | READ | FAILED | DELETED | WAIT_REPLY; falha explica em failedReason. OTP usa outro enum: UNDEFINED | PENDING | SENT | RECEIVED | FAILED (consulta em GET /chat/v1/send/otp/{id}, que aceita o ID da mensagem ou o seu senderId).
4. options controla o atendimento criado: enableBot, hiddenSession, forceStartSession, user, department.
5. delayTyping (≤ 25 s) simula "digitando" antes de entregar. Em canal CloudAPI oficial prefira POST /chat/v1/send/typing.
6. refId responde a uma mensagem específica (reply).

Enviar arquivo — 3 passos

fileIdOrUrl aceita URL pública (caminho curto, nada a fazer) ou um FileId da plataforma. Para o FileId, que é reutilizável indefinidamente:

# 1. pede a URL de upload (Type: UNDEFINED|PDF|EXCEL|WORD|IMAGE|AUDIO|VIDEO|DOCUMENT)
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.wts.chat/core/v2/file?Type=IMAGE&Name=foto.jpg&MimeType=image/jpeg"
# -> { "tempFileId": "...", "urlUpload": "https://..." }

# 2. sobe o conteúdo com PUT na urlUpload (sem header de Authorization)
curl -X PUT --upload-file foto.jpg "$URL_UPLOAD"

# 3. confirma e recebe o FileId definitivo
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"tempFileId":"..."}' https://api.wts.chat/core/v2/file
# -> { "id": "FILE_ID", "name": ..., "mimeType": ..., "size": ... }

IMAGE e VIDEO passam por transformação/compressão para compatibilidade entre canais; DOCUMENT não.

Webhooks

Assine por API (POST /core/v1/webhook/subscription) ou em Ajustes > Integrações > Webhooks. A plataforma faz POST na sua URL pública com:

{ "eventType": "CONTACT_UPDATE", "date": "2026-09-15T16:42:35.4359934Z", "content": { } }

Eventos assináveis (enum fixo, de GET /core/v1/webhook/event):

SESSION_NEW  SESSION_UPDATE  SESSION_COMPLETE
MESSAGE_RECEIVED  MESSAGE_UPDATED  MESSAGE_SENT
CONTACT_NEW  CONTACT_UPDATE  CONTACT_TAG_UPDATE
PAYMENT_NEW  PAYMENT_UPDATE
PANEL_CARD_NEW  PANEL_CARD_UPDATE  PANEL_CARD_STEP_CHANGE
PANEL_CARD_NOTE_NEW  PANEL_CARD_NOTE_UPDATE

Assinatura pode ser desativada (pausa) sem ser removida. callbackUrl nos envios é um webhook pontual por mensagem, independente das assinaturas.

Exemplo mínimo

# template (único jeito de iniciar conversa no WhatsApp)
curl -X POST https://api.wts.chat/chat/v1/send/template \
  -H "Authorization: Bearer $FLW_TOKEN" -H "Content-Type: application/json" \
  -d '{
    "to": "+55|11999999999",
    "templateId": "UUID_DO_TEMPLATE",
    "parameters": { "1": "João", "2": "12345" },
    "senderId": "pedido-9876",
    "options": { "enableBot": true }
  }'

Onde achar o resto

• reference/*.md — 19 arquivos por domínio: todo campo de todo endpoint, com tipo, obrigatoriedade, descrição e enums, mais os schemas usados. É onde olhar antes de montar um payload.
• openapi/{core,chat,crm}.json — specs completos. Fonte de verdade para codegen/Postman.
• llms-full.md — tudo acima num arquivo só, para colar em janela de contexto.
• guides/ — páginas conceituais e tutoriais originais (auth, paginação, rate limit, webhooks, UTM, N8N, MAKE, firewall, login integrado).
• index.json — as 109 operações em JSON (método, path, resumo, tag, página de origem).
• python3 build.py regenera tudo da documentação publicada.

Índice de endpoints

Paths abaixo já incluem o prefixo de serviço — cole direto após https://api.wts.chat.

CORE — https://api.wts.chat/core

Arquivos

Campos

Carteiras

Contatos

Equipes

Etiquetas

Horários de Atendimento

Usuários

Webhooks

CHAT — https://api.wts.chat/chat

Canais de Atendimento

Chatbots

Conversas

Envios (Msg/Otp/Bot)

Mensagens

Mensagens Agendadas

Modelos de Mensagem

Sequências

CRM — https://api.wts.chat/crm

Cards

Painéis