Conversation — Overview

The conversation configuration (conversation-config) captures user data and decisions — such as approving, rejecting, or providing a value — directly through a WhatsApp conversation, without the person needing to access AgFlow. Each configuration is a message-template state machine: with every user response, the conversation advances to the next template, until it reaches a final state.

The conversation configuration depends on other configurations on the same phase: the WhatsApp number that sends the messages (phone-config) and, when the conversation is triggered by document generation, the auto-document configuration (auto-document-config) and the linked document template.

Endpoints in this domain

Method	Path	Description
`GET`	`/v1/flows/{flowId}/phases/{phaseId}/conversation-config`	Retrieves the phase's conversation configuration
`POST`	`/v1/flows/{flowId}/phases/{phaseId}/conversation-config`	Creates the phase's conversation configuration
`DELETE`	`/v1/flows/conversation-config/{id}`	Removes the conversation configuration

Naming note: the creation/lookup path uses {flowId} for the flow parameter. The deletion path, however, uses only {id}, without {flowId} or {phaseId} — the configuration is identified globally by its own identifier.

There is no update (PUT) — the pattern is remove and recreate

There is no dedicated update endpoint for conversation-config. A PUT attempt on the phase path is not recognized by the API. To update an existing configuration — for example, to change the referenced document template or adjust a routing rule — the correct pattern is:

Remove the current configuration via DELETE /v1/flows/conversation-config/{id}.

Create a new one via POST /v1/flows/{flowId}/phases/{phaseId}/conversation-config, with the already-updated payload.

A POST call on a phase that already has a configuration returns an error stating the preexisting configuration, and the body of that error includes the identifier of the existing configuration — which can also be obtained via GET before starting the update process.

Recreating the configuration generates a new conversation identifier. This does not affect automation: finalized-auto-document triggers with the start-conversation action are tied to the phase, not to the configuration identifier, and remain valid after recreation.

State machine structure

The creation payload is 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 based on the status of the document automatically generated on the phase.

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, where the user's response is stored, the identifier of the template approved on WhatsApp Meta, the routing rules that point to the next template based on the response received, and, optionally, an alternate template (fallback) for scenarios such as a failure generating the document.

Important behaviors

Looking up a phase without a conversation configuration returns a 404 error — expected behavior, not a failure.

The values used to compare the user's response (target) must match EXACTLY the buttons defined on the template approved on WhatsApp Meta, including accents and case — mismatches cause a silent routing failure, with no API error.

When capturing a monetary response, the matching rule must use condition: "type" (checks whether the response is a monetary value) — never condition: "eq", which would compare the response against the literal string "money" and never find a match.

The conversation is only actually started if there is, on the same phase, a trigger of type finalized-auto-document with the start-conversation action. The conversation configuration alone, without that trigger, does not start anything.

We always 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.

Removing a conversation configuration (DELETE) does not disable the finalized-auto-document trigger associated with the phase; it remains active, but with no effect, until a new configuration is created.

Conversation — Overview

Endpoints in this domain#

There is no update (PUT) — the pattern is remove and recreate#

State machine structure#

Important behaviors#

Endpoints in this domain

There is no update (PUT) — the pattern is remove and recreate

State machine structure

Important behaviors