Criar configuração de conversa

Cria a configuração de conversa (conversation-config) de uma fase — uma máquina de estados de modelos de mensagem WhatsApp que permite capturar respostas diretamente por mensagem, sem que a pessoa envolvida precise acessar o AgFlow. É comumente usada para conduzir aprovações inteiramente por WhatsApp.

Esta operação só cria uma configuração nova. Se a fase já possuir uma configuração de conversa, a chamada retorna erro informando que já existe uma configuração para este flow. Não existe endpoint de atualização (PUT) dedicado para conversation-config: para atualizar uma configuração existente, é necessário primeiro remover a configuração atual (DELETE /v1/flows/conversation-config/{id}) e, em seguida, criar uma nova com o payload atualizado. O identificador da configuração anterior pode ser obtido tanto pela consulta (GET) quanto pelo corpo do próprio erro retornado nesta tentativa de criação duplicada.

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

O payload é composto por uma lista de rules. Cada regra combina: setup.phoneId (o número de WhatsApp, já configurado previamente na fase, que envia as mensagens), conditions (condições que determinam quando a regra se aplica — tipicamente o status do documento gerado automaticamente na fase) e 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 (fields), onde a resposta do usuário deve ser gravada (saveIn / saveInType), o identificador do modelo de mensagem aprovado no WhatsApp Meta (templateId), as regras de roteamento (rules) que direcionam para o próximo modelo (templateTarget) de acordo com a resposta recebida, e, opcionalmente, um modelo alternativo (fallback) usado em cenários alternativos, como falha na geração do documento vinculado.

Comportamentos importantes:

Os valores de target usados para comparar a resposta do usuário devem corresponder EXATAMENTE aos textos dos botões definidos no modelo aprovado no WhatsApp Meta, incluindo maiúsculas/minúsculas e acentuação. Divergências não geram erro na API, mas causam falha silenciosa de roteamento — a conversa trava naquele ponto.

Ao capturar uma resposta de valor monetário (saveInType: "money"), a condição da regra correspondente deve ser type — que verifica se a resposta é um valor monetário — e não eq, que compararia a resposta com a string literal "money" e nunca encontraria correspondência, travando permanentemente aquele ramo da conversa.

A configuração de conversa só produz efeito se existir, na mesma fase, um trigger do tipo finalized-auto-document com ação start-conversation. Sem esse trigger, a conversa nunca é iniciada, mesmo com a configuração corretamente criada.

Recomendamos fortemente 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.

curl --location '/v1/flows//phases//conversation-config' \ --header 'Content-Type: application/json' \ --data '{ "rules": [ { "setup": { "phoneId": "string" }, "conditions": [ { "rule": [ { "path": "string", "reference": "string", "condition": "string", "target": null } ] } ], "conversation": { "title": "string", "templates": [ { "id": "string", "description": "string", "fields": [ { "key": "string", "path": "string", "type": "string", "reference": "string", "description": "string" } ], "saveIn": "string", "saveInType": "string", "templateId": "string", "rules": [ { "conditions": [ { "rule": [ { "field": "string", "condition": "string", "target": null } ] } ], "templateTarget": "string" } ], "fallback": {} } ] } } ] }'

Criar configuração de conversa

Requisição

Respostas