Carrossel e Flows

Dois formatos que só existem em conexão oficial, porque ambos são construídos sobre a Cloud API: um carrossel de cards de produto, e um Flow — um formulário que abre dentro do WhatsApp, sem mandar a pessoa para o navegador.

Tecnicamente não compartilham nada, mas chegam no mesmo lugar: os toques e o formulário preenchido voltam como webhook da conexão.

Carrossel de produtos

Um carrossel é um template com um componente CAROUSEL: de 2 a 10 cards, cada um com header de mídia, corpo próprio e até dois botões. Todos os cards precisam ter o mesmo formato — mesmo tipo de header, mesma quantidade e tipo de botões. A Meta recusa um conjunto heterogêneo.

Dois uploads parecem a mesma coisa e não são intercambiáveis:

Nunca persista o mediaId. Suba de novo a cada envio.

{
  "to": "5511999998888",
  "name": "catalogo_demo",
  "language": "pt_BR",
  "components": [
    { "type": "carousel", "cards": [
      { "card_index": 0, "components": [
        { "type": "header", "parameters": [{ "type": "image", "image": { "id": "28801092679526768" } }] },
        { "type": "button", "sub_type": "quick_reply", "index": 0,
          "parameters": [{ "type": "payload", "payload": "add:SKU-FONE-ANC" }] },
        { "type": "button", "sub_type": "quick_reply", "index": 1,
          "parameters": [{ "type": "payload", "payload": "det:SKU-FONE-ANC" }] }
      ]}
    ]}
  ]
}

Dê um payload próprio a cada botão. O webhook não traz índice de card, então add:SKU-FONE-ANC nomeando produto e ação é o único jeito de saber qual card foi tocado.

Flows

Um Flow é um formulário com telas próprias. Existem dois tipos, e a diferença decide todo o resto:

Agendamento é o caso canônico de data_exchange: o cliente escolhe o dia, e os horários livres daquele dia precisam sair do seu sistema naquele instante.

{
  "to": "5511999998888",
  "header": "Fale com a gente",
  "body": "Preencha o formulário e a gente te responde hoje.",
  "cta": "Abrir formulário",
  "flowId": "1626797462403345",
  "flowAction": "navigate",
  "screen": "FORMULARIO",
  "flowToken": "lead-8812",
  "mode": "published"
}

flowToken é a sua correlação e o único fio de volta — o webhook que traz o formulário preenchido não inclui o id do Flow. Mande um id de pedido, de ticket, de lead. Se omitir, a gente gera pingo_<uuid> e devolve na resposta do envio.

Flows dinâmicos

Para data_exchange, a Meta criptografa cada requisição com RSA-2048 e AES-128-GCM. O Pingo é o endpoint registrado: ele decripta, repassa o JSON em claro para você, assinado, e encripta a sua resposta de volta.

O seu endpoint então recebe, no meio do preenchimento:

{ "action": "data_exchange", "screen": "ESCOLHER_DIA",
  "data": { "dia": "2026-10-05" }, "flow_token": "agendamento-8812" }

e responde com a próxima tela:

{ "screen": "ESCOLHER_HORA",
  "data": { "horarios": [{ "id": "09:00", "title": "09:00" }, { "id": "14:30", "title": "14:30" }] } }

O que volta

Toques e respostas chegam como messages.upsert no webhook da conexão, nos nós documentados na referência:

O formulário preenchido chega sempre aqui, nos dois tipos de Flow. O endpoint de data-exchange só cuida da conversa durante o preenchimento — muita gente configura ele e depois se pergunta por que as respostas nunca apareceram.