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

Pacotes de experiência

Catálogo de pacotes prontos de fluxos para cada tipo de loja, as habilidades do assistente e a instalação.

Montar um fluxo do zero é trabalhoso. Um pacote de experiência traz fluxos prontos para um tipo de loja. Estas rotas listam as habilidades disponíveis, os pacotes e instalam um pacote.

Habilidades do assistente

Lista as habilidades (ferramentas) que o assistente de WhatsApp desta loja pode usar, agrupadas em pacotes (packs). A lista já vem filtrada pelo que a loja tem ligado: módulos e configurações que faltam fazem a habilidade sumir. Serve para saber o que um pacote de experiência pode oferecer.

GET/api/v1/admin/whatsapp/capabilitiesAdmin

Lista as habilidades do assistente de WhatsApp

Exemplo de requisição (Listar habilidades)

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

Resposta (Listar habilidades)

200Habilidades devolvidas
json
{
  "packs": [
    "kb",
    "catalog",
    "cart",
    "orders",
    "b2b",
    "multi_vendor",
    "core"
  ],
  "tool_count": 20,
  "tools": [
    {
      "name": "send_text",
      "description": "Envia uma mensagem de texto curta ao cliente.",
      "pack": "core",
      "parameters": {
        "type": "object",
        "properties": {
          "text": {
            "type": "string",
            "description": "Corpo da mensagem em pt-BR"
          }
        },
        "additionalProperties": false
      }
    }
  ]
}

Campos da resposta

packsarray
Pacotes que têm ao menos uma habilidade disponível.
tool_countinteger
Quantas habilidades estão disponíveis.
toolsarray

As habilidades.

namestring
Nome estável da habilidade.
descriptionstring
O que ela faz, em português.
packstring
Pacote a que pertence.
parametersobject
Parâmetros que ela aceita, em JSON Schema.
customer_questionsarray
Tipos de pergunta de cliente que ela responde. Presente em algumas.
module_slugstring
Módulo exigido além do WhatsApp Commerce. Presente em algumas.
config_flagstring
Configuração que precisa estar ligada. Presente em algumas.
requires_aiboolean
true quando só existe com IA configurada.

Erros (Listar habilidades)

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"}
503Serviço indisponível.{"error":"service unavailable"}

Listar pacotes de experiência

Um pacote de experiência ("playbook") é um conjunto pronto de fluxos para um tipo de loja: varejo, atacado B2B, moda, marketplace. Em vez de montar o fluxo bloco a bloco, você instala um pacote e depois ajusta. Esta rota lista os pacotes do catálogo; a lista é a mesma para qualquer loja.

GET/api/v1/admin/whatsapp/playbooksAdmin

Lista os pacotes de experiência

Exemplo de requisição (Listar pacotes)

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

Resposta (Listar pacotes)

200Pacotes devolvidos
json
{
  "playbooks": [
    {
      "slug": "universal.retail",
      "name_pt": "Varejo B2C completo",
      "name_en": "Full B2C retail",
      "description_pt": "Loja de varejo com catálogo, carrinho, pedidos, base de conhecimento e busca por imagem.",
      "description_en": "Retail store with catalog, cart, orders, knowledge base and image search.",
      "packs": [
        "core",
        "catalog",
        "cart",
        "orders",
        "kb",
        "ai",
        "visual_search",
        "b2b"
      ],
      "suggested_tools": [
        "search_products",
        "show_cart",
        "start_checkout",
        "show_orders",
        "kb_search",
        "request_human",
        "opt_out"
      ],
      "flow_count": 1
    }
  ]
}

Campos da resposta

playbooksarray

Pacotes do catálogo.

slugstring
Identificador estável do pacote, usado nas outras rotas.
name_ptstring
Nome em português.
name_enstring
Nome em inglês.
description_ptstring
Descrição em português, com o que o pacote inclui e o que acontece ao ativar.
description_enstring
Descrição em inglês.
packsarray
Grupos de habilidades do assistente que o pacote usa.
suggested_toolsarray
Habilidades sugeridas, por nome (veja /capabilities).
flow_countinteger
Quantos fluxos o pacote instala.

Erros (Listar pacotes)

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 o catálogo.{"error":"..."}
Pacotes disponíveis

universal.b2b (B2B completo), universal.marketplace (marketplace multi-vendedor) e universal.retail (varejo B2C completo).

Ver um pacote

Devolve o pacote completo, inclusive o desenho de cada fluxo (blocos e ligações), para você conferir o que será instalado.

GET/api/v1/admin/whatsapp/playbooks/{slug}Admin

Lê um pacote de experiência com seus fluxos

Parâmetros de caminho

slugstringobrigatório
Identificador do pacote, por exemplo universal.retail.

Exemplo de requisição (Ver um pacote)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/playbooks/universal.retail" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ver um pacote)

