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

Flows nativos

Liga e desliga os Flows prontos da plataforma na loja, consulta a situação e envia um deles a um cliente.

Além dos Flows que você desenha, a plataforma traz um pacote de Flows prontos (catálogo, produto, busca, carrinho, checkout, login, cadastro, pedidos, perfil). Ligar esse pacote faz o cliente comprar dentro do WhatsApp, sem abrir o site.

Ver a situação

Mostra se os Flows nativos estão ligados, o que ainda falta (blockers) e a situação de cada Flow. É a rota que você consulta depois de ativar, até activating voltar a false.

GET/api/v1/admin/whatsapp/native-flows/statusAdmin

Mostra a situação dos Flows nativos da loja

Exemplo de requisição (Ver a situação)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/native-flows/status" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ver a situação)

200Situação
json
{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "109876543210987",
  "waba_id": "123456789012345",
  "encryption_matches": false,
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=109876543210987",
  "web_preview_disabled": false,
  "blockers": [
    "Chave RSA de Flow ainda não gerada nesta loja."
  ],
  "flows": [
    {
      "key": "catalog",
      "name": "STORE1_UNIFIED_CATALOG_FLOW_V21",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "product",
      "name": "STORE1_STANDALONE_PRODUCT_DETAIL_FLOW_V7",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "search",
      "name": "STORE1_PRODUCT_SEARCH_CATALOG_FLOW_V2",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "...",
      "name": "...",
      "meta_flow_id": "",
      "status": "",
      "published": false
    }
  ],
  "activating": false
}

Campos da resposta

enabledboolean
true quando os Flows nativos estão ligados na loja.
number_registeredboolean
true quando há número de WhatsApp e token cadastrados.
phone_number_idstring
Id do número na Meta.
waba_idstring
Id da conta WhatsApp Business. Ausente quando não conhecida.
encryption_matchesboolean
true quando a chave pública daqui é igual à registrada na Meta.
local_public_keystring
Chave pública local (PEM). Ausente se não existe.
meta_public_keystring
Chave pública lida na Meta. Ausente se não foi possível ler.
endpoint_uristring
URL pública que a Meta chama para trocar dados com os Flows. Vazia se a loja não tem URL pública.
web_preview_disabledboolean
true enquanto os Flows nativos estão ligados: a mini-loja por link fica desligada.
blockersarray
Motivos, em português, pelos quais a ativação não está completa. Lista vazia quando está tudo certo.
flowsarray

Os Flows prontos da plataforma e a situação de cada um na loja.

keystring
catalogproductsearchpizzamulticartcheckoutloginregisterordersprofile
Chave do Flow.
namestring
Nome do Flow na conta da Meta.
meta_flow_idstring
Id na Meta. Vazio se ainda não foi criado.
statusstring
Estado do registro (published quando no ar).
publishedboolean
true quando está publicado na Meta.
activatingboolean
true enquanto a ativação roda em segundo plano.
activation_errorstring
Último erro da ativação. Ausente se não houve.

Erros (Ver a situação)

StatusQuandoCorpo
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"}
500Falha ao ler a situação.{"error":"..."}
O que são os Flows nativos

São telas prontas da plataforma dentro do WhatsApp (catálogo, produto, busca, carrinho, checkout, login, cadastro, pedidos, perfil e outras). Ao ligá-los, a plataforma cria cópias deles na conta da Meta da loja. Ficam diferentes dos Flows que você desenha em /meta-flows.

Ativar

Liga os Flows nativos: cria as cópias na conta da Meta, registra a chave de criptografia e, só no fim, marca a loja como ativa. Como leva de dezenas de segundos a alguns minutos, a rota responde logo e o trabalho segue em segundo plano. Acompanhe com GET /native-flows/status.

POST/api/v1/admin/whatsapp/native-flows/activateAdmin

Liga os Flows nativos da loja

Exemplo de requisição (Ativar)

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

Resposta (Ativar)

200Ativação iniciada
json
{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "109876543210987",
  "waba_id": "123456789012345",
  "encryption_matches": false,
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=109876543210987",
  "web_preview_disabled": false,
  "blockers": [
    "Chave RSA de Flow ainda não gerada nesta loja."
  ],
  "flows": [
    {
      "key": "catalog",
      "name": "STORE1_UNIFIED_CATALOG_FLOW_V21",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "product",
      "name": "STORE1_STANDALONE_PRODUCT_DETAIL_FLOW_V7",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "search",
      "name": "STORE1_PRODUCT_SEARCH_CATALOG_FLOW_V2",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "...",
      "name": "...",
      "meta_flow_id": "",
      "status": "",
      "published": false
    }
  ],
  "activating": true
}

