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

Blocos

Lista, cria, altera e apaga os blocos (passos) do fluxo de conversa do seller.

Um bloco é um passo do fluxo: enviar um texto, mostrar um menu, buscar produtos, passar para um atendente. Os blocos de um fluxo são ligados por conexões. Estas quatro rotas só mexem no fluxo do próprio seller: o bloco de um fluxo da loja ou de outro seller responde 404.

As rotas de bloco não conferem se o desenho continua coerente. Ao terminar de editar, rode Validar o desenho.

Tipos de bloco

O campo block_type aceita qualquer texto na gravação, sem checagem. Use um dos tipos abaixo, que são os que a conversa sabe executar; um tipo inventado é gravado sem erro, mas não é um passo que o fluxo conheça.

`block_type`	O que faz
`trigger`	Ponto de partida que combina a mensagem com palavras-chave.
`message`	Envia um texto. Não espera resposta.
`menu`	Mostra uma lista de opções. Cada opção sai por uma conexão `option_N`.
`input_text`	Pede um texto livre e o guarda na variável `variable_name`.
`conditional`	Escolhe um caminho conforme uma variável. Saídas `condition_N` e `default`.
`products`	Vitrine de produtos.
`cart`, `checkout`, `order_confirmation`, `order_success`	Etapas do carrinho à confirmação.
`order_history`, `order_details`, `cancellation`, `recover_cart`	Pedidos do cliente.
`login`, `otp`, `signup`, `registration`, `address`, `forgot_password`, `change_password`	Identificação e cadastro do cliente.
`shipping`, `payment`, `location`, `form`, `list`, `button`, `media`	Telas de formulário, envio e pagamento.
`send_template`	Envia um modelo de mensagem aprovado pela Meta (usa `template_name`). Útil fora da janela de 24 horas.
`ai_reply`	Entrega a conversa ao assistente de IA.
`human_handoff`	Passa para um atendente humano e desliga o bot na conversa.
`end`	Encerra o fluxo.

Listar os blocos

GET/api/v1/vendor/whatsapp/flows/{id}/blocksSeller

Lista os blocos de um fluxo

Ordenados por position. Blocos apagados não aparecem.

Parâmetros de caminho

iduuidobrigatório

Id do fluxo.

Exemplo de requisição

bash

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

Resposta

200Blocos do fluxo

json

{
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "blocks": [
    {
      "id": "b1a2c3d4-0000-4000-8000-000000000001",
      "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
      "block_type": "message",
      "name": "Boas-vindas",
      "block_key": "welcome",
      "config": { "text": "Oi! Bem-vindo à {{vendor_name}}." },
      "position": 0,
      "position_x": 80,
      "position_y": 40,
      "status": "active",
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-01T12:00:00Z"
    }
  ]
}

Campos da resposta

flow_iduuid

Fluxo consultado.

blocksarray

Blocos do fluxo.

blocks[].iduuid

Id do bloco. Use nas conexões e em PATCH/DELETE.

blocks[].flow_iduuid

Fluxo a que pertence.

blocks[].block_typestring

Tipo do bloco (tabela acima).

blocks[].namestring

Nome mostrado no editor.

blocks[].block_keystring

Chave estável escolhida por você, para localizar o bloco sem depender do id. Ausente se não definida.

blocks[].configobject

Configuração do bloco. As chaves dependem do tipo (veja abaixo). Sempre um objeto, {} quando vazio.

blocks[].positioninteger

Ordem de listagem.

blocks[].position_xinteger

Posição horizontal no editor visual.

blocks[].position_yinteger

Posição vertical no editor visual.

blocks[].statusstring

activedisabled

disabled esconde o bloco do fluxo sem apagar.

blocks[].created_atstring

RFC 3339.

blocks[].updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Fluxo inexistente, da loja ou de outro seller	`{"error":"flow not found or not owned by this seller"}`
500	Falha ao ler	`{"error":"..."}`

Criar um bloco

POST/api/v1/vendor/whatsapp/flows/{id}/blocksSeller

Cria um bloco no fluxo

Devolve 201 com o bloco criado. O bloco nasce solto: ligue-o com uma conexão e, se for o primeiro passo, defina-o como start_block_id do fluxo.

Parâmetros de caminho

iduuidobrigatório

Id do fluxo.

Corpo da requisição

block_typestringobrigatório

Tipo do bloco.

namestring