200Pacote devolvido
json
{
  "slug": "universal.retail",
  "name_pt": "Varejo B2C completo",
  "name_en": "Full B2C retail",
  "description_pt": "Loja de varejo com catálogo, carrinho, pedidos, base de conhecimento e busca por imagem.",
  "description_en": "Retail store with catalog, cart, orders, knowledge base and image search.",
  "packs": [
    "core",
    "catalog",
    "cart",
    "orders",
    "kb",
    "ai",
    "visual_search",
    "b2b"
  ],
  "suggested_tools": [
    "search_products",
    "show_cart",
    "start_checkout",
    "show_orders",
    "kb_search",
    "request_human",
    "opt_out"
  ],
  "flow_count": 1,
  "flows": [
    {
      "name": "Welcome",
      "description": "Inbound default for B2C retail",
      "trigger_type": "inbound_default",
      "status": "active",
      "trigger_priority": 0,
      "start_block_key": "welcome",
      "blocks": [
        {
          "key": "welcome",
          "type": "message",
          "name": "Boas-vindas",
          "config": {
            "text": "Oi! Bem-vindo à {{vendor_name}}."
          },
          "x": 80,
          "y": 40
        }
      ],
      "connections": [
        {
          "from": "welcome",
          "to": "menu",
          "type": "next"
        }
      ]
    }
  ]
}

Campos da resposta

slugstring
Identificador estável do pacote, usado nas outras rotas.
name_ptstring
Nome em português.
name_enstring
Nome em inglês.
description_ptstring
Descrição em português, com o que o pacote inclui e o que acontece ao ativar.
description_enstring
Descrição em inglês.
packsarray
Grupos de habilidades do assistente que o pacote usa.
suggested_toolsarray
Habilidades sugeridas, por nome (veja /capabilities).
flowsarray

Fluxos que o pacote instala.

namestring
Nome do fluxo.
descriptionstring
Descrição do fluxo.
trigger_typestring
Gatilho.
statusstring
Estado ao instalar.
trigger_priorityinteger
Prioridade do gatilho.
start_block_keystring
key do bloco inicial.
blocksarray
Blocos: key, type, name, config, x, y.
connectionsarray
Ligações entre blocos, pela key: from, to, type.

Erros (Ver um pacote)

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"}
404Pacote não existe.{"error":"playbook not found"}

Instalar um pacote

Cria no banco da loja os fluxos do pacote, com blocos e ligações, já ativos. Sem vendor_id os fluxos são da loja toda; com vendor_id, só daquele seller. Por padrão, desativa antes o fluxo inbound_default que estiver ativo no mesmo escopo, para o novo pacote assumir o atendimento.

POST/api/v1/admin/whatsapp/playbooks/{slug}/installAdmin

Instala um pacote de experiência

Parâmetros de caminho

slugstringobrigatório
Identificador do pacote.

Corpo da requisição

vendor_iduuid
Seller que receberá os fluxos. Omitido, os fluxos são da loja toda.
replace_defaultbooleanpadrão: true
true desativa antes o fluxo inbound_default ativo do mesmo escopo (do seller, ou os da loja sem seller). false instala sem desativar.

Exemplo de requisição (Instalar um pacote)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/playbooks/universal.retail/install" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_id": "9d9d9d56-eb43-4719-889d-055632f7c7da",
    "replace_default": true
  }'

Resposta (Instalar um pacote)

200Pacote instalado
json
{
  "slug": "universal.retail",
  "flow_ids": [
    "d4e5f6a7-1b2c-4d3e-8f90-a1b2c3d4e5f6"
  ],
  "replaced_inbound_defaults": 1
}

Campos da resposta

slugstring
O pacote instalado.
flow_idsarray
Ids dos fluxos criados.
replaced_inbound_defaultsinteger
Quantos fluxos inbound_default foram desativados. Ausente quando zero.

Erros (Instalar um pacote)

StatusQuandoCorpo
400Pacote inexistente, módulo desligado, corpo com tipo errado (por exemplo replace_default como texto) ou falha ao criar.{"error":"whatsapp: playbook \"x\" not found"} ou {"error":"invalid request body: ..."}
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"}
Não é idempotente

Instalar duas vezes o mesmo pacote cria dois conjuntos de fluxos. Antes de instalar, liste os fluxos (GET /flows) e apague ou desative duplicatas.

Corpo opcional

Você pode chamar sem corpo: instala para a loja toda, substituindo o fluxo padrão ativo.

Veja também

  • Ler fluxos
  • Pedidos de mudança
Anterior
Pedidos de mudança
Próxima
WhatsApp: Flows da Meta
Nesta página
  • Habilidades do assistente
  • Exemplo de requisição (Listar habilidades)
  • Resposta (Listar habilidades)
  • Erros (Listar habilidades)
  • Listar pacotes de experiência
  • Exemplo de requisição (Listar pacotes)
  • Resposta (Listar pacotes)
  • Erros (Listar pacotes)
  • Ver um pacote
  • Exemplo de requisição (Ver um pacote)
  • Resposta (Ver um pacote)
  • Erros (Ver um pacote)
  • Instalar um pacote
  • Exemplo de requisição (Instalar um pacote)
  • Resposta (Instalar um pacote)
  • Erros (Instalar um pacote)
  • Veja também