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

Blocos

Lista, cria, lê, altera e apaga os blocos (passos) de um fluxo de conversa.

Um bloco é um passo da conversa: enviar uma mensagem, mostrar um menu, perguntar um dado, decidir por uma condição, passar para um atendente. O que o bloco faz depende do block_type e do config.

Listar os blocos de um fluxo

Devolve os blocos do fluxo em ordem de position (e, em empate, do mais antigo ao mais novo). Não verifica se o fluxo existe: um id desconhecido devolve lista vazia.

GET/api/v1/admin/whatsapp/flows/{id}/blocksAdmin

Lista os blocos de um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Exemplo de requisição (Listar blocos)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/flows/fa4b0c91-2883-43c6-94ef-86e5b540a2aa/blocks" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Listar blocos)

200Blocos devolvidos
json
{
  "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "blocks": [
    {
      "id": "b8c1057a-d5b6-448f-af73-31734882b110",
      "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
      "block_type": "menu",
      "name": "Menu",
      "config": {
        "options": [
          {
            "label": "Ver produtos",
            "option_index": 1
          },
          {
            "label": "Meus pedidos",
            "option_index": 2
          }
        ]
      },
      "position": 0,
      "position_x": 990,
      "position_y": 337,
      "status": "active",
      "created_at": "2026-05-07T06:53:17.425442Z",
      "updated_at": "2026-07-21T15:16:48.409466Z"
    }
  ]
}

Campos da resposta

flow_iduuid
O fluxo pedido.
blocksarray

Blocos do fluxo.

iduuid
Identificador do bloco.
flow_iduuid
Fluxo a que o bloco pertence.
block_typestring
Tipo do bloco (veja a tabela no fim da página).
namestring
Nome mostrado no editor.
block_keystring
Chave estável opcional, útil para encontrar o bloco sem depender do id. Ausente quando não definida.
configobject
Configuração do bloco. Livre, depende do block_type.
positioninteger
Ordem do bloco na lista.
position_xinteger
Posição horizontal no desenho do editor.
position_yinteger
Posição vertical no desenho do editor.
statusstring
activedisabled
Estado do bloco.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Listar blocos)

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"}
500O id não é um UUID válido, ou falha ao consultar.{"error":"Failed to list blocks: ..."}

Adicionar um bloco

Cria um bloco dentro do fluxo. O bloco nasce solto: ligue-o a outros com uma conexão e, se for o primeiro, defina-o como start_block_id.

POST/api/v1/admin/whatsapp/flows/{id}/blocksAdmin

Adiciona um bloco a um fluxo

Parâmetros de caminho

iduuidobrigatório
Id do fluxo.

Corpo da requisição

block_typestringobrigatório
Tipo do bloco. Obrigatório. A rota não confere o valor contra a lista de tipos: um tipo desconhecido é aceito aqui e só falha quando o bot tenta executá-lo.
namestring
Nome mostrado no editor.
block_keystring
Chave estável opcional.
configobject
Configuração do bloco, um objeto JSON livre (veja a tabela no fim da página). Omitido, vira {}. Chaves desconhecidas são aceitas e guardadas, mas o bot as ignora.
positionintegerpadrão: 0
Ordem na lista.
position_xintegerpadrão: 0
Posição horizontal no editor.
position_yintegerpadrão: 0
Posição vertical no editor.
statusstringpadrão: active
activedisabled
Estado.

Exemplo de requisição (Adicionar um bloco)

bash
curl -X POST "$BASE_URL/api/v1/admin/whatsapp/flows/fa4b0c91-2883-43c6-94ef-86e5b540a2aa/blocks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "block_type": "message",
    "name": "Boas-vindas",
    "config": {
      "text": "Oi! Bem-vindo à nossa loja."
    },
    "position_x": 120,
    "position_y": 80
  }'

Resposta (Adicionar um bloco)

201Bloco criado
json
{
  "id": "c9f47922-b163-47f0-a7db-8345287707fc",
  "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "block_type": "message",
  "name": "Boas-vindas",
  "config": {
    "text": "Oi! Bem-vindo à nossa loja."
  },
  "position": 0,
  "position_x": 120,
  "position_y": 80,
  "status": "active",
  "created_at": "2026-10-11T14:30:00.000000Z",
  "updated_at": "2026-10-11T14:30:00.000000Z"
}

Campos da resposta

iduuid
Identificador do bloco.
flow_iduuid
Fluxo a que o bloco pertence.
block_typestring
Tipo do bloco (veja a tabela no fim da página).
namestring
Nome mostrado no editor.
block_keystring
Chave estável opcional, útil para encontrar o bloco sem depender do id. Ausente quando não definida.
configobject
Configuração do bloco. Livre, depende do block_type.
positioninteger
Ordem do bloco na lista.
position_xinteger
Posição horizontal no desenho do editor.
position_yinteger
Posição vertical no desenho do editor.
statusstring
activedisabled
Estado do bloco.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Adicionar um bloco)

