API oficial do WhatsApp com CRM e IA, num só lugar.

Visão geral

O que é a FlashConnect

Um provedor de API oficial do WhatsApp (Cloud API da Meta) e, quando você quiser, um CRM completo de atendimento. Você escolhe o quanto usar.

Tudo o que o painel faz também está disponível por API e MCP. O painel é só mais um cliente da mesma API, então nada fica preso à tela.

Recursos

O que a plataforma entrega

Planos

Pague por número conectado

Todos os planos começam com período de teste. Troque de plano quando quiser: os módulos mudam na hora e o valor novo vale a partir da próxima cobrança.

As mensagens são cobradas pela Meta conforme a tabela oficial dela, direto no cartão que você cadastra na Meta, separado da assinatura. Os tokens de IA (Anthropic, OpenAI…) também são pagos direto ao provedor da IA.

Ligação oficial com a Meta

Coexistência: o melhor dos dois mundos

Seu número fica ao mesmo tempo no app WhatsApp Business do celular e na API oficial. Você ganha automação e CRM sem abrir mão do jeito que já atende.

Padrão × Coexistência

Janela de 24h: regra da Meta para mensagens pela API. Depois que o cliente fala com você, há 24 horas para responder livremente; fora disso, só com template aprovado pela Meta. A FlashConnect avisa antes de tentar (erro JANELA_EXPIRADA) e você cria e acompanha os templates pelo painel ou pela IA.

Passo a passo

Como conectar o número

1. Pré-requisitoNúmero do WhatsApp Business com pelo menos 7 dias de uso no app. É uma exigência da Meta para a coexistência.
2. Cadastro incorporado (Embedded Signup)Você faz login com o Facebook, escolhe a empresa e o número e aprova com o QR code no celular. Tudo dentro do fluxo oficial da Meta, sem passar senha para ninguém.
3. SincronizaçãoContatos e histórico de conversas são importados. O histórico entra no painel sem disparar automações nem respostas da IA.
4. ProntoMensagens do cliente chegam por webhook; as enviadas pelo celular chegam como eco (message.echo), marcadas como vindas do celular.

Na prática

Como fica o seu dia a dia

Sem termo técnico: o que muda para quem atende e para quem vende.

Para quem é

Do cadastro ao primeiro atendimento

1. Crie a contaCadastro rápido, com período de teste.
2. Conecte o número em coexistênciaLogin com Facebook e QR code. Seu celular continua funcionando.
3. Configure o agentePelo painel ou pedindo ao Claude. Cadastre produtos e conhecimento.
4. AtendaIA, equipe e celular na mesma conversa.

Segurança

Seus dados protegidos em cada camada

Cada cliente enxerga só o que é seu, e cada acesso deixa rastro.

Mantemos política para solicitações de autoridades e tratamos os dados conforme a LGPD, com o cliente como controlador dos dados dos seus contatos.

Para o time técnico

API REST

Tudo em JSON, autenticado por API key com escopos. Crie a chave no painel em Integrações → Nova chave.

Base:   https://qqyphyubrxyouaqicdbo.supabase.co/functions/v1
Header: Authorization: Bearer ck_live_…

• O segredo da chave aparece uma única vez. Guardamos só o hash; não há como recuperá-lo depois.
• Chave revogada responde 401 CHAVE_REVOGADA; chave sem o escopo do endpoint, 403 ESCOPO_INSUFICIENTE.

Endpoints

Regras que ajudam

• Fora da janela de 24h, pela API só passa template; o resto retorna JANELA_EXPIRADA antes de chamar a Meta.
• Erros vêm como { "erro", "codigo" }; falhas da Meta são traduzidas (limite de qualidade, número sem WhatsApp, token inválido…).
• Agendamento só aceita horários que a própria API listou como livres; conflito retorna HORARIO_INDISPONIVEL.
• Contato com opt-out não recebe template (OPT_OUT).

Exemplo: enviar uma mensagem

curl -X POST $BASE/whatsapp-send \
  -H "Authorization: Bearer $KEY" \
  -H "content-type: application/json" \
  -d '{"phone_number_id":"123456789012345","para":"5511999990000","texto":"Olá! Posso ajudar?"}'

Para o time técnico

Webhooks: a plataforma avisa a sua IA

Cadastre uma URL https no painel, escolha os eventos e guarde o secret. Todo evento chega assinado.

Eventos

Formato da entrega

POST <sua-url>
Content-Type: application/json
X-Castilho-Event: message.received
X-Castilho-Delivery: 7c1e…-uuid-da-entrega
X-Castilho-Signature: t=1758374400,v1=8f3a…hex

{
  "id": "7c1e…",
  "evento": "message.received",
  "tenant_id": "<uuid>",
  "criado_em": "2026-09-20T12:00:00.000Z",
  "dados": { … }
}

