Flow Design Guide

Design interactive WhatsApp Flows in ChatYug without writing JSON. This guide covers why and how to use Flows in ChatYug, every designer component and its properties, starter templates, and what to do when Meta rejects a publish.

Why use Flow Design in ChatYug

WhatsApp Flows are Meta’s native in-chat forms (checkout, leads, surveys, appointments, support). ChatYug’s Flow Design module lets non-technical operators:

• Build screens with drag-and-drop (n8n-style canvas).
• Approve (= publish on Meta) from the same screen.
• Test Send the published flow to any WhatsApp number.
• Keep advanced JSON only as an escape hatch.

This is not the Chatbot keyword builder (Automation). Commerce Flows collect structured answers inside WhatsApp; chatbot flows automate replies with a different node engine.

How to use a Flow in ChatYug (end-to-end)

1. Open WhatsApp Messaging → Flow Design (or Commerce → Flow Design).
2. Click Create from template, choose a use case, and create the draft on Meta.
3. In the designer: add/edit screens and components, connect screens with the purple port, then Save.
4. Click Approve to publish on Meta (DRAFT → PUBLISHED). If Meta rejects, read the rejection panel (reason + fixes).
5. Click Test Send and enter a number with country code (e.g. 919876543210).
6. Open Analytics on the flow card to see sends and submissions (phone, name, time, payload) and export Excel.

Production paths after publish

Create, list, and count flows

• Create: Flow Design → Create from template (or External API POST /commerce/flows).
• List: Flow Design home shows all drafts/published for the selected WABA; header strip shows Total / Draft / Published counts.
• API list: GET /api/external/commerce/flows or MCP list_commerce_flows.

Analytics (from each flow card)

Analytics live inside Flow Design — not as a separate Messaging hub card. Each flow card shows mini send/submit counts and an Analytics button.

• Opens a per-flow report: time, event type (send / submit), phone, name (when present), interaction payload summary.
• Filters: date range, phone, event type.
• Export Excel downloads the filtered set (portal or GET /api/commerce/flows/analytics/export?flowId=). Each form answer becomes its own column (field labels from the flow when available); there is no combined Payload blob column.
• Designer top bar also has Analytics for the open flow.

V1 records Test Send / API sends and customer completions. Meta per-screen open funnels are not available in ChatYug today.

Send a flow and receive filled answers

Send (portal)

1. Publish with Approve (status must be PUBLISHED).
2. Test Send → enter digits with country code (e.g. 917016793529), or from Start Chat use the green sitemap button to send a published flow while the 24-hour window is open.
3. Conversations show an outbound Flow sent bubble; Analytics logs a send row.

Send (API / MCP)

POST /api/external/messages/flow or MCP send_commerce_flow_message. Pass your own flowToken so you can match the reply later. Details: Commerce Flows API.

Receive

Customer completion arrives as webhook interactive.type = nfm_reply. Parse response_json; keys = designer field Names; include flow_token for correlation. ChatYug also stores a readable Flow response bubble in Conversations and a Flow Analytics submit event.

const answers = JSON.parse(nfm_reply.response_json || '{}');
// answers.flow_token === the token from send
// answers.<field_name> === what the customer typed/selected

Full parse samples: Receive filled data.

Pre-publish checklist (ChatYug validates on Approve)

• Terminal screens have a Footer
• Unique UPPER_SNAKE_CASE screen IDs
• Unique lowercase field names across the whole flow
• ≥2 options on Dropdown / Radio / Checkbox
• HTTPS image URLs
• Navigate targets exist; data_exchange only if Commerce endpoint is configured

Use the Variables panel for ${form.field_name} (answers) and ${data.key} (init / endpoint data). Preview shows a phone frame of the selected screen; published flows may also show Meta’s preview_url.

Designer steps (canvas model)

• Screen = a canvas node (one WhatsApp Flow screen).
• Edge = routing from one screen to another (drag the purple out-port).
• Components live inside the selected screen (left palette → drop or click).
• Screen properties: ID (UPPER_SNAKE_CASE), Title, Terminal flag.
• Terminal screens must end with a Footer (Meta requirement).
• Top bar: Save · Approve · Test Send · Analytics · JSON · Help.

