POST
/
api
/
v1
/
campaign
/
otp-flow
OTPflow API
curl --request POST \
  --url https://api.zixflow.com/api/v1/campaign/otp-flow \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {
      "channel": "<string>",
      "timeout": 123,
      "messageType": "<string>",
      "data": {}
    }
  ],
  "webhookurl": "<string>",
  "callbackData": "<string>"
}'
We’ve worked with hundreds of clients, and one common question is: How can we achieve 100% message delivery? Over the years, we’ve optimized every channel using AI-powered real-time dynamic routing and automated retries at Zixflow. While we outperform competitors in delivery rates, achieving 100% delivery isn’t always possible due to limitations in operator infrastructure, which is beyond our control. However, ensuring critical use cases like OTPs or mandatory messages reach users on time is essential, as missed messages can lead to lost business opportunities. To solve this, we’re introducing the world’s first OTPflow API. With this, we can achieve 99.99% delivery for valid numbers. Here’s how it works:
  • The system uses AI to optimize delivery across all channels with priority routing, not just at Zixflow but also at the operator level.
  • If a message fails or isn’t delivered in time, it automatically switches to another channel.
  • You can pass potential messages to all activated channels in your account, and the system will handle delivery optimization on autopilot.
This approach ensures faster and more reliable message delivery, reducing drop-offs and maximizing business impact.

​
How does it work?

  1. Sequential Delivery: Messages are sent in the defined order (e.g., SMS → WhatsApp → RCS). You can customize it on request.
  2. Timeout Handling:
  • If a message is delivered within the timeout window, the next steps are skipped.
  • If a message fails, it will switch to the next channel (e.g., if the message fails within 2 seconds, it will move to the next channel immediately without waiting for the timeout).
  • If we don’t receive a delivery report (success or failure) within the timeout window, it will switch to the next channel.
  1. Multi-Channel Reliability: Combining SMS, WhatsApp, and RCS ensures high delivery success.

​
Example Flow

  • Scenario: Send via SMS (timeout 10s), then WhatsApp (timeout 10s), then RCS (timeout 10s).
  • Process:
    1. SMS message sent first.
    2. If delivered, stops. If failed or no response, moves to WhatsApp.
    3. Same logic applies to RCS.

​
Benefits:

  • Higher Delivery Rates: Ensures at least one channel succeeds.
  • Efficient Use of Resources: No redundant attempts and reduces wait-time for users.
  • Customizable: Control timeouts and delivery order.
  • Save Costs: Instead of retrying on the same channel multiple times or sending messages to all channels simultaneously, this approach triggers the second channel only if the first one fails, reducing unnecessary usage and cost.
  • Real-time updates: When a switch occurs to the next channel, we can trigger a webhook to your system. This allows you to optimize the user experience. For example, if SMS couldn’t be delivered, we’ll notify you that the message has been sent via the next channel ex. WhatsApp.

​
Limitation:

  1. Timeout Limitation: The maximum timeout window for all channels combined is 5 minutes (300 seconds). After this, the entire request is skipped.
  2. Total Messages: In one request, you can send a minimum of 1 message and a maximum of 5 messages. You can use the same channel multiple times or use different channels as per your need (e.g., SMS → SMS → WhatsApp → RCS → Email).
  3. Fallback Channels: In some cases, delivery reports may arrive late, even if the message was delivered on time. Despite optimizations, this may result in messages being sent on multiple channels if the report isn’t received within the timeout window.
How to Test: To check if all information or messages are being sent correctly, set the timeout to 0. This will trigger all messages at once, allowing you to verify if they’re received on the test number from all channels. Once confirmed, increase the timeout for the production environment. We recommend adding a 10-second delay between each message for optimal performance. No Additional Cost: There are no extra charges for this service. You’ll only be charged for the messages sent, based on the pricing of each channel.
Number Verification: For OTP or number verification, use only SMS, WhatsApp, and RCS. Avoid using email, as users may receive the OTP via email, but it won’t verify the phone number.

​
Request Body Parameters

​
Root Fields

FieldTypeDescriptionRequired
messagesarrayA list of message objects to be sent. It explained below.Yes
webhookurlstringImportant: Pass the webhook URL if you want to display a message to the user when a channel switch happens. eg. If a message switches from SMS to RCS, a webhook will be triggered. You can ignore if you don’t want it.

This is not a message delivery webhook. That you need to pass it only in the respective message body. The report URL is separate and used for reporting purposes like delivered.		No
callbackDatastringMetadata or identifiers passed for callbacks.No

​
Message Object

