> For the complete documentation index, see [llms.txt](https://help.clickatell.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.clickatell.com/developers-documentation/dynamic-api-to-trigger-chat-flow-workflows.md).

# Dynamic API to trigger Chat Flow workflows

Use this guide to create a[ Dynamic API workflow](/chat-flow/workflow-management/create-new-flow/dynamic-api-workflows.md), 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.

{% hint style="info" %}
**Before you begin**\
\
• Confirm that Dynamic API is enabled for your account. 

• If Dynamic API is not yet available, [log a request](#before-you-begin) 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.
{% endhint %}

#### **How to set up a Dynamic API Workflow:**

**Build the workflow**

1. 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.

<figure><img src="/files/WqjxQ6p8VLbquCX8Zzbz" alt=""><figcaption></figcaption></figure>

\
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.

3. Select a [node ](https://guides.clickatell.com/flow/workflow-management/create-new-flow#nodes-the-building-blocks-of-your-workflow)on the canvas to configure/edit it in a panel on the right.
4. Repeat this process as required to build out your workflow. Remember to save your changes to each node.
5. 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.

{% hint style="info" %}
Dynamic API workflows are API-driven and are intended to trigger workflow execution. They are not designed as user-facing conversational entry points.
{% endhint %}

**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](https://www.clickatell.com/contact-support/) with our Support team.

Once the Dynamic API channel is added to the entity a new channel tab will appear under Chat Flow Routing.

<figure><img src="/files/7KxaWd9pbo7xU0ZAHVoX" alt=""><figcaption></figcaption></figure>

1. Select Routing from the panel on the left.
2. Configure the relevant fields. You are presented with several options to customize the endpoint.

| Setting                        | Description                                                                                                                                                                                                                                                                               |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **HTTP METHOD**                | Select the method supported by the route, such as GET, POST, PUT or DELETE.                                                                                                                                                                                                               |
| **Allowed IP Address Sources** | <p>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.<br>- 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.<br></p> |
| **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**        | <p></p><p>A unique API token will also be generated.</p>                                                                                                                                                                                                                                  |

<figure><img src="/files/MihjlyUXnfFJaDmjPKeB" alt=""><figcaption></figcaption></figure>

#### **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](/chat-flow/action-nodes/send-template.md) 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**

* &#x20;Send pre-approved WhatsApp templates to users.
* &#x20;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.

&#x20;

#### Environment URLs

Please find the Sandbox and Production URLs below.

·        Sandbox URL: [https://flow-sandbox-api.clickatell.com/api/\<API\_ID](https://flow-sandbox-api.clickatell.com/api/%3cAPI_ID)>

·        Production URL: [https://flow-api.clickatell.com/dynamic/\<API\_ID](https://flow-api.clickatell.com/dynamic/%3cAPI_ID)>

#### Uploading Media Files

&#x20;

{% hint style="info" %}
To send a template with media (image, video or document), please upload the media file before sending the template.
{% endhint %}

**Media upload to multiple users (broadcast-safe)**

&#x20;Use case: Used to send non-user-specific, non-sensitive media.

&#x20;Examples:

·        Promotional images

·        Company logo

·        Marketing banners

&#x20;Behavior:

Media can be reused across many recipients

broadcastAllowed=true must be set

<figure><img src="/files/AbcSts7H9l8FJ0Sy72uw" alt=""><figcaption></figcaption></figure>

| Parameter             | Description                         |
| --------------------- | ----------------------------------- |
| 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)**

&#x20;Use case: Used to send user-specific or sensitive media.

&#x20;Examples:

**·**  Boarding pass

·        Payslip

·        Invoice

·        Personal documents

&#x20;Behavior:

* Media is locked to one WhatsApp number
* Cannot be reused for other recipients

<figure><img src="/files/e73L2fvD4y7uXNVlJ2M1" alt=""><figcaption></figcaption></figure>

**Media upload – example response**

<figure><img src="/files/STfyWoixAnc7XKccDldU" alt=""><figcaption></figcaption></figure>

| Rule               | Explanation                           |
| ------------------ | ------------------------------------- |
| 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

&#x20;                   Name: order\_update\_text

&#x20;                   Body: Hello {{1}}, your order {{2}} is ready for collection.

<figure><img src="/files/0ZwJUeb0Fttehmuv1mnR" alt=""><figcaption></figcaption></figure>

#### Template with Quick Reply Buttons

* WhatsApp Template example

&#x20;                     Name: confirm\_action

&#x20;                     Body: Would you like to proceed?

&#x20;                     Buttons: Yes | No | Talk to agent

<figure><img src="/files/sNxykPP3ohG9NCd6pUc2" alt=""><figcaption></figcaption></figure>

#### Template with Media and 3 Quick Reply Buttons

&#x20;

* WhatsApp Template example

&#x20;                Name: delivery\_status

&#x20;                 Header: Image

&#x20;                 Body: Hi {{1}}, your order {{2}} is ready for delivery..

&#x20;                 Buttons: Track Order | Reschedule | Help

<figure><img src="/files/2hrbuGfbGPpi7Fh15q8N" alt=""><figcaption></figcaption></figure>

#### Template with Text Header

* WhatsApp Template example

&#x20;                        Name: appointment\_reminder

&#x20;                        Header: Text → Appointment Reminder

&#x20;                        Body: Hi {{1}}, your appointment is on {{2}}.

<figure><img src="/files/AqzLwtyLt0STgRyWgblm" alt=""><figcaption></figcaption></figure>

#### Template with Image Header

* WhatsApp Template example

&#x20;                  Name: image\_header\_notice

&#x20;                  Header: Image

&#x20;                  Body: Please review the information below.

<figure><img src="/files/0oR64iSzSOPYScP7c3wq" alt=""><figcaption></figcaption></figure>

#### Template with Video Header

* WhatsApp Template example

&#x20;                         Name: video\_intro

&#x20;                         Header: Video

&#x20;                         Body: Watch this short video for more details.

<figure><img src="/files/mb4DPGQdAjJUcTgmFbqY" alt=""><figcaption></figcaption></figure>

#### Template with Document (PDF) Header

* WhatsApp Template example

&#x20;                       Name: terms\_and\_conditions

&#x20;                       Header: Document

&#x20;                      Body: Please review the attached terms and conditions.

<figure><img src="/files/Xoxffgo54BXXImZ6idVB" alt=""><figcaption></figcaption></figure>

#### Template with Location Header

* WhatsApp Template example

&#x20;                           Name: store\_location

&#x20;                           Header: Location

&#x20;                          Body: Visit our nearest branch using the map below.

<figure><img src="/files/xlhiNlF95graFAYZeCaR" alt=""><figcaption></figcaption></figure>

#### Template with Phone and URL Call-to-Action Buttons

* WhatsApp Template example

&#x20;                              Name: support\_options

&#x20;                              Body: Choose one of the options below.<br>

Buttons:\
1\. Website URL: contact/contact\_sales/\
2\. Phone Number: +27821234567

<figure><img src="/files/1D44O0aBYKLlr0Wxd4fm" alt=""><figcaption></figcaption></figure>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://help.clickatell.com/developers-documentation/dynamic-api-to-trigger-chat-flow-workflows.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.