API atual/Referência completa/WhatsApp Commerce: fluxos e experiência

Modelos prontos

Lista os fluxos de conversa já desenhados e instala um deles para o seller, trocando o fluxo de boas-vindas atual.

Um modelo pronto (playbook) é um fluxo completo, com blocos e conexões, para um tipo de operação: varejo para consumidor final, atacado entre empresas, marketplace com vários vendedores. Instalar um modelo é o jeito mais rápido de o seller ter um fluxo próprio e editável, que depois ele ajusta com blocos e textos.

Listar os modelos

GET/api/v1/vendor/whatsapp/playbooksSeller

Lista os modelos prontos e qual está em uso

Devolve o catálogo inteiro (o mesmo para todo seller) e, junto, o fluxo que o seller usa hoje. O modelo em uso é deduzido pelo nome do fluxo ativo, então um fluxo renomeado deixa de ser reconhecido e active_slug volta vazio.

Exemplo de requisição

bash

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

Resposta

200Catálogo e estado do seller

json

{
  "playbooks": [
    {
      "slug": "universal.retail",
      "name_pt": "Varejo B2C - completo",
      "name_en": "Retail B2C - full",
      "description_pt": "Boas-vindas, menu, catálogo, carrinho, pedidos, atendente e IA.",
      "description_en": "Welcome, menu, catalog, cart, orders, human agent and AI.",
      "packs": ["core", "catalog", "cart", "orders", "kb", "ai"],
      "suggested_tools": [],
      "flow_count": 1
    }
  ],
  "active_flow": {
    "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
    "flow_name": "Welcome Retail",
    "owned": true
  },
  "active_slug": "universal.retail",
  "active_packs": ["core", "catalog", "cart", "orders", "kb", "ai"],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
}

Campos da resposta

playbooksarray

Catálogo de modelos.

playbooks[].slugstring

Identificador do modelo. Use na instalação. Os modelos genéricos são universal.retail (varejo), universal.b2b (atacado) e universal.marketplace (vários vendedores); o catálogo pode trazer também modelos específicos de lojas.

playbooks[].name_ptstring

Nome em português.

playbooks[].name_enstring

Nome em inglês.

playbooks[].description_ptstring

Descrição em português.

playbooks[].description_enstring

Descrição em inglês.

playbooks[].packsarray

Funcionalidades que o modelo usa (veja Funcionalidades).

playbooks[].suggested_toolsarray

Ferramentas sugeridas do assistente. Pode estar vazio.

playbooks[].flow_countinteger

Quantos fluxos o modelo cria.

active_flowobject

Fluxo ativo do seller, ou null se não há. Campos: flow_id, flow_name e owned (true se é do seller).

active_slugstring

Modelo reconhecido no fluxo ativo. Vazio se nenhum combina.

active_packsarray

Funcionalidades do modelo reconhecido.

vendor_iduuid

Seller.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; sem privilégio	veja Fluxo
404	Usuário sem cadastro de seller	`{"error":"vendor profile not found","code":"vendor_profile_not_found"}`
500	Falha ao ler o catálogo	`{"error":"..."}`

Instalar um modelo

POST/api/v1/vendor/whatsapp/playbooks/{slug}/installSeller

Cria os fluxos do modelo para o seller

Cria, para o seller, os fluxos do modelo (blocos e conexões incluídos), já ativos. Por padrão desativa antes os fluxos de boas-vindas (inbound_default) do próprio seller, para o novo assumir; os fluxos da loja e de outros sellers não são tocados. Devolve também os textos editáveis do novo fluxo, prontos para o seller personalizar.

Parâmetros de caminho

slugstringobrigatório

Identificador do modelo (playbooks[].slug).

Corpo da requisição

replace_defaultbooleanpadrão: true

true desativa os fluxos de boas-vindas atuais do seller antes de instalar. Com false, os antigos continuam ativos junto com os novos. O corpo é opcional; um valor que não seja booleano é recusado.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/playbooks/universal.retail/install" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "replace_default": true
}'

Resposta

200Modelo instalado

json

{
  "install": {
    "slug": "universal.retail",
    "flow_ids": ["6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f"],
    "replaced_inbound_defaults": 1
  },
  "copy": {
    "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
    "flow_name": "Welcome Retail",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "fields": []
  }
}

Campos da resposta

install.slugstring

Modelo instalado.

install.flow_idsarray

