Checkout Flows

WhatsApp Flows collect shipping address and payment details after a cart order. This is the native checkout path — distinct from carousel Buy-button orders, which create orders with order_source carousel_campaign or carousel_inquiry without using the native cart UI.

List flows

GET /api/external/commerce/flows

Auth: Authorization: Bearer ck_<api_key> (required)

Response example

{
  "success": true,
  "flows": [
    {
      "id": 1,
      "meta_flow_id": "700000000000001",
      "name": "Demo Checkout Flow",
      "category": "SHOPPING",
      "status": "PUBLISHED"
    }
  ]
}

Create flow

POST /api/external/commerce/flows

Auth: Authorization: Bearer ck_<api_key> (required)

Request parameters

Field	Required	Type	Description
`name`	Yes	string	Flow display name
`category`	No	string	Meta flow category (default `SHOPPING`)
`flowJson`	No	object	WhatsApp Flow JSON definition (screens, fields, routing)

Response example

{
  "success": true,
  "message": "Flow created",
  "flow": {
    "id": 1,
    "meta_flow_id": "700000000000001",
    "name": "Demo Checkout Flow",
    "category": "SHOPPING",
    "status": "DRAFT"
  }
}

Publish flow

POST /api/external/commerce/flows/:flowId/publish

Auth: Authorization: Bearer ck_<api_key> (required)

:flowId is the internal ChatYug flow ID (not the Meta flow ID).

Response example

{
  "success": true,
  "message": "Flow published successfully"
}

Send flow message

POST /api/external/messages/flow

Auth: Authorization: Bearer ck_<api_key> (required)

Send an interactive Flow message to a customer. Use after a cart order if auto-send is disabled in portal settings, passing the flow_token from GET /orders/:orderId.

Request parameters

Field	Required	Type	Description
`phoneNumberId`	Yes	string	WhatsApp phone number ID to send from
`to`	Yes	string	Recipient phone in digits (e.g. `919876543210`)
`flowId`	No	string	Meta Flow ID. Falls back to the default checkout flow configured in portal Commerce Settings.
`flowToken`	No	string	Bind flow response to an order. Auto-generated if omitted.
`headerText`	No	string	Default `🛒 Ready to Checkout?`
`bodyText`	No	string	Default `Complete your order below.`
`footerText`	No	string	Default `Powered by ChatYug`
`ctaText`	No	string	Flow CTA button label (default `Proceed`)
`initialScreenId`	No	string	First screen to open (auto-resolved from stored flow JSON if omitted)
`initialScreenData`	No	object	Pre-fill data for the first screen (e.g. `order_id`, `product_name`, `order_total`)

Response example

{
  "success": true,
  "message": "Flow message sent",
  "flowToken": "flow_1720856400000_abc123",
  "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA=="
}

Code samples — send flow

curl -X POST https://chatyug.com/api/external/messages/flow \
  -H "Authorization: Bearer ck_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "100000000000001",
    "to": "919876543210",
    "flowId": "700000000000001",
    "flowToken": "order_1720856400000_abc123",
    "initialScreenData": {
      "order_id": "1001",
      "product_name": "Demo Cotton T-Shirt",
      "order_total": "INR 998.00"
    }
  }'

const axios = require('axios');

await axios.post('https://chatyug.com/api/external/messages/flow', {
  phoneNumberId: '100000000000001',
  to: '919876543210',
  flowId: '700000000000001',
  flowToken: 'order_1720856400000_abc123',
  initialScreenData: {
    order_id: '1001',
    product_name: 'Demo Cotton T-Shirt',
    order_total: 'INR 998.00'
  }
}, { headers: { Authorization: 'Bearer ck_your_api_key_here' } });

import requests

requests.post('https://chatyug.com/api/external/messages/flow', json={
    'phoneNumberId': '100000000000001',
    'to': '919876543210',
    'flowId': '700000000000001',
    'flowToken': 'order_1720856400000_abc123',
    'initialScreenData': {
        'order_id': '1001',
        'product_name': 'Demo Cotton T-Shirt',
        'order_total': 'INR 998.00'
    }
}, headers={'Authorization': 'Bearer ck_your_api_key_here'})

$client = new GuzzleHttp\Client();
$client->post('https://chatyug.com/api/external/messages/flow', [
    'headers' => ['Authorization' => 'Bearer ck_your_api_key_here'],
    'json' => [
        'phoneNumberId' => '100000000000001',
        'to' => '919876543210',
        'flowId' => '700000000000001',
        'flowToken' => 'order_1720856400000_abc123',
        'initialScreenData' => [
            'order_id' => '1001',
            'product_name' => 'Demo Cotton T-Shirt',
            'order_total' => 'INR 998.00'
        ]
    ]
]);

Meta reference: WhatsApp Flows