Nome mostrado no editor.

block_keystring

Chave estável para localizar o bloco.

configobject

Configuração do bloco. Ausente ou null vira {}.

positionintegerpadrão: 0

Ordem de listagem.

position_xintegerpadrão: 0

Posição horizontal no editor.

position_yintegerpadrão: 0

Posição vertical no editor.

statusstringpadrão: active

activedisabled

Estado do bloco.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/flows/$FLOW_ID/blocks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "block_type": "message",
  "name": "Horário",
  "block_key": "hours",
  "config": {
    "text": "Atendemos de segunda a sábado, das 9h às 18h."
  },
  "position_x": 360,
  "position_y": 80
}'

Resposta

201Bloco criado

json

{
  "id": "b1a2c3d4-0000-4000-8000-000000000010",
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "block_type": "message",
  "name": "Horário",
  "block_key": "hours",
  "config": { "text": "Atendemos de segunda a sábado, das 9h às 18h." },
  "position": 0,
  "position_x": 360,
  "position_y": 80,
  "status": "active",
  "created_at": "2026-10-11T14:10:00Z",
  "updated_at": "2026-10-11T14:10:00Z"
}

Os campos são os de um item da listagem.

Configuração por tipo

config é um objeto livre; estas são as chaves de uso mais comum.

Tipo	Chaves principais
`message`, `human_handoff`	`text` (aceita variáveis como `{{vendor_name}}`).
`menu`, `list`, `button`	`question` (pergunta), `options`: lista de objetos com `id` e `title`. A opção de índice N sai pela conexão `option_N`.
`input_text`	`question` e `variable_name`.
`products`	`header`, `message`, `limit` e `filling_type` (critério da vitrine, por exemplo `newest`).
`order_history`	`limit` (padrão 10) e `empty_message`.
`cart`	`empty_message`.
`ai_reply`	`text`, `system_prompt` e `enable_product_search`.
`send_template`	`template_name` e `template_params`.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	Falta `block_type`	`{"error":"whatsapp/flows: block_type is required"}`
400	Valor de `status` fora de `active`/`disabled`	`{"error":"whatsapp/flows: insert block: ..."}`
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Fluxo inexistente, da loja ou de outro seller	`{"error":"flow not found or not owned by this seller"}`

Alterar um bloco

PATCH/api/v1/vendor/whatsapp/blocks/{block_id}Seller

Altera um bloco

Atualização parcial. Note que a rota não leva o id do fluxo: o fluxo é descoberto pelo bloco. config, quando enviado, substitui o objeto inteiro (não faz mescla).

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. String vazia remove.

configobject

Nova configuração, completa.

positioninteger

Ordem.

position_xinteger

Posição horizontal.

position_yinteger

Posição vertical.

statusstring

activedisabled

Estado.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/whatsapp/blocks/$BLOCK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "text": "Atendemos de segunda a sexta, das 9h às 18h."
  }
}'

Resposta

200Bloco atualizado

json

