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

Fluxos e experiência do WhatsApp

Como o seller desenha a conversa automática do WhatsApp (fluxo, blocos e conexões), troca os textos e escolhe as funcionalidades.

Quando um cliente escreve para o número da loja, o que ele vê primeiro (saudação, menu, catálogo, carrinho) vem de um fluxo: um mapa de conversa montado com blocos ligados por conexões. Esta seção documenta as rotas que o seller usa para ler e editar o fluxo, trocar só os textos, instalar um modelo pronto, ligar ou desligar funcionalidades e ativar os fluxos nativos da Meta.

Vocabulário rápido:

  • Fluxo (flow): o mapa completo de uma conversa automática. Cada seller tem o seu.
  • Bloco (block): um passo do mapa. Pode enviar uma mensagem, mostrar um menu, buscar produtos, pedir um dado, passar para um atendente...
  • Conexão (connection): a seta que leva de um bloco ao próximo. Num menu, cada opção tem a sua conexão.
  • Modelo pronto (playbook): um fluxo completo já desenhado (varejo, atacado, marketplace) que o seller instala com uma chamada.
  • Funcionalidade (capability): um interruptor de recurso do atendimento (base de conhecimento, busca por foto, atacado...).
  • Fluxo nativo da Meta: formulários do próprio WhatsApp, que abrem dentro da conversa em vez de levar o cliente a um site.
Pontos-chave
  • Todas as rotas são de usuário seller (/api/v1/vendor/whatsapp/...), com o módulo whatsapp-commerce ligado e, na maioria, o privilégio vendor_manage_whatsapp.
  • O seller só edita fluxos dele. Um fluxo da loja (sem seller) é só leitura aqui; para ter um fluxo editável, instale um modelo pronto.
  • Mudar o desenho (blocos e conexões) é livre. Mudar só os textos é mais seguro e tem rotas próprias. Pedir a uma pessoa da plataforma para alterar a estrutura é outro caminho (flow-requests).
  • As rotas de blocos e conexões não validam o desenho ao gravar. Rode validate depois de editar.
  • Os fluxos nativos da Meta valem para a loja inteira, não só para o seller que os liga.

Como funciona

O caminho de um cliente pelo fluxo

Cliente escreve→Gatilho do fluxo→Blocos em sequência→Fim ou atendente

O gatilho do fluxo decide quando ele entra em ação:

trigger_typeQuando dispara
manualSó quando alguém o executa à mão (teste). É o padrão de um fluxo novo.
keywordQuando a mensagem do cliente combina com uma das palavras-chave (trigger_keywords), segundo trigger_match_mode.
inbound_defaultQuando nenhum fluxo de palavra-chave combinou e o cliente não está no meio de outro. É o fluxo de "boas-vindas".

Se vários fluxos combinam, vence o de maior trigger_priority.

O fluxo típico de uma integração

  1. Ver o fluxo atual

    GET /flows/active devolve o fluxo ativo do seller. Se ele ainda não tem um próprio, a plataforma cria uma cópia editável do fluxo de boas-vindas da loja.

  2. Escolher um ponto de partida

    Instale um modelo pronto ou parta do fluxo existente.

  3. Editar textos ou estrutura

    Só textos, ou blocos e conexões.

  4. Validar e ativar

    GET /flows/{id}/validate aponta blocos soltos e setas quebradas. Depois, PATCH com status: "active".

Conceitos-chave

Estados de um fluxo

statusSignificado
draftRascunho, não atende clientes.
activeEm uso.
inactiveDesligado.
archivedArquivado.

O campo status da resposta pode vir como a palavra (active) ou como uma letra (A ativo, P inativo, R rascunho, H arquivado), conforme o banco da loja. Aceite os dois formatos ao ler. Ao gravar, envie a palavra (active).

Ids e dinheiro

Todos os ids desta seção são UUID em string. Posições dos blocos (position_x, position_y) são inteiros em pixels do editor visual. Não há valores monetários.

Quem pode editar o quê

RecursoSellerObservação
Fluxo, blocos, conexões do próprio sellerLê e editaFluxo de outro seller ou da loja: 404.
Textos do fluxo (flow-copy)Lê e editaVale só para este seller.
Pedido de mudança de estruturaCria e listaA plataforma analisa e aplica à mão.
FuncionalidadesLiga e desligaAlgumas são base e não desligam.
Fluxos nativos da MetaLiga e desligaAfeta a loja inteira.

