VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/WhatsApp Platform

Publicar, pré-visualizar e usar com IA

Publica um Flow global na Meta, gera o link de pré-visualização, cria um Flow a partir de uma descrição e testa qual Flow a IA enviaria.

Um Flow salvo em Flows globais ainda é só um rascunho da plataforma. Estas quatro operações fecham o ciclo: publicar na Meta, ver como fica, pedir um rascunho pronto a partir de uma descrição e testar se a IA de atendimento escolheria o Flow certo para uma mensagem.

Rascunho→Publicado na Meta→Pré-visualização→IA oferece ao cliente

Todas exigem root_admin com o privilégio manage_whatsapp_platform.

Publicar na Meta

POST/api/v1/admin/whatsapp-platform/flows/{id}/publishAdmin

Publicar o Flow na Meta

Valida o flow_json e faz três chamadas à Meta com as credenciais da plataforma: cria o Flow na conta (só na primeira vez), envia o JSON como arquivo do Flow e publica. Em caso de sucesso grava o meta_flow_id e muda o status para published. Publicar de novo um Flow que já tem meta_flow_id reaproveita o Flow da Meta e envia a nova versão do JSON. Não tem corpo.

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.
200Flow publicado
json
{
  "id": 4,
  "flow_key": "contato_rapido",
  "name": "Contato rápido",
  "scope": "global",
  "flow_json": { "version": "7.3", "screens": [] },
  "ai_when_to_use": "Cliente quer deixar um recado para a loja.",
  "ai_params": {},
  "status": "published",
  "version": 1,
  "meta_flow_id": "1234567890123456",
  "category": "CONTACT_US",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:05:31Z"
}

A resposta é o objeto Flow completo (veja Flows globais); o flow_json do exemplo foi encurtado.

Pré-visualizar

GET/api/v1/admin/whatsapp-platform/flows/{id}/previewAdmin

Obter o link de pré-visualização da Meta

Pede à Meta um link para ver o Flow renderizado, sem precisar de login (a Meta o mantém válido por cerca de 30 dias). Só funciona para um Flow que já existe na Meta, isto é, que foi publicado ao menos uma vez.

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.
200Link gerado
json
{ "preview_url": "https://business.facebook.com/wa/manage/flows/preview/?token=EXEMPLO" }

Campos da resposta

preview_urlstring
Endereço público de pré-visualização, entregue pela Meta.

Gerar um Flow a partir de uma descrição

POST/api/v1/admin/whatsapp-platform/flows/generateAdmin

Gerar um rascunho de Flow com IA

Você descreve em português o que quer ("um formulário de cadastro com nome, CPF e CEP") e a IA responde de dois jeitos: perguntas de esclarecimento, quando o pedido está vago, ou um Flow completo. Nada é salvo: o resultado volta para você revisar e, se aprovar, enviar a criação. Se a primeira tentativa vier com problemas de estrutura, a plataforma tenta uma segunda vez e fica com a que tiver menos problemas.

Corpo da requisição

promptstringobrigatório
O pedido em linguagem natural. Vazio devolve 400.
historyarray
Textos das rodadas anteriores (por exemplo, suas respostas às perguntas de esclarecimento), em ordem. Cada item é um texto.
200Flow gerado
json
{
  "questions": null,
  "flow_json": { "version": "7.3", "screens": [ { "id": "CADASTRO", "terminal": true, "layout": { "type": "SingleColumnLayout", "children": [] } } ] },
  "name": "Cadastro rápido",
  "flow_key": "cadastro_rapido",
  "when_to_use": "Cliente quer se cadastrar na loja.",
  "warnings": null
}
200A IA precisa de mais informação
json
{
  "questions": ["Quais campos o formulário deve ter?", "Precisa buscar o endereço pelo CEP?"],
  "flow_json": null,
  "name": "",
  "flow_key": "",
  "when_to_use": "",
  "warnings": null
}

Campos da resposta

