Commerce Flows API & MCP

Create, publish, send, and analyze Meta WhatsApp Flows with ChatYug’s External API (Bearer ck_…) or MCP tools. Prefer authoring screens in the portal Flow Design module; use API/MCP for CRM automation and reporting.

Prerequisites

• Active ChatYug API key or MCP connection scoped to the WABA
• Flows published on Meta before customer send
• Valid phoneNumberId for send

Base URL

https://chatyug.com/api/external

Manage flows

flowId in manage paths is the local ChatYug flow id. For send, pass Meta’s meta_flow_id as flowId.

Send a flow message

POST /messages/flow · MCP send_commerce_flow_message

curl -X POST https://chatyug.com/api/external/messages/flow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "YOUR_PHONE_NUMBER_ID",
    "to": "919876543210",
    "flowId": "META_FLOW_ID",
    "bodyText": "Please complete this form",
    "ctaText": "Open"
  }'

Successful sends are logged as analytics send events. Customer completions (nfm_reply / flow endpoint) become submit events. Portal Test Send and API send also write an outbound “Flow sent” bubble in Conversations.

Receive filled data (nfm_reply)

When the customer completes the flow, Meta delivers a normal inbound message webhook with interactive.type = "nfm_reply". ChatYug forwards this on your customer webhook and stores the same fields in Conversations + Flow Analytics.

1. Parse data.message.interactive.nfm_reply.response_json (it is a JSON string).
2. Keys in that object match the designer input Name (e.g. customer_name → ${form.customer_name} in the canvas).
3. Correlate with the token you passed as flowToken on send — it is usually present as flow_token inside response_json.

{
  "eventType": "message",
  "data": {
    "from": "919876543210",
    "message": {
      "type": "interactive",
      "interactive": {
        "type": "nfm_reply",
        "nfm_reply": {
          "name": "flow",
          "body": "Sent",
          "response_json": "{\"flow_token\":\"flow_1720856400000_abc\",\"customer_name\":\"Rahul\",\"city\":\"Bharuch\"}"
        }
      }
    }
  }
}

// Node — end-to-end correlate
const reply = payload.data.message.interactive.nfm_reply;
const answers = JSON.parse(reply.response_json || '{}');
const token = answers.flow_token; // same value returned from POST /messages/flow
// Load your CRM lead/order by token, then map answers.customer_name, answers.city, …

curl -X POST https://chatyug.com/api/external/messages/flow \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumberId": "YOUR_PHONE_NUMBER_ID",
    "to": "917016793529",
    "flowId": "META_FLOW_ID",
    "flowToken": "lead_42_checkout",
    "bodyText": "Please complete this form",
    "ctaText": "Open"
  }'
# Later, on your webhook: JSON.parse(nfm_reply.response_json).flow_token === "lead_42_checkout"

Portal views of the same events: Conversations (Flow sent / Flow response bubbles) and Flow Design → Analytics (structured send/submit table + Excel).

Also see Webhook Settings samples and API docs §4.5.

Pre-publish checklist

• Terminal screens include a Footer
• Screen IDs are unique UPPER_SNAKE_CASE
• Field names unique flow-wide (lowercase / underscore)
• Dropdown / Radio / Checkbox have ≥2 options
• Image src is HTTPS when set
• Footer / NavigationList navigate targets exist
• If any Footer uses data_exchange, configure Commerce Settings flow endpoint (+ RSA)

ChatYug runs these checks on Approve in the designer and list before calling Meta.

Flow analytics

Query params: flowId (local id, recommended), metaFlowId, eventType (send|submit), phone, fromDate, toDate, page, pageSize. Export: format=xlsx (default) or json.

PhotoPicker / DocumentPicker answers are downloaded into ChatYug storage on submit. List responses include a parsed payload object; media items gain chatyug_url and chatyug_media_type (image|document|video from MIME — there is no VideoPicker). Use the media endpoint (or MCP get_flow_media) with eventId + field name; add format=json for metadata only.

curl "https://chatyug.com/api/external/commerce/flows/analytics?flowId=12&page=1&pageSize=50" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://chatyug.com/api/external/commerce/flows/analytics/summary?flowId=12" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -OJ "https://chatyug.com/api/external/commerce/flows/analytics/export?flowId=12&format=xlsx" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl "https://chatyug.com/api/external/commerce/flows/analytics/events/EVENT_ID/media/photo_75ke?format=json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Portal

Operators open analytics from each flow card in Flow Design (Excel export included). See the Flow Design Guide — Analytics.