Component quick index

Component reference

TextHeading

When: Start every screen with a clear title.

Step: Select screen → add Heading from Text palette → set text in the inspector.

Properties: text (required).

TextSubheading

When: Secondary title under the heading.

Step: Add Subheading → edit text.

Properties: text.

TextBody

When: Instructions or dynamic values such as order total.

Step: Add Body → set text. You may use ${data.order_total} when screen data provides that field (checkout).

Properties: text.

TextCaption

When: Small hints or legal notes under fields.

Properties: text.

RichText

When: Light formatting (e.g. **bold**) without adding an input.

Properties: text.

TextInput

When: Name, email, phone, PIN, short answers.

Step: Add Text Input → set Label, unique Name, Required, Input type (text, number, email, phone, etc.).

Properties: label, name (unique), required, input-type.

Prevent errors: Never reuse the same name on two fields.

TextArea

When: Comments, issue descriptions, notes.

Properties: label, name, required.

Dropdown

When: Single choice from a short list (payment method, issue type).

Step: Add Dropdown → set Label / Name → enter options as comma-separated titles.

Properties: label, name, required, options → Meta data-source.

RadioButtonsGroup

When: Visible single-choice list (ratings).

Properties: same pattern as Dropdown (comma-separated options).

CheckboxGroup

When: Allow multiple selections.

Properties: label, name, required, options.

DatePicker

When: Appointment or delivery date.

Properties: label, name, required.

CalendarPicker

When: Calendar-style date UI is preferred.

Properties: label, name, required.

OptIn

When: Consent / terms agreement.

Properties: label, name, required (mark required for mandatory consent).

Image

When: Show a product or brand image.

Step: Add Image → set public https:// src URL.

Prevent errors: Meta must be able to fetch the URL; avoid private or HTTP-only links.

ImageCarousel

When: Multiple images on one screen.

Step: One HTTPS URL per line in the inspector.

PhotoPicker

When: Customer uploads a photo (proof, KYC).

Properties: label, name, max file size (KB). Do not use Meta required on this component — ChatYug strips it on save; use min-uploaded-photos if Meta requires a minimum.

Answers: Submitted photos appear in Flow Analytics Attachments (thumbnails) and via External API / MCP as chatyug_url on the field.

DocumentPicker

When: Customer uploads a document (PDF, etc.). If the file MIME is video/*, Analytics treats it as video for preview/download — there is no separate VideoPicker in WhatsApp Flows.

Properties: label, name, max file size (KB). Same rule: no required property (stripped on normalize).

Answers: Appear in Flow Analytics Attachments and via API/MCP (list_flow_analytics, get_flow_media).

EmbeddedLink

When: Link to terms or a help page.

Properties: link text, URL.

NavigationList

When: Menu that jumps to other screens.

Step: Enter rows as Title|SCREEN_ID (one per line). SCREEN_ID must exist on the canvas.

Footer (CTA)

When: Every interactive screen needs a bottom button. Terminal screens must have a Footer.

Actions:

• complete — close the flow (simple thank-you / done).
• data_exchange — send form fields to ChatYug (checkout / endpoint flows). Requires Commerce endpoint + RSA when Meta health-checks.
• navigate — go to another screen (set Next screen ID or connect ports).

Properties: button label, action, optional next screen.

Multi-screen variables

On a single screen, reference answers with ${form.field_name} (the field must exist on that same screen).

On a later screen, values from an earlier screen must use ${data.field_name}. Pass them in the previous screen’s Footer when action is navigate, for example:

"payload": { "interest": "${form.interest}" }

Then on the next screen body text can say You selected: ${data.interest}. Using ${form.interest} on screen 2 when interest is only on screen 1 is a common cause of Meta publish error 139002 / 4016011.

Publish readiness panel

The designer shows a Publish readiness strip above the canvas. It updates as you edit (debounced). When blocking issues exist, Approve is disabled until you fix them.

Templates

When Meta rejects Approve / Publish

ChatYug shows a rejection panel with three parts: What Meta said, What this means, and How to fix / prevent. The same guidance is summarized below.

On the Flow Design list, drafts with stored validation_errors show Rejected by Meta — view details so you can reopen the same panel without republishing.