Messaging — Overview
Prerequisite: the tenant's WhatsApp Business phone number must be registered (phone configuration) before creating any messaging configuration that uses the WhatsApp channel on a phase. Without that registration, creating a rule with a WhatsApp channel fails because the referenced number cannot be found.
Endpoints in this domain
| Method | Path | Description |
|---|---|---|
POST | /v1/flows/{flowId}/phone-config | Registers the flow's WhatsApp Business phone |
GET | /v1/flows/{flowId}/phases/{phaseId}/messaging-config | Retrieves the phase's messaging configuration |
POST | /v1/flows/{flowId}/phases/{phaseId}/messaging-config | Creates the phase's messaging configuration |
PUT | /v1/flows/{flowId}/phases/{phaseId}/messaging-config | Updates the configuration's contacts and template variables |
POST | /v1/flows/{flowId}/phases/{phaseId}/messaging-config/rules | Adds firing rules to the configuration |
PUT | /v1/flows/{flowId}/phases/{phaseId}/messaging-config/rules/{ruleId} | Updates a specific rule |
DELETE | /v1/flows/messaging-config/{id} | Removes the phase's messaging configuration |
Naming note: the deletion endpoint does not take the flow or phase identifier in the path — only the identifier of the messaging configuration itself ( id), previously obtained from the phase's configuration query.
Configuration structure
contacts.default[] holds fixed (static) contacts; contacts.fields[] holds dynamic contacts, resolved at runtime from a card or start-form field.{{1}}, {{2}}...) and shared across all channels of the rules.channels[]) with conditions (conditions[]).Recommended configuration sequence
1.
POST .../phone-config), if it does not already exist for the company.2.
POST .../messaging-config), with the contacts and, if needed, the template variables.3.
POST .../messaging-config/rules).4.
Important behaviors
rules[] remains inert — at least one rule is required for a message to actually be sent.name, not type — for example, {name: 'whatsapp', templateId: '...', setup: {phoneId: '...'}}.phone-config) is tied to the company (tenant), not to an individual flow, and the call is idempotent: if the phone already exists, the API responds successfully indicating that the record already existed.contacts.default is required even when there is no fixed contact — in that case, send an empty array.contacts.fields[] needs a non-empty description — omitting it or sending it blank returns a validation error.fields field, at the configuration's root level, is also required even when empty — send an empty array when the message does not use dynamic variables in its body, such as in fixed approval or rejection notifications.PUT of the configuration), the type field of contacts.fields[] accepts a more restricted set of values than on creation — always use 'default' for the standard contacts (name, phone, email).contacts.default[] must have a non-empty phone, even for contacts that should receive the message by email only; in that case, use a fictitious phone number in a valid format.fields[] needs the required field explicitly set (true or false).PUT .../rules/{ruleId}), the rule identifier goes only in the URL — including it in the request body as well returns a validation error.setup.phoneId pointing to a previously registered phone; its absence returns a 404 error.Modificado em 2026-07-28 20:38:32