StatusQuandoCorpo
400Corpo que não é JSON, block_type vazio, ou fluxo inexistente (a chave estrangeira recusa).{"error":"whatsapp/flows: block_type is required"}
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"}

Ver um bloco

Devolve um bloco pelo id, sem precisar do id do fluxo.

GET/api/v1/admin/whatsapp/blocks/{block_id}Admin

Lê um bloco

Parâmetros de caminho

block_iduuidobrigatório
Id do bloco.

Exemplo de requisição (Ver um bloco)

bash
curl "$BASE_URL/api/v1/admin/whatsapp/blocks/b8c1057a-d5b6-448f-af73-31734882b110" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Ver um bloco)

200Bloco devolvido
json
{
  "id": "b8c1057a-d5b6-448f-af73-31734882b110",
  "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "block_type": "menu",
  "name": "Menu",
  "config": {
    "options": [
      {
        "label": "Ver produtos",
        "option_index": 1
      },
      {
        "label": "Meus pedidos",
        "option_index": 2
      }
    ]
  },
  "position": 0,
  "position_x": 990,
  "position_y": 337,
  "status": "active",
  "created_at": "2026-05-07T06:53:17.425442Z",
  "updated_at": "2026-07-21T15:16:48.409466Z"
}

Campos da resposta

iduuid
Identificador do bloco.
flow_iduuid
Fluxo a que o bloco pertence.
block_typestring
Tipo do bloco (veja a tabela no fim da página).
namestring
Nome mostrado no editor.
block_keystring
Chave estável opcional, útil para encontrar o bloco sem depender do id. Ausente quando não definida.
configobject
Configuração do bloco. Livre, depende do block_type.
positioninteger
Ordem do bloco na lista.
position_xinteger
Posição horizontal no desenho do editor.
position_yinteger
Posição vertical no desenho do editor.
statusstring
activedisabled
Estado do bloco.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Ver um bloco)

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"}
404Bloco não encontrado.{"error":"Block not found"}
500O id não é um UUID válido.{"error":"Failed to load block: ..."}

Alterar um bloco

Altera só os campos enviados. O config enviado substitui o atual por inteiro: reenvie o objeto completo.

PATCH/api/v1/admin/whatsapp/blocks/{block_id}Admin

Altera um bloco

Parâmetros de caminho

block_iduuidobrigatório
Id do bloco.

Corpo da requisição

block_typestring
Novo tipo.
namestring
Novo nome.
block_keystring
Nova chave. "" limpa.
configobject
Novo config, que substitui o atual. null volta para {}.
positioninteger
Nova ordem.
position_xinteger
Nova posição horizontal.
position_yinteger
Nova posição vertical.
statusstring
activedisabled
Novo estado.

Exemplo de requisição (Alterar um bloco)

bash
curl -X PATCH "$BASE_URL/api/v1/admin/whatsapp/blocks/b8c1057a-d5b6-448f-af73-31734882b110" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Menu principal",
    "position_x": 400,
    "position_y": 200
  }'

Resposta (Alterar um bloco)

200Bloco atualizado
json
{
  "id": "b8c1057a-d5b6-448f-af73-31734882b110",
  "flow_id": "fa4b0c91-2883-43c6-94ef-86e5b540a2aa",
  "block_type": "menu",
  "name": "Menu principal",
  "config": {
    "options": [
      {
        "label": "Ver produtos",
        "option_index": 1
      },
      {
        "label": "Meus pedidos",
        "option_index": 2
      }
    ]
  },
  "position": 0,
  "position_x": 400,
  "position_y": 200,
  "status": "active",
  "created_at": "2026-05-07T06:53:17.425442Z",
  "updated_at": "2026-07-21T15:16:48.409466Z"
}

Campos da resposta

iduuid
Identificador do bloco.
flow_iduuid
Fluxo a que o bloco pertence.
block_typestring
Tipo do bloco (veja a tabela no fim da página).
namestring
Nome mostrado no editor.
block_keystring
Chave estável opcional, útil para encontrar o bloco sem depender do id. Ausente quando não definida.
configobject
Configuração do bloco. Livre, depende do block_type.
positioninteger
Ordem do bloco na lista.
position_xinteger
Posição horizontal no desenho do editor.
position_yinteger
Posição vertical no desenho do editor.
statusstring
activedisabled
Estado do bloco.
created_atstring
Criação (RFC 3339, UTC).
updated_atstring
Última alteração (RFC 3339, UTC).