Each message object in the messages array contains the following fields:
FieldTypeDescriptionRequired
channelstringThe channel through which the message is sent (e.g., sms/whatsapp/rcs/email).Yes
timeoutnumberTimeout value for the message in seconds. it range from 0-300.Yes
messageTypestringType of the message. Empty for email and sms channel. For rcs values can be text, message, video, audio, document, template. For whatsapp value can be template, custom.Yes
dataobjectThe message data containing detailed information with respective channel.Yes

​
Message Data Object

The data object contains the following api request body payload:
ChannelMessage TypePayload
Send SMSsmsData Payload
Send Whatsapp TemplatewhatsapptemplateData Payload
Send Direct Whatsapp MessagewhatsappcustomData Payload
Send RCS Text MessagercstextData Payload
Send RCS Image MessagercsimageData Payload
Send RCS Video MessagercsvideoData Payload
Send RCS Audio MessagercsaudioData Payload
Send RCS Document MessagercsdocumentData Payload
Send RCS Template MessagercstemplateData Payload
Send EmailemailData Payload
If you’re using WhatsApp for authentication or OTP, we recommend using the WhatsApp Authentication template.

​
Request Body Schema

​
messages
array
required
A list of message objects to be sent. It explained below.
​
webhookurl
string
The URL where message success or failed webhook will be sent with index.
​
callbackData
string
Metadata or identifiers passed for callbacks.

​
Example Request

curl -X POST \
  https://api.zixflow.com/api/v1/campaign/otp-flow \
  -H 'Content-Type: application/json' \
  -d '{
    "webhookurl": "https://example.com/webhook",
    "callbackData": "order123",
     "messages": [
        {
            "channel": "sms",
            "timeout": 0,
            "messageType": "",
            "data": {
                "senderId": "SAMPLE",
                "route": "promotional",
                "number": "919876543210",
                "message": "Boost efficiency with ZixFlow! 🚀 Streamline workflows & save time. Start now at www.zixflow.com or call 123-456-7890. Your success, simplified!",
                "dltTemplateId": "1234",
                "dltEntityId": "1234",
                "isFlash": false,
                "submissionStatus": true,
                "reportURL": "https://example.com/webhook"
            }
        },
        {
            "channel": "whatsapp",
            "timeout": 0,
            "messageType": "template",
            "data": {
                "to": "919876543210",
                "phoneId": "test-phone-id",
                "templateName": "marketing_sample_2",
                "language": "en",
                "variables": {
                    "<variable_key>":"<variable_value>
                },
                "source": "OTPflow",
                "linkWithRecord": false,
                "reportURL": "https://example.com/webhook"
            }
        },
        {
            "channel": "rcs",
            "timeout": 0,
            "messageType": "text",
            "data": {
                "to": "919876543210",
                "botId": "test-bot-id",
                "text": "Boost efficiency with ZixFlow! 🚀 Streamline workflows & save time. Start now at www.zixflow.com or call 123-456-7890. Your success, simplified!",
                "source": "OTPflow",
                "linkWithRecord": false,
                "reportURL": "https://example.com/webhook"
            }
        },
        {
            "channel": "email",
            "timeout": 0,
            "messageType": "",
            "data": {
                "to": [
                  "text@sample.com"
                ],
                "subject": "Boost efficiency with ZixFlow!",
                "from": "mailer@sample.us",
                "fromName": "Zixflow Marketing",
                "bodyHtml": "<h1>Boost efficiency with ZixFlow! 🚀 Streamline workflows & save time. Start now at www.zixflow.com or call 123-456-7890. Your success, simplified!</h1>",
                "trackClicks": true,
                "trackOpens": true,
                "replyToEmail": "support@sample.com",
                "attachments": [],
                "replyToName": "Support",
                "bodyText": "Boost efficiency with ZixFlow! 🚀 Streamline workflows & save time. Start now at www.zixflow.com or call 123-456-7890. Your success, simplified!",
                "callbackUrl": "https://example.com/webhook"
            }
        }
    ]
}'

​
Response

​
Success Response

Status Code: 200 OK 
{
  "status": "success",
  "message": "Message sent successfully.",
  "eventId": "ca64ad45-937d-45b4-9c5d-9b1d93bf2302",
  "requestIds": [
    "ca64ad45-937d-45b4-9c5d-9b1d93bf2303",
    "ca64ad45-937d-45b4-9c5d-9b1d93bf2304",
    "ca64ad45-937d-45b4-9c5d-9b1d93bf2305",
    "ca64ad45-937d-45b4-9c5d-9b1d93bf2306"
  ]
}

​
Error Response

Status Code: 400 Bad Request 
{
  "status": "error",
  "message": "Invalid request payload."
}

​
Notes

  • Ensure the webhook URL is accessible and capable of handling incoming responses. Our system makes only one attempt, and if your webhook URL is down, the request response cannot be recovered.
  • Timeout values should be set based on the use case to prevent excessive delays.