Dynamic API to trigger Chat Flow workflows
Use this guide to create a Dynamic API workflow, configure a route, and test the route using an API testing tool. Dynamic API enables external systems to trigger Chat Flow workflows through incoming payloads and is used for workflow-driven customer engagement.
Before you begin • Confirm that Dynamic API is enabled for your account.
• If Dynamic API is not yet available, log a request with Clickatell Support to provision the channel for you.
• Confirm that any WhatsApp templates used in the workflow are pre-approved.
• Have an API testing tool available because Dynamic API workflows do not have a flow preview mode.
How to set up a Dynamic API Workflow:
Build the workflow
Select Dynamic API flow under Flows from the menu on the left. A Start node and arrow will automatically appear on your canvas as the starting point for your flow.
2. Build the workflow using the required action nodes. The workflow should reflect the business event that will trigger it, and the customer journey that should follow. Examples include:
· Send a WhatsApp template.
· Call an external API.
· Evaluate a business condition.
· Set or map variables.
· Route the journey to the next workflow step.
Select a node on the canvas to configure/edit it in a panel on the right.
Repeat this process as required to build out your workflow. Remember to save your changes to each node.
There is a special end node to end the flow session. When you are at the end of your workflow, add the API end node.
Dynamic API workflows are API-driven and are intended to trigger workflow execution. They are not designed as user-facing conversational entry points.
Set up the routing
Before a route for a Dynamic API can be added it needs to be onboarded for the entity. To activate a Dynamic API channel, you will need to log a ticket with our Support team.
Once the Dynamic API channel is added to the entity a new channel tab will appear under Chat Flow Routing.
Select Routing from the panel on the left.
Configure the relevant fields. You are presented with several options to customize the endpoint.
HTTP METHOD
Select the method supported by the route, such as GET, POST, PUT or DELETE.
Allowed IP Address Sources
This is a ';' delimited list of IP addresses that should be allowed to call your Dynamic API, e.g. 10.0.0.1;10.0.0.2. - If you want to allow any IP address access you can use 0.0.0.0/0 for IPv4 and ::/0 for IPv6 e.g. 0.0.0.0/0;::/0 to match any IPv4 and IPv6 address.
Asynchronous toggle
This is set to Synchronous by default. To add an asynchronous route/request, enable the toggle. Note that for asynchronous requests there is no feedback on the response, only acknowledgement that the request was received and processed.
Flow Selection
Select the workflow and step that should execute when the endpoint is called. Save the route.
Generated Endpoint URL
Once the route is saved, Chat Flow will generate a unique URL for your route.
Generated API Token
A unique API token will also be generated.
Common use cases
A common Dynamic API use case is to initiate a WhatsApp conversation using a pre-approved template through the Send Template node.
1. Add a Send Template node to the Dynamic API workflow.
2. Select the approved WhatsApp template.
3. Configure the required template variables.
4. Connect the Send Template node to the relevant next step in the workflow.
5. Save and publish the workflow.
6. Trigger the workflow through the Dynamic API route.
Key features
Send pre-approved WhatsApp templates to users.
Support for interactive templates with buttons.
Configure next steps based on user button selection.
API Examples
Below are sample requests for sending WhatsApp templates via the Dynamic Flow API. All sensitive values are masked using the below placeholders. Replace the placeholders with your actual values before use.
1. API_ID = API_ID
2. api-key = API_Key
3. Authorization = WhatsApp_API_Key
4. Recipient Number= Mobile_Number
5. Recipient Name = First_Name
Security and Best Practices
· Validate MSISDN format and country codes, for example: 27821234567
· Verify that templates are pre-approved on WhatsApp before sending.
· Limit additional postback data to under ~50 characters.
· Maximum quick reply buttons are 10.
Environment URLs
Please find the Sandbox and Production URLs below.
· Sandbox URL: https://flow-sandbox-api.clickatell.com/api/<API_ID>
· Production URL: https://flow-api.clickatell.com/dynamic/<API_ID>
Uploading Media Files
To send a template with media (image, video or document), please upload the media file before sending the template.
Media upload to multiple users (broadcast-safe)
Use case: Used to send non-user-specific, non-sensitive media.
Examples:
· Promotional images
· Company logo
· Marketing banners
Behavior:
Media can be reused across many recipients
broadcastAllowed=true must be set
fileName
Name of the uploaded file
broadcastAllowed=true
Enables reuse across multiple users
Authorization
WhatsApp API key
Content-Type
MIME type of the file
--data-binary
Path to the local file
Media upload to a single user (sensitive or personalised)
Use case: Used to send user-specific or sensitive media.
Examples:
· Boarding pass
· Payslip
· Invoice
· Personal documents
Behavior:
Media is locked to one WhatsApp number
Cannot be reused for other recipients
Media upload – example response
Broadcast upload
For reusable marketing media
Single-user upload
For sensitive or personalized files
fileId required
Mandatory for all media headers
Upload first
Media must exist before template send
WhatsApp Template Options
Template with Text Only
· WhatsApp Template example
Name: order_update_text
Body: Hello {{1}}, your order {{2}} is ready for collection.
Template with Quick Reply Buttons
WhatsApp Template example
Name: confirm_action
Body: Would you like to proceed?
Buttons: Yes | No | Talk to agent
Template with Media and 3 Quick Reply Buttons
WhatsApp Template example
Name: delivery_status
Header: Image
Body: Hi {{1}}, your order {{2}} is ready for delivery..
Buttons: Track Order | Reschedule | Help
Template with Text Header
WhatsApp Template example
Name: appointment_reminder
Header: Text → Appointment Reminder
Body: Hi {{1}}, your appointment is on {{2}}.
Template with Image Header
WhatsApp Template example
Name: image_header_notice
Header: Image
Body: Please review the information below.
Template with Video Header
WhatsApp Template example
Name: video_intro
Header: Video
Body: Watch this short video for more details.
Template with Document (PDF) Header
WhatsApp Template example
Name: terms_and_conditions
Header: Document
Body: Please review the attached terms and conditions.
Template with Location Header
WhatsApp Template example
Name: store_location
Header: Location
Body: Visit our nearest branch using the map below.
Template with Phone and URL Call-to-Action Buttons
WhatsApp Template example
Name: support_options
Body: Choose one of the options below.
Buttons: 1. Website URL: contact/contact_sales/ 2. Phone Number: +27821234567
Last updated