Endpoints

Auth: Seller é um usuário do painel do seller (Authorization: Bearer $TOKEN).

MétodoRotaO que fazAuthPágina
GET/api/v1/vendor/whatsapp/flows/activeFluxo ativo do sellerSellerFluxo
GET/api/v1/vendor/whatsapp/flows/{id}Lê um fluxoSellerFluxo
PATCH/api/v1/vendor/whatsapp/flows/{id}Altera nome, status e gatilhoSellerFluxo
GET/api/v1/vendor/whatsapp/flows/{id}/validateConfere o desenho do fluxoSellerFluxo
GET/api/v1/vendor/whatsapp/flows/{id}/blocksLista os blocosSellerBlocos
POST/api/v1/vendor/whatsapp/flows/{id}/blocksCria um blocoSellerBlocos
PATCH/api/v1/vendor/whatsapp/blocks/{block_id}Altera um blocoSellerBlocos
DELETE/api/v1/vendor/whatsapp/blocks/{block_id}Apaga um blocoSellerBlocos
GET/api/v1/vendor/whatsapp/flows/{id}/connectionsLista as conexõesSellerConexões
POST/api/v1/vendor/whatsapp/flows/{id}/connectionsCria uma conexãoSellerConexões
DELETE/api/v1/vendor/whatsapp/connections/{conn_id}Apaga uma conexãoSellerConexões
GET/api/v1/vendor/whatsapp/flow-copyLê os textos editáveisSellerTextos
PUT/api/v1/vendor/whatsapp/flow-copyGrava textosSellerTextos
GET/api/v1/vendor/whatsapp/flow-requestsLista pedidos de mudançaSellerTextos
POST/api/v1/vendor/whatsapp/flow-requestsPede uma mudança de estruturaSellerTextos
GET/api/v1/vendor/whatsapp/playbooksLista os modelos prontosSellerModelos prontos
POST/api/v1/vendor/whatsapp/playbooks/{slug}/installInstala um modelo prontoSellerModelos prontos
GET/api/v1/vendor/whatsapp/capabilitiesLista as funcionalidadesSellerFuncionalidades
PUT/api/v1/vendor/whatsapp/capabilities/{pack}Liga ou desliga uma funcionalidadeSellerFuncionalidades
POST/api/v1/vendor/whatsapp/capabilities/presetAplica um modelo como conjunto de funcionalidadesSellerFuncionalidades
GET/api/v1/vendor/whatsapp/native-flows/statusSituação dos fluxos nativosSellerFluxos nativos
POST/api/v1/vendor/whatsapp/native-flows/activateAtiva os fluxos nativosSellerFluxos nativos
POST/api/v1/vendor/whatsapp/native-flows/deactivateDesativa os fluxos nativosSellerFluxos nativos

Erros comuns

  • Editar o fluxo da loja. Um fluxo sem seller dono responde 404 flow not found or not owned by this seller. Instale um modelo pronto ou chame flows/active para ganhar uma cópia editável.
  • Gravar um desenho quebrado. Blocos e conexões entram sem checagem de coerência. Uma seta para um bloco de outro fluxo só aparece em validate.
  • trigger_type: "keyword" sem palavras. A gravação é recusada com 400.
  • Instalar o mesmo modelo várias vezes. Cada instalação cria fluxos novos; as cópias antigas ficam lá. Use a opção de substituição ou apague o excesso.
  • Esperar que PUT /capabilities/{pack} recuse um valor errado. Pacote desconhecido ou de base responde sucesso sem fazer nada.
  • Ligar os fluxos nativos achando que é só deste seller. O efeito é na loja toda e desliga o carrinho por link (mini-loja).
  • Confiar no texto de erro. Muitas mensagens saem em português ou em inglês técnico. Use o status HTTP.

Próximos passos

Fluxo
Ler, ativar e validar o fluxo.
Modelos prontos
Começar de um fluxo desenhado.
Textos
Trocar só as frases do bot.
Anterior
Ligações
Próxima
Fluxo
Nesta página
  • Como funciona
  • O caminho de um cliente pelo fluxo
  • O fluxo típico de uma integração
  • Conceitos-chave
  • Estados de um fluxo
  • Ids e dinheiro
  • Quem pode editar o quê
  • Endpoints
  • Erros comuns
  • Próximos passos