Campos da resposta

enabledboolean
true quando os Flows nativos estão ligados na loja.
number_registeredboolean
true quando há número de WhatsApp e token cadastrados.
phone_number_idstring
Id do número na Meta.
waba_idstring
Id da conta WhatsApp Business. Ausente quando não conhecida.
encryption_matchesboolean
true quando a chave pública daqui é igual à registrada na Meta.
local_public_keystring
Chave pública local (PEM). Ausente se não existe.
meta_public_keystring
Chave pública lida na Meta. Ausente se não foi possível ler.
endpoint_uristring
URL pública que a Meta chama para trocar dados com os Flows. Vazia se a loja não tem URL pública.
web_preview_disabledboolean
true enquanto os Flows nativos estão ligados: a mini-loja por link fica desligada.
blockersarray
Motivos, em português, pelos quais a ativação não está completa. Lista vazia quando está tudo certo.
flowsarray

Os Flows prontos da plataforma e a situação de cada um na loja.

keystring
catalogproductsearchpizzamulticartcheckoutloginregisterordersprofile
Chave do Flow.
namestring
Nome do Flow na conta da Meta.
meta_flow_idstring
Id na Meta. Vazio se ainda não foi criado.
statusstring
Estado do registro (published quando no ar).
publishedboolean
true quando está publicado na Meta.
activatingboolean
true enquanto a ativação roda em segundo plano.
activation_errorstring
Último erro da ativação. Ausente se não houve.

Erros (Ativar)

StatusQuandoCorpo
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"}
422Falta algo antes de ativar, ou a ativação anterior ainda está terminando.{"error":"cadastre o número do WhatsApp (phone_number_id + token) antes de ligar o Flow"} ou {"error":"URL pública da loja ausente para o data exchange"}
Desliga a mini-loja por link

Com os Flows nativos ligados, a mini-loja aberta por link (web_preview) fica desligada (web_preview_disabled: true). POST /native-flows/deactivate religa a mini-loja.

Ação real na conta da Meta

A ativação cria Flows de verdade na conta da Meta e troca a chave de criptografia do número. Se a ativação falhar no meio, a loja continua desligada e activation_error explica; chamar de novo é seguro.

Desativar

Desliga os Flows nativos e religa a mini-loja por link. Cancela uma ativação em andamento. Os Flows já criados na Meta continuam lá.

POST/api/v1/admin/whatsapp/native-flows/deactivateAdmin

Desliga os Flows nativos da loja

Exemplo de requisição (Desativar)

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

Resposta (Desativar)

200Desativado
json
{
  "enabled": false,
  "number_registered": true,
  "phone_number_id": "109876543210987",
  "waba_id": "123456789012345",
  "encryption_matches": false,
  "endpoint_uri": "https://minhaloja.io.venddor.com.br/api/v1/webhooks/whatsapp/minhaloja/flow?phone_number_id=109876543210987",
  "web_preview_disabled": false,
  "blockers": [
    "Chave RSA de Flow ainda não gerada nesta loja."
  ],
  "flows": [
    {
      "key": "catalog",
      "name": "STORE1_UNIFIED_CATALOG_FLOW_V21",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "product",
      "name": "STORE1_STANDALONE_PRODUCT_DETAIL_FLOW_V7",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "search",
      "name": "STORE1_PRODUCT_SEARCH_CATALOG_FLOW_V2",
      "meta_flow_id": "",
      "status": "",
      "published": false
    },
    {
      "key": "...",
      "name": "...",
      "meta_flow_id": "",
      "status": "",
      "published": false
    }
  ],
  "activating": false
}

Campos da resposta

enabledboolean
true quando os Flows nativos estão ligados na loja.
number_registeredboolean
true quando há número de WhatsApp e token cadastrados.
phone_number_idstring
Id do número na Meta.
waba_idstring
Id da conta WhatsApp Business. Ausente quando não conhecida.
encryption_matchesboolean
true quando a chave pública daqui é igual à registrada na Meta.
local_public_keystring
Chave pública local (PEM). Ausente se não existe.
meta_public_keystring
Chave pública lida na Meta. Ausente se não foi possível ler.
endpoint_uristring
URL pública que a Meta chama para trocar dados com os Flows. Vazia se a loja não tem URL pública.
web_preview_disabledboolean
true enquanto os Flows nativos estão ligados: a mini-loja por link fica desligada.
blockersarray
Motivos, em português, pelos quais a ativação não está completa. Lista vazia quando está tudo certo.
flowsarray

Os Flows prontos da plataforma e a situação de cada um na loja.

keystring
catalogproductsearchpizzamulticartcheckoutloginregisterordersprofile
Chave do Flow.
namestring
Nome do Flow na conta da Meta.
meta_flow_idstring
Id na Meta. Vazio se ainda não foi criado.
statusstring
Estado do registro (published quando no ar).
publishedboolean
true quando está publicado na Meta.
activatingboolean
true enquanto a ativação roda em segundo plano.
activation_errorstring
Último erro da ativação. Ausente se não houve.

Erros (Desativar)

StatusQuandoCorpo
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"}
500Falha ao gravar a configuração.{"error":"..."}

Enviar um Flow nativo

Manda um dos Flows nativos para um cliente, já na tela certa. Serve para disparar uma ação (por exemplo abrir o carrinho) a partir do seu sistema.

POST/api/v1/admin/whatsapp/native-flows/sendAdmin

Envia um Flow nativo a um telefone

Corpo da requisição

phonestringobrigatório
Telefone do cliente com DDI e DDD. Obrigatório.
keystring
catalogproductsearchpizzamulticartcheckoutloginregisterordersprofile
Qual Flow nativo enviar. Tem prioridade sobre tool.
toolstring
Alternativa a key, um apelido: cart/sacola, checkout/pagamento, login, register/cadastro, orders/pedidos, product/produto, search/busca, pizza, profile/conta/ajuda. Qualquer outro valor (ou nenhum) abre o catálogo.
ctastring
Texto do botão, até 20 caracteres. Omitido, Ver.
bodystring
Texto da mensagem. Omitido, Toque no botão abaixo.
screenstring
Tela em que abrir. Omitido, a tela inicial do Flow.
dataobject
Dados iniciais da tela (por exemplo product_id ou query).

Exemplo de requisição (Enviar um Flow nativo)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/native-flows/send" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "5511999990000",
    "key": "search",
    "body": "Procure o que precisa",
    "data": {
      "query": "camisa"
    }
  }'

Resposta (Enviar um Flow nativo)

200Flow enviado
json
{
  "success": true,
  "message_id": "wamid.HBgMNTUxMTk5OTk5MDAwMBUCABEYEjQ5RjY1RTQ3OUVBNDM4MDM4AA==",
  "key": "search"
}

Campos da resposta

successboolean
Sempre true em sucesso.
message_idstring
Id da mensagem no WhatsApp.
keystring
O Flow nativo enviado.

Erros (Enviar um Flow nativo)

StatusQuandoCorpo
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"}
422Flow desconhecido, ainda não publicado (ative primeiro), ou envio recusado.{"error":"whatsapp: flow nativo desconhecido x"} ou {"error":"whatsapp: flow catalog ainda não publicado na Meta ..."}
Envia de verdade

A mensagem sai para o telefone informado. A regra das 24 horas do WhatsApp vale: fora da janela a Meta recusa.

Preços para visitantes

Se o cliente ainda não fez login e a loja esconde preços de visitantes, os valores monetários são retirados dos dados antes do envio.

Veja também

  • Chaves de Flow
  • Visão geral
Anterior
IA para Flows
Próxima
Chaves de Flow
Nesta página
  • Ver a situação
  • Exemplo de requisição (Ver a situação)
  • Resposta (Ver a situação)
  • Erros (Ver a situação)
  • Ativar
  • Exemplo de requisição (Ativar)
  • Resposta (Ativar)
  • Erros (Ativar)
  • Desativar
  • Exemplo de requisição (Desativar)
  • Resposta (Desativar)
  • Erros (Desativar)
  • Enviar um Flow nativo
  • Exemplo de requisição (Enviar um Flow nativo)
  • Resposta (Enviar um Flow nativo)
  • Erros (Enviar um Flow nativo)
  • Veja também