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

Publicar e enviar

Publica um Flow na Meta, gera o link de pré-visualização e envia o Flow a um cliente.

Um Flow só existe para clientes depois de publicado na Meta. Estas rotas fazem esse caminho: publicar, conferir a aparência e enviar. Todas falam com a API da Meta.

Publicar na Meta

Cria o Flow na conta da Meta (se ainda não existir), envia o flow_json e publica. Ao terminar, grava o meta_flow_id e muda o estado para published. Só depois disso o Flow pode ser enviado a clientes sem o modo rascunho.

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

Publica um Flow na Meta

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

Exemplo de requisição (Publicar na Meta)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/meta-flows/2/publish" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Publicar na Meta)

200Flow publicado
json
{
  "id": 2,
  "flow_key": "contato-rapido",
  "name": "Contato rápido",
  "scope": "store",
  "ai_when_to_use": "Quando o cliente pedir para ser chamado de volta.",
  "ai_params": {},
  "status": "published",
  "version": 1,
  "meta_flow_id": "1774424140505972",
  "category": "CONTACT_US",
  "created_at": "2026-10-11T23:55:12.229890Z",
  "updated_at": "2026-10-11T23:55:12.229890Z"
}

Campos da resposta

idinteger
Identificador numérico do Flow na loja. Não é UUID.
flow_keystring
Chave única e estável do Flow na loja (até 120 caracteres). Não muda depois de criado.
namestring
Nome mostrado no painel e usado como nome do Flow na Meta.
scopestring
storeglobal
Onde o Flow vive. Nestas rotas é sempre store.
flow_jsonobject
O desenho das telas, no formato JSON de Flows da Meta.
ai_when_to_usestring
Texto que explica ao assistente quando enviar este Flow.
ai_paramsobject
Objeto JSON livre guardado junto ao Flow. {} quando vazio.
statusstring
draftpublished
draft até ser publicado na Meta; published depois.
versioninteger
Começa em 1 e sobe a cada PUT.
meta_flow_idstring
Id do Flow na Meta, preenchido na publicação. Texto vazio antes disso.
categorystring
SIGN_UPSIGN_INAPPOINTMENT_BOOKINGLEAD_GENERATIONCONTACT_USCUSTOMER_SUPPORTSURVEYOTHER
Categoria na Meta.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Publicar na Meta)

StatusQuandoCorpo
400O id não é um número.{"error":"Invalid id"}
400Flow inexistente, credenciais da Meta da plataforma ausentes, ou recusa da Meta (a mensagem traz o motivo).{"error":"whatsapp: credenciais da plataforma (token + WABA) não configuradas"} ou {"error":"whatsapp: publicar flow: ..."}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
422O flow_json não passa na validação. A lista errors diz o que corrigir.{"error":"Flow JSON inválido","errors":["version ausente","screens vazio"]}
Ação real na conta da Meta

Esta rota fala com a API da Meta e cria um Flow de verdade. Um Flow publicado não pode ser apagado pela API da Meta, só desativado no Business Manager. Use contas de teste ao experimentar.

Credenciais da plataforma

A publicação usa o token e a conta empresarial (WABA) compartilhados da plataforma, não as credenciais do número da loja. Se eles não estiverem configurados, a resposta é 400.

Pré-visualizar

Pede à Meta um link de pré-visualização do Flow, que abre sem login e vale por cerca de 30 dias. O Flow precisa já existir na Meta, ou seja, ter sido publicado ao menos uma vez.

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

Gera o link de pré-visualização de um Flow

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

Exemplo de requisição (Pré-visualizar)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/meta-flows/2/preview" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Pré-visualizar)

200Link gerado
json
{
  "preview_url": "https://business.facebook.com/wa/manage/flows/1774424140505972/preview/?token=..."
}

Campos da resposta

preview_urlstring
Link de pré-visualização da Meta.

Erros (Pré-visualizar)

StatusQuandoCorpo
400O id não é um número.{"error":"Invalid id"}
400Flow inexistente, ainda não publicado, ou falha na Meta.{"error":"whatsapp: publique o flow na Meta antes de pré-visualizar"} ou {"error":"sql: no rows in result set"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}

Enviar a um cliente

Manda o Flow como mensagem interativa para um telefone. O cliente vê um botão que abre as telas do Flow dentro do WhatsApp.

POST/api/v1/admin/whatsapp/meta-flows/{id}/sendAdmin

Envia um Flow a um telefone

Parâmetros de caminho

idintegerobrigatório
Id numérico do Flow.

Corpo da requisição

phonestringobrigatório
Telefone do cliente, com DDI e DDD (por exemplo 5511999990000). Obrigatório.
ctastring
Texto do botão. Omitido, Abrir.
bodystring
Texto da mensagem. Omitido, Toque para continuar.
screenstring
Id da tela em que abrir (ver screens[].id do flow_json). Só vale junto com data.
dataobject
Dados iniciais da tela. Com screen e data, o Flow abre direto nessa tela.
flow_idstring
Id de um Flow da Meta para enviar no lugar do deste registro. Permite testar um Flow antes de publicá-lo pelo painel.

Exemplo de requisição (Enviar a um cliente)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/meta-flows/2/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999990000",
    "cta": "Abrir",
    "body": "Preencha seus dados"
  }'

Resposta (Enviar a um cliente)

200Mensagem enviada
json
{
  "success": true,
  "message_id": "wamid.HBgMNTUxMTk5OTk5MDAwMBUCABEYEjQ5RjY1RTQ3OUVBNDM4MDM4AA=="
}

Campos da resposta

successboolean
Sempre true em sucesso.
message_idstring
Id da mensagem no WhatsApp (wamid...).

Erros (Enviar a um cliente)

StatusQuandoCorpo
400O id não é um número.{"error":"Invalid id"}
400Corpo que não é JSON, ou phone ausente.{"error":"phone é obrigatório"}
401Sem token, token inválido ou expirado.{"error":"missing authorization header"}
403O módulo WhatsApp Commerce está desligado na loja, o usuário não é administrador ou não tem o privilégio exigido.{"error":"module_disabled","module":"whatsapp-commerce"} ou {"error":"insufficient privileges","required":"manage_settings"} ou {"error":"admin access required"}
404Flow não encontrado.{"error":"flow não encontrado"}
422O Flow ainda não foi publicado e você não enviou flow_id.{"error":"flow ainda não publicado na Meta (sem meta_flow_id)"}
500O WhatsApp da loja não está configurado, o módulo está desligado, ou a Meta recusou o envio.{"error":"whatsapp: API token or phone number ID not configured"}
Janela de 24 horas

O WhatsApp só entrega mensagens interativas livres dentro de 24 horas depois da última mensagem do cliente. Fora da janela, a Meta recusa e a resposta é 500 com o motivo.

Envia de verdade

A mensagem sai para o telefone informado e fica registrada na conversa. Teste com o seu próprio número.

Veja também

  • Flows da loja
  • IA para Flows
Anterior
Flows da loja
Próxima
IA para Flows
Nesta página
  • Publicar na Meta
  • Exemplo de requisição (Publicar na Meta)
  • Resposta (Publicar na Meta)
  • Erros (Publicar na Meta)
  • Pré-visualizar
  • Exemplo de requisição (Pré-visualizar)
  • Resposta (Pré-visualizar)
  • Erros (Pré-visualizar)
  • Enviar a um cliente
  • Exemplo de requisição (Enviar a um cliente)
  • Resposta (Enviar a um cliente)
  • Erros (Enviar a um cliente)
  • Veja também