ChatMaxima Docs

Build a Dynamic Data Flow in WhatsApp

Build a WhatsApp Dynamic Data Flow in ChatMaxima with chained dependent lists populated live from your API, such as Category to Product or Doctor to Date to Time.

Overview

A Dynamic Data Flow is a WhatsApp Flow whose lists are populated live from your own API. Each step is a list, and the customer's choice in one step decides what the next step shows. The flow walks the customer through a chain of dependent selections.

Typical examples:

  • Healthcare - Doctor, then available Date, then available Time slot.
  • E-commerce - Category, then Product.
  • Services - Branch, then Service, then Staff member.

Unlike the Form Builder, the options are not entered by hand. When the customer moves to the next screen, WhatsApp calls a secure ChatMaxima endpoint, which calls your API and returns the next list. Nothing is hardcoded, so the same flow works for any chain of steps you define.

How It Works

  1. The customer opens the flow and sees the first step's list.
  2. They make a selection.
  3. WhatsApp sends that selection to ChatMaxima's encrypted endpoint.
  4. ChatMaxima calls your API for the next step, passing the earlier selections.
  5. The next list appears. This repeats until the final summary screen.

Prerequisites

Before you begin, ensure you have:

  • A connected WhatsApp account - a WhatsApp Cloud API number linked to ChatMaxima.
  • An API for each step - an HTTPS endpoint that returns a JSON list of options.
  • The encryption key set up - a one-time setup per WhatsApp account, described below.

Note: Dynamic Data Flows are endpoint-driven, so WhatsApp requires an encryption key. You must complete the encryption setup before you can save a dynamic flow.

Step 1: Start a Dynamic Data Flow

  1. Go to Campaigns then WhatsApp Flows and click Create Flow.
  2. Enter a Flow Name and choose a Category.
  3. Set Flow Type to Dynamic Data Flow.

The builder switches to the Dynamic Steps view.

Step 2: Set Up the Encryption Key

A Dynamic Data Flow calls a ChatMaxima endpoint for each screen, and WhatsApp requires that channel to be encrypted.

  1. In the Endpoint Encryption card, click Set up Encryption Key.
  2. ChatMaxima generates an RSA key pair for the account and uploads the public key to Meta automatically.

This is a one-time action per WhatsApp account. Every dynamic flow on that account reuses the same key.

Step 3: Add Steps

Each step is one dependent list. Click Add Step and fill in the step editor.

Step Fields

FieldDescription
Step TitleThe screen heading, for example Select a Category
Step KeyA lowercase identifier, for example category, referenced later as {category}
List LabelThe label shown above the list
HTTP MethodGET or POST for the API call
API URLThe endpoint that returns this step's options
AuthenticationNone, Bearer Token, Basic Auth, or Custom Header

Passing Earlier Selections

To make a later step depend on an earlier one, put the earlier step's key in its API URL as a placeholder. ChatMaxima replaces it with the customer's selection at runtime.

https://api.example.com/products?category={category}

In this example, the product step's URL inserts the chosen category.

Step 4: Map the API Response

The step editor's Response Mapping section tells ChatMaxima how to read your API's JSON.

FieldDescription
List PathPath to the array in the response, for example data. Leave blank if the response is already an array
ID FieldThe field used as the option's value, for example id
Title FieldThe field shown as the option's main text, for example name
Description FieldAn optional secondary line, for example price

Dot notation is supported for nested fields, such as price.amount.

Step 5: Save and Publish

  1. Click Save Dynamic Flow. ChatMaxima generates the WhatsApp Flow screens from your steps and uploads them.
  2. Open the saved draft and click Publish.

The final screen is a summary that recaps every selection before the customer confirms.

Best Practices

  • Use clear step keys - short, lowercase, and meaningful, since they appear in URLs.
  • Return small lists - WhatsApp lists work best with a focused set of options.
  • Order steps from general to specific - for example Category before Product.
  • Test each API - confirm each endpoint returns the expected JSON before saving.

Troubleshooting

Save fails asking for the encryption key

  1. Open the Endpoint Encryption card.
  2. Click Set up Encryption Key and wait for confirmation.
  3. Save the dynamic flow again.

A step shows an empty list

  1. Check that the API URL is correct and reachable over HTTPS.
  2. Verify the List Path, ID Field, and Title Field match your API's JSON.
  3. Confirm any {placeholder} in the URL matches an earlier step's key.

A step cannot reach the API

  1. The API must be a public HTTPS endpoint. Internal or private addresses are blocked for security.
  2. Confirm the authentication details are correct.

Next Steps

On this page

OverviewHow It WorksPrerequisitesStep 1: Start a Dynamic Data FlowStep 2: Set Up the Encryption KeyStep 3: Add StepsStep FieldsPassing Earlier SelectionsStep 4: Map the API ResponseStep 5: Save and PublishBest PracticesTroubleshootingSave fails asking for the encryption keyA step shows an empty listA step cannot reach the APINext Steps