{
  "id": "b1a2c3d4-0000-4000-8000-000000000010",
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "block_type": "message",
  "name": "Horário",
  "block_key": "hours",
  "config": { "text": "Atendemos de segunda a sexta, das 9h às 18h." },
  "position": 0,
  "position_x": 360,
  "position_y": 80,
  "status": "active",
  "created_at": "2026-10-11T14:10:00Z",
  "updated_at": "2026-10-11T14:20:00Z"
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Bloco inexistente	`{"error":"block not found"}`
404	Bloco de um fluxo que não é do seller	`{"error":"flow not found or not owned by this seller"}`

Apagar um bloco

DELETE/api/v1/vendor/whatsapp/blocks/{block_id}Seller

Apaga um bloco e as conexões dele

Exclusão lógica: o bloco sai do fluxo e todas as conexões que entram ou saem dele também. Se o bloco apagado era o start_block_id do fluxo, o campo continua apontando para ele, e validate passa a acusar start_block_not_in_flow.

Parâmetros de caminho

block_iduuidobrigatório

Id do bloco.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/whatsapp/blocks/$BLOCK_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Bloco apagado

json

{ "status": "deleted", "id": "b1a2c3d4-0000-4000-8000-000000000010" }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Bloco inexistente ou já apagado	`{"error":"block not found"}`
404	Bloco de um fluxo que não é do seller	`{"error":"flow not found or not owned by this seller"}`
400	Falha ao apagar	`{"error":"..."}`

Veja também

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

Blocos

Lista, cria, altera e apaga os blocos (passos) do fluxo de conversa do seller.

As rotas de bloco não conferem se o desenho continua coerente. Ao terminar de editar, rode Validar o desenho.

Tipos de bloco

`block_type`	O que faz
`trigger`	Ponto de partida que combina a mensagem com palavras-chave.
`message`	Envia um texto. Não espera resposta.
`menu`	Mostra uma lista de opções. Cada opção sai por uma conexão `option_N`.
`input_text`	Pede um texto livre e o guarda na variável `variable_name`.
`conditional`	Escolhe um caminho conforme uma variável. Saídas `condition_N` e `default`.
`products`	Vitrine de produtos.
`cart`, `checkout`, `order_confirmation`, `order_success`	Etapas do carrinho à confirmação.
`order_history`, `order_details`, `cancellation`, `recover_cart`	Pedidos do cliente.
`login`, `otp`, `signup`, `registration`, `address`, `forgot_password`, `change_password`	Identificação e cadastro do cliente.
`shipping`, `payment`, `location`, `form`, `list`, `button`, `media`	Telas de formulário, envio e pagamento.
`send_template`	Envia um modelo de mensagem aprovado pela Meta (usa `template_name`). Útil fora da janela de 24 horas.
`ai_reply`	Entrega a conversa ao assistente de IA.
`human_handoff`	Passa para um atendente humano e desliga o bot na conversa.
`end`	Encerra o fluxo.

Listar os blocos

GET/api/v1/vendor/whatsapp/flows/{id}/blocksSeller

Lista os blocos de um fluxo

Ordenados por position. Blocos apagados não aparecem.

Parâmetros de caminho

iduuidobrigatório

Id do fluxo.

Exemplo de requisição

bash

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

Resposta

200Blocos do fluxo

json

{
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "blocks": [
    {
      "id": "b1a2c3d4-0000-4000-8000-000000000001",
      "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
      "block_type": "message",
      "name": "Boas-vindas",
      "block_key": "welcome",
      "config": { "text": "Oi! Bem-vindo à {{vendor_name}}." },
      "position": 0,
      "position_x": 80,
      "position_y": 40,
      "status": "active",
      "created_at": "2026-10-01T12:00:00Z",
      "updated_at": "2026-10-01T12:00:00Z"
    }
  ]
}

Campos da resposta

flow_iduuid

Fluxo consultado.

blocksarray

Blocos do fluxo.

blocks[].iduuid

Id do bloco. Use nas conexões e em PATCH/DELETE.

blocks[].flow_iduuid

Fluxo a que pertence.

blocks[].block_typestring

Tipo do bloco (tabela acima).

blocks[].namestring

Nome mostrado no editor.

blocks[].block_keystring

Chave estável escolhida por você, para localizar o bloco sem depender do id. Ausente se não definida.

blocks[].configobject

Configuração do bloco. As chaves dependem do tipo (veja abaixo). Sempre um objeto, {} quando vazio.

blocks[].positioninteger

Ordem de listagem.

blocks[].position_xinteger

Posição horizontal no editor visual.

blocks[].position_yinteger

Posição vertical no editor visual.

blocks[].statusstring

activedisabled

disabled esconde o bloco do fluxo sem apagar.

blocks[].created_atstring

RFC 3339.

blocks[].updated_atstring

RFC 3339.

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Fluxo inexistente, da loja ou de outro seller	`{"error":"flow not found or not owned by this seller"}`
500	Falha ao ler	`{"error":"..."}`

Criar um bloco

POST/api/v1/vendor/whatsapp/flows/{id}/blocksSeller

Cria um bloco no fluxo

Devolve 201 com o bloco criado. O bloco nasce solto: ligue-o com uma conexão e, se for o primeiro passo, defina-o como start_block_id do fluxo.

Parâmetros de caminho

iduuidobrigatório

Id do fluxo.

Corpo da requisição

block_typestringobrigatório

Tipo do bloco.

namestring

Nome mostrado no editor.

block_keystring

Chave estável para localizar o bloco.

configobject

Configuração do bloco. Ausente ou null vira {}.

positionintegerpadrão: 0

Ordem de listagem.

position_xintegerpadrão: 0

Posição horizontal no editor.

position_yintegerpadrão: 0

Posição vertical no editor.

statusstringpadrão: active

activedisabled

Estado do bloco.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/vendor/whatsapp/flows/$FLOW_ID/blocks" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "block_type": "message",
  "name": "Horário",
  "block_key": "hours",
  "config": {
    "text": "Atendemos de segunda a sábado, das 9h às 18h."
  },
  "position_x": 360,
  "position_y": 80
}'