Ids dos fluxos criados.

install.replaced_inbound_defaultsinteger

Quantos fluxos de boas-vindas foram desativados. Ausente quando zero.

copyobject

Textos editáveis do fluxo ativo do seller, no formato de Ler os textos editáveis. Pode vir ausente se a leitura falhar, sem afetar a instalação.

Erros

Status	Quando	Corpo
400	Corpo com JSON inválido	`{"error":"invalid request body: ..."}`
400	Modelo inexistente	`{"error":"whatsapp: playbook \"x\" not found"}`
400	Módulo desligado	`{"error":"whatsapp: module disabled"}`
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo

Veja também

Modelos prontos

Lista os fluxos de conversa já desenhados e instala um deles para o seller, trocando o fluxo de boas-vindas atual.

Listar os modelos

GET/api/v1/vendor/whatsapp/playbooksSeller

Lista os modelos prontos e qual está em uso

Exemplo de requisição

bash

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

Resposta

200Catálogo e estado do seller

json

{
  "playbooks": [
    {
      "slug": "universal.retail",
      "name_pt": "Varejo B2C - completo",
      "name_en": "Retail B2C - full",
      "description_pt": "Boas-vindas, menu, catálogo, carrinho, pedidos, atendente e IA.",
      "description_en": "Welcome, menu, catalog, cart, orders, human agent and AI.",
      "packs": ["core", "catalog", "cart", "orders", "kb", "ai"],
      "suggested_tools": [],
      "flow_count": 1
    }
  ],
  "active_flow": {
    "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
    "flow_name": "Welcome Retail",
    "owned": true
  },
  "active_slug": "universal.retail",
  "active_packs": ["core", "catalog", "cart", "orders", "kb", "ai"],
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36"
}

Campos da resposta

playbooksarray

Catálogo de modelos.

playbooks[].slugstring

playbooks[].name_ptstring

Nome em português.

playbooks[].name_enstring

Nome em inglês.

playbooks[].description_ptstring

Descrição em português.

playbooks[].description_enstring

Descrição em inglês.

playbooks[].packsarray

Funcionalidades que o modelo usa (veja Funcionalidades).

playbooks[].suggested_toolsarray

Ferramentas sugeridas do assistente. Pode estar vazio.

playbooks[].flow_countinteger

Quantos fluxos o modelo cria.

active_flowobject

Fluxo ativo do seller, ou null se não há. Campos: flow_id, flow_name e owned (true se é do seller).

active_slugstring

Modelo reconhecido no fluxo ativo. Vazio se nenhum combina.

active_packsarray

Funcionalidades do modelo reconhecido.

vendor_iduuid

Seller.

Erros

Status	Quando	Corpo
401	Sem token	`{"error":"authentication required"}`
403	Token que não é de seller; módulo desligado; sem privilégio	veja Fluxo
404	Usuário sem cadastro de seller	`{"error":"vendor profile not found","code":"vendor_profile_not_found"}`
500	Falha ao ler o catálogo	`{"error":"..."}`

Instalar um modelo

POST/api/v1/vendor/whatsapp/playbooks/{slug}/installSeller

Cria os fluxos do modelo para o seller

Parâmetros de caminho

slugstringobrigatório

Identificador do modelo (playbooks[].slug).

Corpo da requisição

replace_defaultbooleanpadrão: true

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/playbooks/universal.retail/install" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "replace_default": true
}'

Resposta

200Modelo instalado

json

{
  "install": {
    "slug": "universal.retail",
    "flow_ids": ["6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f"],
    "replaced_inbound_defaults": 1
  },
  "copy": {
    "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
    "flow_name": "Welcome Retail",
    "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
    "fields": []
  }
}

Campos da resposta

install.slugstring

Modelo instalado.

install.flow_idsarray

Ids dos fluxos criados.

install.replaced_inbound_defaultsinteger

Quantos fluxos de boas-vindas foram desativados. Ausente quando zero.

copyobject

Textos editáveis do fluxo ativo do seller, no formato de Ler os textos editáveis. Pode vir ausente se a leitura falhar, sem afetar a instalação.

Erros

Status	Quando	Corpo
400	Corpo com JSON inválido	`{"error":"invalid request body: ..."}`
400	Modelo inexistente	`{"error":"whatsapp: playbook \"x\" not found"}`
400	Módulo desligado	`{"error":"whatsapp: module disabled"}`
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo