Create conversation configuration

Creates the conversation configuration (conversation-config) of a phase — a WhatsApp message-template state machine that captures responses directly by message, without the person involved needing to access AgFlow. It is commonly used to run approvals entirely over WhatsApp.

This operation only creates a new configuration. If the phase already has a conversation configuration, the call returns an error stating that a configuration already exists for this flow. There is no dedicated update endpoint (PUT) for conversation-config: to update an existing configuration, you must first remove the current one (DELETE /v1/flows/conversation-config/{id}) and then create a new one with the updated payload. The identifier of the previous configuration can be obtained either from a lookup (GET) or from the body of the error returned by this duplicate creation attempt.

Recreating the configuration generates a new conversation identifier. This is not a problem for automation: the finalized-auto-document triggers with the start-conversation action, which actually start the conversation, are tied to the phase — not to the configuration identifier — and remain valid after recreation.

The payload consists of a list of rules. Each rule combines: setup.phoneId (the WhatsApp number, already configured on the phase, that sends the messages), conditions (conditions that determine when the rule applies — typically the status of the document automatically generated on the phase), and conversation (a title and a list of templates, the state machine itself).

Each template represents a step of the conversation and defines: the dynamic fields that populate the message (fields), where the user's response should be stored (saveIn / saveInType), the identifier of the message template approved on WhatsApp Meta (templateId), the routing rules (rules) that point to the next template (templateTarget) based on the response received, and, optionally, an alternate template (fallback) used in alternative scenarios, such as a failure generating the linked document.

Important behaviors:

The target values used to compare the user's response must match EXACTLY the button labels defined on the template approved on WhatsApp Meta, including case and accents. Mismatches do not produce an API error, but cause a silent routing failure — the conversation gets stuck at that point.

When capturing a monetary response (saveInType: "money"), the corresponding rule's condition must be type — which checks whether the response is a monetary value — and not eq, which would compare the response against the literal string "money" and never match, permanently blocking that branch of the conversation.

The conversation configuration only takes effect if there is, on the same phase, a trigger of type finalized-auto-document with the start-conversation action. Without that trigger, the conversation never starts, even with the configuration correctly created.

We strongly recommend reusing WhatsApp message templates already approved by Meta instead of creating new templates for each configuration — approval of a new template can take 24 to 48 hours.

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": {} } ] } } ] }'

Create conversation configuration

Requisição

Respostas