Erros (Alterar um bloco)

StatusQuandoCorpo
400Corpo que não é JSON.{"error":"Invalid JSON 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"}
404Bloco não encontrado.{"error":"Block not found"}
`config` é substituído, não mesclado

Enviar {"text":"novo"} apaga todas as outras chaves do config. Leia o bloco, altere o objeto e envie-o inteiro.

Apagar um bloco

Apaga o bloco (remoção lógica) e todas as ligações que entram ou saem dele.

DELETE/api/v1/admin/whatsapp/blocks/{block_id}Admin

Apaga um bloco e suas ligações

Parâmetros de caminho

block_iduuidobrigatório
Id do bloco.

Exemplo de requisição (Apagar um bloco)

bash
curl -X DELETE "$BASE_URL/api/v1/admin/whatsapp/blocks/b8c1057a-d5b6-448f-af73-31734882b110" \
  -H "Authorization: Bearer $TOKEN"

Resposta (Apagar um bloco)

200Bloco apagado
json
{
  "status": "deleted",
  "id": "b8c1057a-d5b6-448f-af73-31734882b110"
}

Campos da resposta

statusstring
deleted
Sempre deleted.
iduuid
O id enviado.

Erros (Apagar um bloco)

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"}
500O id não é um UUID válido, ou falha ao apagar.{"error":"Failed to delete block: ..."}
Cuidado com o bloco inicial

Se você apagar o bloco que é o start_block_id do fluxo, o fluxo continua apontando para ele e /validate passa a acusar start_block_not_in_flow. Defina outro bloco inicial. A rota também responde deleted para um id inexistente.

Tipos de bloco

O campo block_type aceita os valores abaixo. Os blocos de Meta Flow (list, button, form e afins) usam telas nativas do WhatsApp; os demais são mensagens de conversa.

GrupoTipos
Entrada e controletrigger, message, menu, input_text, conditional, end
Lojalogin, products, cart, checkout, order_history, order_details, order_success, order_confirmation, recover_cart, cancellation, shipping, payment
Contasignup, registration, address, forgot_password, change_password, otp
Telas e mídialist, button, form, media, location, send_template
Assistente e atendimentoai_reply, human_handoff

Chaves de config mais usadas

O config é livre e cada tipo lê suas próprias chaves. As principais:

TipoChaves
messagetext (também aceita message ou body): o texto enviado.
menuquestion (ou prompt, header): a pergunta; options: lista de {label, description}. O cliente responde com o número (a partir de 1), com o texto da opção ou tocando no botão.
input_textquestion, variable_name (onde guardar a resposta), required, validation_regex, error_message.
conditionalvariable, operator (equals, not_equals, contains, greater_than, less_than, is_empty, is_not_empty) e value; ou uma lista conditions com vários desses trios.
mediacontent_type (image, video, document ou audio), media_url, caption.
ai_replymulti_turn (continua no bloco após a resposta), enable_product_search, enable_kb_injection, max_tokens.
order_historylimit (padrão 10), empty_message.

As chaves de texto aceitam variáveis entre chaves duplas, como {{vendor_name}}, preenchidas pelo bot.

Como as ligações escolhem o próximo bloco

Quando um bloco termina, o bot procura uma ligação que sai dele. O connection_type da ligação decide o caminho: next (padrão, segue sempre), option_0, option_1... (a opção escolhida num menu, contando de zero) e condition_0, condition_1... (o ramo que casou num conditional). Em caso de nenhuma opção ou condição casar, o bot tenta a ligação default e depois next. Veja a página de ligações.

Veja também

  • Ligações
  • Criar e alterar fluxos
Anterior
Criar e alterar fluxos
Próxima
Ligações
Nesta página
  • Listar os blocos de um fluxo
  • Exemplo de requisição (Listar blocos)
  • Resposta (Listar blocos)
  • Erros (Listar blocos)
  • Adicionar um bloco
  • Exemplo de requisição (Adicionar um bloco)
  • Resposta (Adicionar um bloco)
  • Erros (Adicionar um bloco)
  • Ver um bloco
  • Exemplo de requisição (Ver um bloco)
  • Resposta (Ver um bloco)
  • Erros (Ver um bloco)
  • Alterar um bloco
  • Exemplo de requisição (Alterar um bloco)
  • Resposta (Alterar um bloco)
  • Erros (Alterar um bloco)
  • Apagar um bloco
  • Exemplo de requisição (Apagar um bloco)
  • Resposta (Apagar um bloco)
  • Erros (Apagar um bloco)
  • Tipos de bloco
  • Chaves de config mais usadas
  • Como as ligações escolhem o próximo bloco
  • Veja também