O id é igual ao X-Castilho-Delivery. Use-o como chave de idempotência: numa nova tentativa, a mesma entrega chega com o mesmo id.

Entrega confiável

• Responda 2xx em até 10 s. Qualquer outra coisa (erro, timeout, DNS) conta como falha.
• Novas tentativas em 1 min, 5 min, 15 min e 1 h. Depois de 5 tentativas, a entrega aparece no painel (Integrações → Entregas) com botão de reenviar.
• message.received e message.echo saem na hora, poucos segundos depois da Meta entregar. Os demais eventos saem no ciclo de 1 minuto.
• A ordem entre entregas não é garantida; dentro de uma conversa, ordene por dados.message.timestamp.

Como verificar a assinatura

v1 = HMAC-SHA256(secret, "<t>.<corpo cru>"), em hex minúsculo. Rejeite se o carimbo tiver mais de 300 s e compare em tempo constante. Use o corpo cru: reserializar o JSON muda os bytes e invalida a assinatura.

Vetor de teste: secret whsec_teste, t = 1700000000, corpo {"id":"d1","evento":"ping"} → v1 = 144ed65255014b00c5de7faf72d1a7d29015b86b7e78bc32f0dd21bd5ad2da8f.

Node (Express)

import crypto from "node:crypto";
import express from "express";

const SECRET = process.env.WEBHOOK_SECRET;
const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("x-castilho-signature") ?? "";
  const partes = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  const t = Number(partes.t);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(401);

  const esperado = crypto.createHmac("sha256", SECRET).update(`${t}.${req.body}`).digest("hex");
  const recebido = Buffer.from(partes.v1 ?? "", "hex");
  if (recebido.length !== 32 || !crypto.timingSafeEqual(Buffer.from(esperado, "hex"), recebido)) {
    return res.sendStatus(401);
  }

  const evento = JSON.parse(req.body);
  res.sendStatus(200);          // responda antes de processar
  processar(evento).catch(console.error);
});

Python (FastAPI)

import hmac, hashlib, json, time, os
from fastapi import FastAPI, Request, Response

SECRET = os.environ["WEBHOOK_SECRET"].encode()
app = FastAPI()

@app.post("/webhook")
async def webhook(req: Request):
    corpo = await req.body()                       # bytes crus
    header = req.headers.get("x-castilho-signature", "")
    partes = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    try:
        t = int(partes["t"])
    except (KeyError, ValueError):
        return Response(status_code=401)
    if abs(time.time() - t) > 300:
        return Response(status_code=401)

    esperado = hmac.new(SECRET, f"{t}.".encode() + corpo, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(esperado, partes.get("v1", "")):
        return Response(status_code=401)

    evento = json.loads(corpo)
    # enfileire e responda 200 rápido
    return {"ok": True}

Fluxo típico de uma IA

1. Recebe message.receivedCom a conversa em modo IA.
2. Busca o contextoGET /agent-config (persona, produtos, regras) e GET /messages-list (histórico).
3. RespondePOST /whatsapp-send, e agenda ou cria tarefa se for o caso.
4. Precisa de gente?POST /conversation-update com modo: "humano" e a equipe certa.

Integração com IAs

Claude e outras IAs gerenciam tudo por MCP

O servidor MCP da FlashConnect usa a mesma API key e os mesmos escopos. Conecte no Claude, ChatGPT ou n8n e peça em linguagem natural: a IA opera o atendimento e também configura a plataforma.

O que dá para pedir

"Mostre as conversas em modo IA e responda a da Ana confirmando a consulta de amanhã."

"Crie um agente de vendas com tom informal e cadastre estes 10 produtos."

"Marque um horário na agenda para sexta e crie uma tarefa de follow-up."

"Crie um template de lembrete de consulta e um webhook para o meu n8n."

Como conectar

1. Abra o painel em Conectar IAEscolha o destino (Claude, ChatGPT, outras IAs ou sistema próprio). Cada um mostra só as instruções daquele destino.
2. Gere a chave com os escopos certosSó leitura para consultar; envio e escrita para operar.
3. Peça para a IA rodar status_setupEla lê o que já está pronto e guia o próximo passo. O que exige navegador (conectar o número, cartão) vira um link que a IA entrega.

Segurança do MCP: cada ferramenta exige um escopo. Chave só de leitura não envia mensagem nem altera nada: recebe ESCOPO_INSUFICIENTE. Tudo é isolado por cliente e as ações ficam registradas.

Para o time técnico

Códigos de erro

Toda resposta de erro tem erro (mensagem legível) e codigo (estável, para o seu código tratar).

Nos erros 502 da Meta, o campo codigo_meta traz o código original da Meta.

Ajuda

Perguntas frequentes