questionsarray
Perguntas para você responder e reenviar em history. null quando já veio um Flow.
flow_jsonobject
O Flow gerado. null quando vieram perguntas.
namestring
Nome sugerido.
flow_keystring
Chave sugerida.
when_to_usestring
Texto sugerido para ai_when_to_use.
warningsarray
Problemas de validação do flow_json gerado, com as mesmas regras do POST /flows. null (nenhum problema) significa que ele passaria na criação. Também é null quando vieram perguntas.

Testar a escolha de Flow

POST/api/v1/admin/whatsapp-platform/flows/decideAdmin

Descobrir (e opcionalmente enviar) o Flow que a IA escolheria

Simula o atendimento: dada uma mensagem de cliente, a IA decide se algum Flow publicado serve e qual. O catálogo considerado é o conjunto de Flows publicados visível para a loja do seu token (globais, com os da loja prevalecendo pela mesma flow_key). Se não há Flow publicado, responde decided: false sem chamar a IA (mas, se a IA não estiver configurada, o erro 500 vem antes).

Sem phone é um teste a seco: só diz qual Flow escolheria. Com phone o Flow é enviado de verdade para esse telefone, pelo WhatsApp da loja.

Corpo da requisição

textstringobrigatório
Mensagem do cliente a simular. Vazio devolve 400.
phonestring
Telefone de destino. Se informado, o Flow escolhido é enviado a esse número.
200Decisão tomada
json
{ "flow_key": "cadastro_endereco", "decided": true, "sent": false }

Campos da resposta

flow_keystring
Chave do Flow escolhido; vazio quando a IA não escolheu nenhum.
decidedboolean
true quando algum Flow foi escolhido.
sentboolean
true quando o Flow foi escolhido e um phone foi informado, isto é, o envio foi feito.

Exemplo de requisição

bash
# publicar
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/flows/4/publish" \
  -H "Authorization: Bearer $TOKEN"

# gerar um rascunho
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/flows/generate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Formulário de cadastro com nome, CPF e CEP"}'

# teste a seco da escolha
curl -X POST "$BASE_URL/api/v1/admin/whatsapp-platform/flows/decide" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Quero mudar meu endereço de entrega"}'

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido{"error":"Invalid request body"}
400{id} que não é inteiro{"error":"Invalid id"}
400prompt vazio (generate){"error":"prompt é obrigatório"}
400text vazio (decide){"error":"text é obrigatório"}
400Publicar: credenciais da plataforma ausentes{"error":"whatsapp: credenciais da plataforma (token + WABA) não configuradas"}
400Pré-visualizar um Flow que nunca foi publicado{"error":"whatsapp: publique o flow na Meta antes de pré-visualizar"}
400Publicar ou pré-visualizar: Flow não encontrado, ou a Meta recusou a chamada{"error":"whatsapp: publicar flow: ..."} (com a mensagem da Meta, inclusive os campos inválidos do JSON)
422Publicar: flow_json inválido pela validação da plataforma{"error":"Flow JSON inválido","errors":["screens vazio"]}
500A IA não está disponível, ou falhou (generate, decide); Flow escolhido ainda sem meta_flow_id (decide com phone){"error":"whatsapp: provider de IA não configurado"}
401 / 403Sem token / sem ser root_admin com manage_whatsapp_platform{"error":"insufficient permissions"}
decide com phone envia mensagem de verdade

Para testar sem efeito colateral, omita phone. Com phone o cliente real recebe o Flow no WhatsApp.

Os Flows são avaliados pela loja do seu token

O decide usa os Flows publicados globais e os da loja do usuário que chama, não os de outra loja. Um Flow que só existe na loja A não aparece no teste feito com o token da loja B.

Sempre leia warnings antes de salvar

A IA não é determinística: o mesmo pedido pode gerar JSONs diferentes. Se warnings não for null, corrija o JSON antes de criar o Flow, ou a criação devolverá 422.

Veja também

  • Flows globais
  • Credenciais da plataforma
  • Visão geral do WhatsApp Platform
Anterior
Flows globais
Próxima
Mini-shop no storefront
Nesta página
  • Publicar na Meta
  • Pré-visualizar
  • Gerar um Flow a partir de uma descrição
  • Testar a escolha de Flow
  • Exemplo de requisição
  • Erros
  • Veja também