Resposta

201Bloco criado

json

{
  "id": "b1a2c3d4-0000-4000-8000-000000000010",
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "block_type": "message",
  "name": "Horário",
  "block_key": "hours",
  "config": { "text": "Atendemos de segunda a sábado, das 9h às 18h." },
  "position": 0,
  "position_x": 360,
  "position_y": 80,
  "status": "active",
  "created_at": "2026-10-11T14:10:00Z",
  "updated_at": "2026-10-11T14:10:00Z"
}

Os campos são os de um item da listagem.

Configuração por tipo

config é um objeto livre; estas são as chaves de uso mais comum.

Tipo	Chaves principais
`message`, `human_handoff`	`text` (aceita variáveis como `{{vendor_name}}`).
`menu`, `list`, `button`	`question` (pergunta), `options`: lista de objetos com `id` e `title`. A opção de índice N sai pela conexão `option_N`.
`input_text`	`question` e `variable_name`.
`products`	`header`, `message`, `limit` e `filling_type` (critério da vitrine, por exemplo `newest`).
`order_history`	`limit` (padrão 10) e `empty_message`.
`cart`	`empty_message`.
`ai_reply`	`text`, `system_prompt` e `enable_product_search`.
`send_template`	`template_name` e `template_params`.

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
400	Falta `block_type`	`{"error":"whatsapp/flows: block_type is required"}`
400	Valor de `status` fora de `active`/`disabled`	`{"error":"whatsapp/flows: insert block: ..."}`
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Fluxo inexistente, da loja ou de outro seller	`{"error":"flow not found or not owned by this seller"}`

Alterar um bloco

PATCH/api/v1/vendor/whatsapp/blocks/{block_id}Seller

Altera um bloco

Atualização parcial. Note que a rota não leva o id do fluxo: o fluxo é descoberto pelo bloco. config, quando enviado, substitui o objeto inteiro (não faz mescla).

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. String vazia remove.

configobject

Nova configuração, completa.

positioninteger

Ordem.

position_xinteger

Posição horizontal.

position_yinteger

Posição vertical.

statusstring

activedisabled

Estado.

Exemplo de requisição

bash

curl -X PATCH "$BASE_URL/api/v1/vendor/whatsapp/blocks/$BLOCK_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "config": {
    "text": "Atendemos de segunda a sexta, das 9h às 18h."
  }
}'

Resposta

200Bloco atualizado

json

{
  "id": "b1a2c3d4-0000-4000-8000-000000000010",
  "flow_id": "6f1c2d3e-9a4b-4c5d-8e7f-0a1b2c3d4e5f",
  "block_type": "message",
  "name": "Horário",
  "block_key": "hours",
  "config": { "text": "Atendemos de segunda a sexta, das 9h às 18h." },
  "position": 0,
  "position_x": 360,
  "position_y": 80,
  "status": "active",
  "created_at": "2026-10-11T14:10:00Z",
  "updated_at": "2026-10-11T14:20:00Z"
}

Erros

Status	Quando	Corpo
400	JSON inválido	`{"error":"Invalid JSON body"}`
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Bloco inexistente	`{"error":"block not found"}`
404	Bloco de um fluxo que não é do seller	`{"error":"flow not found or not owned by this seller"}`

Apagar um bloco

DELETE/api/v1/vendor/whatsapp/blocks/{block_id}Seller

Apaga um bloco e as conexões dele

Parâmetros de caminho

block_iduuidobrigatório

Id do bloco.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/vendor/whatsapp/blocks/$BLOCK_ID" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Bloco apagado

json

{ "status": "deleted", "id": "b1a2c3d4-0000-4000-8000-000000000010" }

Erros

Status	Quando	Corpo
401 / 403	Autenticação, módulo ou privilégio	veja Fluxo
404	Bloco inexistente ou já apagado	`{"error":"block not found"}`
404	Bloco de um fluxo que não é do seller	`{"error":"flow not found or not owned by this seller"}`
400	Falha ao apagar	`{"error":"..."}`