Conversa — Visão geral

A configuração de conversa (conversation-config) permite capturar dados e decisões do usuário — como aprovar, reprovar ou informar um valor — diretamente por uma conversa de WhatsApp, sem que a pessoa precise acessar o AgFlow. Cada configuração é uma máquina de estados de modelos de mensagem: a cada resposta do usuário, a conversa avança para o próximo modelo, até alcançar um estado final.

A configuração de conversa depende de outras configurações da mesma fase: o número de WhatsApp que envia as mensagens (phone-config) e, quando a conversa é disparada pela geração de um documento, a configuração de documento automático (auto-document-config) e o modelo de documento vinculado.

Endpoints deste domínio

Método	Caminho	Descrição
`GET`	`/v1/flows/{flowId}/phases/{phaseId}/conversation-config`	Consulta a configuração de conversa da fase
`POST`	`/v1/flows/{flowId}/phases/{phaseId}/conversation-config`	Cria a configuração de conversa da fase
`DELETE`	`/v1/flows/conversation-config/{id}`	Remove a configuração de conversa

Nota sobre nomenclatura: no caminho de criação/consulta, o parâmetro do flow é {flowId}. Já o caminho de remoção usa apenas {id}, sem {flowId} nem {phaseId} — a configuração é identificada globalmente pelo seu próprio identificador.

Não existe atualização (PUT) — o padrão é remover e recriar

Não há um endpoint de atualização dedicado para conversation-config. Uma tentativa de PUT no caminho de fase não é reconhecida pela API. Para atualizar uma configuração existente — por exemplo, para trocar o modelo de documento referenciado ou ajustar uma regra de roteamento — o padrão correto é:

Remover a configuração atual via DELETE /v1/flows/conversation-config/{id}.

Criar uma nova via POST /v1/flows/{flowId}/phases/{phaseId}/conversation-config, com o payload já atualizado.

Uma chamada de POST em uma fase que já possui configuração retorna erro informando a preexistência, e o corpo desse erro inclui o identificador da configuração existente — que também pode ser obtido via GET antes de iniciar o processo de atualização.

Recriar a configuração gera um novo identificador de conversa. Isso não afeta a automação: os triggers do tipo finalized-auto-document com ação start-conversation são vinculados à fase, não ao identificador da configuração, e continuam válidos após a recriação.

Estrutura da máquina de estados

O payload de criação é uma lista de rules. Cada regra combina:

setup.phoneId — o número de WhatsApp (já configurado na fase) que envia as mensagens.

conditions — condições que determinam quando a regra se aplica, tipicamente com base no status do documento gerado automaticamente na fase.

conversation — título e lista de templates, a máquina de estados propriamente dita.

Cada modelo (template) representa uma etapa da conversa e define os campos dinâmicos que preenchem a mensagem, onde a resposta do usuário é gravada, o identificador do modelo aprovado no WhatsApp Meta, as regras de roteamento que apontam para o próximo modelo de acordo com a resposta recebida e, opcionalmente, um modelo alternativo (fallback) para cenários como falha na geração do documento.

Comportamentos importantes

Consultar uma fase sem configuração de conversa retorna erro 404 — comportamento esperado, não uma falha.

Os textos usados para comparar a resposta do usuário (target) devem corresponder EXATAMENTE aos botões definidos no modelo aprovado no WhatsApp Meta, incluindo acentuação e maiúsculas/minúsculas — divergências causam falha silenciosa de roteamento, sem erro na API.

Ao capturar uma resposta de valor monetário, a regra correspondente deve usar condition: "type" (verifica se a resposta é um valor monetário) — nunca condition: "eq", que compararia a resposta com a string literal "money" e nunca encontraria correspondência.

A conversa só é efetivamente iniciada se existir, na mesma fase, um trigger do tipo finalized-auto-document com ação start-conversation. A configuração de conversa, sozinha, sem esse trigger, não dispara nada.

Recomendamos sempre reutilizar modelos de mensagem WhatsApp já aprovados pela Meta em vez de criar modelos novos a cada configuração — a aprovação de um modelo novo pode levar de 24 a 48 horas.

Remover uma configuração de conversa (DELETE) não desativa o trigger finalized-auto-document associado à fase; ele permanece ativo, porém sem efeito, até que uma nova configuração seja criada.

Conversa — Visão Geral

Conversa — Visão geral#

Endpoints deste domínio#

Não existe atualização (PUT) — o padrão é remover e recriar#

Estrutura da máquina de estados#

Comportamentos importantes#

Conversa — Visão geral

Endpoints deste domínio

Não existe atualização (PUT) — o padrão é remover e recriar

Estrutura da máquina de estados

Comportamentos importantes