Loading...
Keys for your apps and integrations to send WhatsApp messages via ChatYug
Connect Claude, ChatGPT, or other MCP clients to your ChatYug WhatsApp account
Add this URL in your AI client (Claude.ai custom connector, Claude Code, Gemini CLI, etc.). Leave OAuth Client ID/Secret empty — sign in with ChatYug when prompted.
https://mcp.chatyug.com/mcp
Authorization: Bearer mcp_….
Test endpoints from the portal with a live request/response viewer
Send authenticated requests against your WABA and inspect responses without leaving ChatYug.
Follow these simple steps to integrate our API with your software:
Click the "Generate New API Key" button above to create your API key. Save it securely - you won't be able to see it again!
API keys start with ck_ and a long random secret (shown once when you generate the key). Do not use made-up or example strings.
Include your API key in the Authorization header of all requests:
Authorization: Bearer YOUR_API_KEY
Send a template message using cURL:
curl -X POST https://chatyug.com/api/external/send-message \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "917016793529",
"type": "template",
"templateName": "hello_world",
"templateLanguage": "en"
}'
type values on POST /send-message:
text, template, image, video, audio, document.
See the Send Media tab for photos/files (use mediaId from upload-media). Download the full PDF for complete request/response samples.
Endpoint: POST https://chatyug.com/api/external/send-message
{
"phoneNumberId": "719142414620783",
"to": "917016793529",
"type": "text",
"text": "Hello! This is a test message."
}
{
"success": true,
"message": "text message sent successfully",
"data": {
"messageId": "wamid.HBgMOTE5ODc2NTQzMjEw...",
"status": "sent",
"conversationId": 12345
}
}
{
"success": false,
"message": "Failed to send text message: (#131047) Message failed to send because more than 24 hours have passed since the customer last replied to this number."
}
curl -X POST https://chatyug.com/api/external/send-message \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "719142414620783",
"to": "917016793529",
"type": "text",
"text": "Hello! This is a test message."
}'
Send photos and files inside the 24-hour customer service window. Outside that window use an approved media template instead.
type: "text" with mediaUrl — that only sends text. Set type to image, video, audio, or document.
Endpoint: POST https://chatyug.com/api/external/send-message
POST /api/external/messages/upload-media (multipart) → get mediaIdPOST /api/external/send-message with type + mediaIdcurl -X POST https://chatyug.com/api/external/messages/upload-media \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "mediaFile=@photo.jpg" \ -F "phoneNumberId=YOUR_PHONE_NUMBER_ID" \ -F "mediaType=image"
curl -X POST https://chatyug.com/api/external/send-message \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "917016793529",
"type": "image",
"mediaId": "META_MEDIA_ID_FROM_UPLOAD",
"caption": "Here is the product photo"
}'{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "917016793529",
"type": "image",
"mediaUrl": "https://example.com/images/product.jpg",
"caption": "Optional caption"
}{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "917016793529",
"type": "document",
"mediaId": "META_MEDIA_ID",
"filename": "invoice.pdf",
"caption": "Your invoice"
}ChatYug downloads inbound media to /received_media/.... Use GET /api/external/messages/:messageId/media for a stable URL. Do not cache Meta lookaside.fbsbx.com links — they expire in minutes.
Endpoint: POST https://chatyug.com/api/external/send-message
{
"phoneNumberId": "719142414620783",
"to": "917016793529",
"type": "template",
"templateName": "hello_world",
"templateLanguage": "en"
}
{
"success": true,
"message": "template message sent successfully",
"data": {
"messageId": "wamid.HBgMOTE5ODc2NTQzMjEw...",
"status": "sent",
"conversationId": 12345
}
}
curl -X POST https://chatyug.com/api/external/send-message \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "719142414620783",
"to": "917016793529",
"type": "template",
"templateName": "hello_world",
"templateLanguage": "en"
}'
Fetch templates registered in ChatYug for your WABA. Use templateName, templateLanguage, and templateVariables in POST /api/external/send-message.
https://chatyug.com/api/external | Auth: Authorization: Bearer YOUR_API_KEY
Query: status (APPROVED default, or PENDING, REJECTED, ALL), search, category, language
curl -X GET "https://chatyug.com/api/external/templates?status=APPROVED" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"total": 2,
"templates": [
{
"templateId": 42,
"templateName": "order_confirmation",
"language": "en",
"category": "UTILITY",
"status": "APPROVED",
"bodyText": "Hello {{1}}, your order {{2}} is confirmed.",
"variableCount": 2,
"variables": [
{ "index": 1, "component": "body", "placeholder": "{{1}}", "example": "Rahul" },
{ "index": 2, "component": "body", "placeholder": "{{2}}", "example": "ORD-12345" }
],
"sampleSendRequest": {
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "919876543210",
"type": "template",
"templateName": "order_confirmation",
"templateLanguage": "en",
"templateVariables": ["Rahul", "ORD-12345"]
}
}
]
}curl -X GET https://chatyug.com/api/external/templates/42 \ -H "Authorization: Bearer YOUR_API_KEY"
Returns full body/header/footer text, variables, buttons, components, and sendMessageExample.
Select a template to copy the ready-to-use send-message JSON for your integration.
Submit WhatsApp message templates to Meta for approval without using the portal UI. The API always returns PENDING immediately — poll the status endpoint until Meta approves or rejects.
AUTOMATION_ACCESS_DENIED without it.
https://chatyug.com/api/external | Auth: Authorization: Bearer YOUR_API_KEY
templateId + status: "PENDING".| Field | Required | Description |
|---|---|---|
| templateName | ✅ | Lowercase, underscores. Must be unique in your WABA. |
| templateContent | ✅ | Body text. Use {{1}}, {{2}} for variables. |
| category | ✅ | UTILITY, MARKETING, or AUTHENTICATION |
| language | — | BCP-47 code. Default: en_US. Common values: en, hi, gu |
| variables | — | Array of {"index":1,"example":"Rahul"} — one per {{n}}. Required when template has variables. |
| headerContent | — | Text header (plain text, no emoji). |
| footerContent | — | Footer text (short, no variables). |
| buttons | — | Array of button objects. type: QUICK_REPLY, URL, or PHONE_NUMBER. |
| mediaType | — | Header media: IMAGE, VIDEO, or DOCUMENT. Requires mediaFile or assetHandle. |
| mediaFile | — | Multipart field (use multipart/form-data). Requires phoneNumberId. |
| assetHandle | — | Meta Resumable Upload handle (recommended for VIDEO). |
| phoneNumberId | — | Required when uploading mediaFile. |
Accepts application/json or multipart/form-data (use mediaFile field for IMAGE/VIDEO/DOCUMENT headers). Alternatively pass assetHandle from Meta Resumable Upload.
curl -X POST https://chatyug.com/api/external/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"templateName": "order_update_api",
"templateContent": "Hi {{1}}, your order {{2}} is confirmed.",
"category": "UTILITY",
"language": "en",
"variables": [
{ "index": 1, "example": "Rahul" },
{ "index": 2, "example": "ORD-991" }
]
}'curl -X POST https://chatyug.com/api/external/templates \
-H "Authorization: Bearer YOUR_API_KEY" \
-F "templateName=promo_with_image" \
-F "templateContent=Check out our latest offer {{1}}!" \
-F "category=MARKETING" \
-F "language=en" \
-F "mediaType=IMAGE" \
-F "phoneNumberId=YOUR_PHONE_NUMBER_ID" \
-F "variables=[{\"index\":1,\"example\":\"Summer Sale\"}]" \
-F "mediaFile=@/path/to/banner.jpg"{
"success": true,
"data": {
"templateId": 128,
"metaTemplateId": "123456789",
"status": "PENDING",
"statusEndpoint": "/api/external/templates/128/status"
}
}Returns PENDING, APPROVED, or REJECTED plus rejectionReason when applicable. Poll every 2–5 minutes; no webhook is sent when status changes.
curl -X GET https://chatyug.com/api/external/templates/128/status \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"data": {
"templateId": 128,
"templateName": "order_update_api",
"status": "APPROVED",
"metaStatus": "approved",
"rejectionReason": null
}
}Forces ChatYug to re-fetch the template's approval status from Meta immediately. Useful if the status seems stale.
curl -X POST https://chatyug.com/api/external/templates/128/sync \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phoneNumberId": "YOUR_PHONE_NUMBER_ID"}'Register a carousel template with card images and buttons. Requires phoneNumberId, templateName, bodyText, and cards[] with headerSrc (HTTPS image URL) per card.
curl -X POST https://chatyug.com/api/external/templates/carousel \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"templateName": "summer_sale_carousel",
"languageCode": "en_US",
"bodyText": "Swipe to explore our summer collection",
"cards": [
{ "headerSrc": "https://chatyug.com/example/card1.jpg", "bodyText": "T-shirt", "buttons": [{ "type": "URL", "text": "Shop", "url": "https://example.com" }] }
]
}'Once APPROVED, send with POST /api/external/messages/carousel.
| HTTP | Code | When |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing templateName, templateContent, or category; or missing phoneNumberId when uploading mediaFile |
| 403 | AUTOMATION_ACCESS_DENIED | WABA lacks automation permission |
| 502 | — | Meta rejected the template payload (check message field for Meta's reason) |
Full guide: Template Creation API documentation | Prefer the portal UI? Use Message Templates → Create Template.
Schedule template-based WhatsApp sends from your CRM, ERP, or custom platform — no portal login required. ChatYug's background processor fires at the scheduled time; use the report endpoint for delivery status.
APPROVED in Meta before scheduling. Default timezone: Asia/Kolkata. Use ISO date (YYYY-MM-DD) and HH:mm time.
scheduleType: ONE_TIME or RECURRING. For recurring, include recurrencePattern, recurrenceInterval, recurrenceDays, recurrenceEndDate.
curl -X POST https://chatyug.com/api/external/scheduled-messages \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"scheduleName": "Monday promo",
"scheduleType": "ONE_TIME",
"templateName": "order_update",
"templateLanguage": "en",
"scheduledDate": "2026-07-25",
"scheduledTime": "10:30",
"timezone": "Asia/Kolkata",
"recipients": [
{ "phoneNumber": "919876543210", "variables": { "1": "Rahul", "2": "ORD-991" } }
]
}'variables map to template {{1}}, {{2}} placeholders.
Query: status, scheduleType, phoneNumberId, page, limit
curl -X GET "https://chatyug.com/api/external/scheduled-messages?status=PENDING&page=1&limit=20" \ -H "Authorization: Bearer YOUR_API_KEY"
curl -X GET https://chatyug.com/api/external/scheduled-messages/101 \ -H "Authorization: Bearer YOUR_API_KEY"
Returns summary counts (sent, delivered, read, failed, pending) and per-recipient delivery details.
curl -X GET https://chatyug.com/api/external/scheduled-messages/101/report \ -H "Authorization: Bearer YOUR_API_KEY"
Cancels a pending schedule. Requires automation permission.
curl -X DELETE https://chatyug.com/api/external/scheduled-messages/101 \ -H "Authorization: Bearer YOUR_API_KEY"
Multipart upload with field csvFile. CSV must include a phone column (or Phone, phone_number). Returns validated rows for use in create payload.
curl -X POST https://chatyug.com/api/external/scheduled-messages/upload-csv \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "csvFile=@recipients.csv"
Queues a PENDING or FAILED schedule for immediate execution by the background processor.
curl -X POST https://chatyug.com/api/external/scheduled-messages/101/run-now \ -H "Authorization: Bearer YOUR_API_KEY"
| Code | When |
|---|---|
AUTOMATION_ACCESS_DENIED | WABA lacks automation permission |
TEMPLATE_NOT_APPROVED | Template not approved in Meta |
VALIDATION_ERROR | Missing or invalid fields |
Full guide: Scheduled Messages API documentation
headerMediaId — upload in the portal or via POST /api/external/messages/upload-media (see section 5). templateId must belong to your API key account. Catalog-registered templates often use empty cards[].bodyParams (body text is set at registration).
Endpoint: GET https://chatyug.com/api/external/templates/carousel
Auth: Authorization: Bearer YOUR_API_KEY
| Query | Default | Values |
|---|---|---|
| status | APPROVED | APPROVED, PENDING, REJECTED |
{
"success": true,
"templates": [
{
"templateId": 1217,
"templateName": "summer_sale_carousel",
"status": "APPROVED",
"languageCode": "en_US",
"carouselConfig": { "cards": [], "source": "catalog" },
"createdAt": "2026-06-03T10:30:00.000Z"
}
]
}
curl -X GET "https://chatyug.com/api/external/templates/carousel?status=APPROVED" \ -H "Authorization: Bearer YOUR_API_KEY"
Endpoint: GET https://chatyug.com/api/external/templates/carousel/:templateId
Returns full carouselConfig (card count, button structure, catalog source) for building send payloads.
curl -X GET "https://chatyug.com/api/external/templates/carousel/1217" \ -H "Authorization: Bearer YOUR_API_KEY"
Endpoint: POST https://chatyug.com/api/external/messages/carousel
{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "919876543210",
"templateName": "summer_sale_carousel",
"templateId": 1217,
"languageCode": "en_US",
"bodyParams": [{ "type": "text", "text": "Rahul" }],
"cards": [
{
"card_index": 0,
"headerMediaId": "META_MEDIA_ID_CARD_1",
"headerMediaType": "image",
"bodyParams": [],
"buttons": [
{ "sub_type": "quick_reply", "index": "0", "parameters": [{ "type": "payload", "payload": "shop" }] }
]
},
{
"card_index": 1,
"headerMediaId": "META_MEDIA_ID_CARD_2",
"headerMediaType": "image",
"bodyParams": [],
"buttons": [
{ "sub_type": "quick_reply", "index": "0", "parameters": [{ "type": "payload", "payload": "buy" }] }
]
}
]
}
cards must have 2–10 items; card_index is 0-based and sequential. headerMediaId is a Meta media ID (not a URL). headerMediaType: image or video.
{ "success": false, "code": "TEMPLATE_NOT_APPROVED", "error": "Template is not approved. Only APPROVED carousel templates can be sent." }
{ "success": false, "code": "VALIDATION_ERROR", "errors": ["cards must contain between 2 and 10 items"] }
{ "success": false, "code": "PHONE_NOT_FOUND", "error": "Phone number ID not found in this account." }
{
"success": true,
"messageId": "wamid.HBgM...",
"data": {
"metaMessageId": "wamid.HBgM...",
"dbMessageId": 12345,
"conversationId": 678
}
}
curl -X POST https://chatyug.com/api/external/messages/carousel \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d @carousel-payload.json
Endpoint: POST https://chatyug.com/api/external/messages/upload-media
Upload an image or video file to Meta and receive a mediaId for cards[].headerMediaId.
| Field | Type | Required | Notes |
|---|---|---|---|
| mediaFile | file | Yes | multipart field name (max 15MB) |
| phoneNumberId | string | Yes | WABA phone number ID |
| mediaType | string | No | image (default) or video — storage subfolder |
{
"success": true,
"message": "Media uploaded successfully",
"data": {
"mediaId": "1234567890",
"mediaUrl": "https://chatyug.com/chat_media/images/chat_...",
"filename": "chat_123.jpg",
"size": 102400,
"mimetype": "image/jpeg"
}
}
curl -X POST "https://chatyug.com/api/external/messages/upload-media" \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "mediaFile=@/path/to/header.jpg" \ -F "phoneNumberId=YOUR_PHONE_NUMBER_ID" \ -F "mediaType=image"
| Code | HTTP | Description |
|---|---|---|
| TEMPLATE_NOT_APPROVED | 403 | Template exists but Status ≠ APPROVED |
| TEMPLATE_NOT_FOUND | 404 | templateId not in this account |
| PHONE_NOT_FOUND | 404 | phoneNumberId not in this account |
| VALIDATION_ERROR | 400 | Invalid cards count, missing fields |
| META_ERROR | 502 | Meta API rejected the request |
| Feature | Portal | External API |
|---|---|---|
| Register template | Yes | Phase 3 |
| Sync Meta status | Yes | Phase 3 |
| Send approved carousel | Yes | Yes (Phase 1) |
| Bulk carousel | Yes | Phase 2 |
| Scheduled carousel | Yes | Not planned |
| Upload header media | Yes | Yes (Phase 1b) |
APPROVED.GET /api/external/templates/carousel?status=APPROVED — note templateName; inspect carouselConfig for card count and buttons.POST /api/external/messages/upload-media → collect data.mediaId as headerMediaId.POST /api/external/messages/carousel with cards[] matching the template structure.GET /api/external/delivery-status/:messageId (see Delivery Status tab).Endpoint: GET https://chatyug.com/api/external/delivery-status/:messageId
curl -X GET https://chatyug.com/api/external/delivery-status/wamid.HBgMOTE5... \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"data": {
"messageId": "wamid.HBgMOTE5ODc2NTQzMjEw...",
"status": "read",
"to": "917016793529",
"customerName": "John Doe",
"messageType": "template",
"content": "Template: order_confirmation",
"sentAt": "2025-10-19T12:00:00.000Z",
"deliveredAt": "2025-10-19T12:00:05.000Z",
"readAt": "2025-10-19T12:00:15.000Z",
"error": null
}
}
sent - Message sent to WhatsAppdelivered - Message delivered to recipientread - Message read by recipientfailed - Message failed to send
Comprehensive code examples for integrating our WhatsApp API in different programming languages.
All requests use Authorization: Bearer YOUR_API_KEY (not X-API-Key). Text, template, and session media (image/video/audio/document) all use POST /api/external/send-message with a type field. For photos, set type: "image" with mediaId — not type: "text" + mediaUrl.
Manage your product catalog programmatically — list catalogs, upload product images (or pass a CDN imageUrl), push new products (requires productUrl + imageUrl), create sale/offers, update stock/pricing, and send catalog messages to customers.
https://chatyug.com/api/external | Auth: Authorization: Bearer YOUR_API_KEY
ChatYug does not auto-reply to SHOP. Your app receives inbound webhooks, calls the APIs below, and sends WhatsApp messages. Assign category on each product in the portal or via POST /catalogs/:id/products.
SHOP) → your webhook eventType: messageGET /catalogs/{metaCatalogId}/categoriesPOST /messages/interactive with interactiveType: "list" and sections from interactiveListSectionslist_reply.id = category slug (e.g. cat_dairy)GET /catalogs/{id}/product-list-payload?category={slug}POST /messages/product-list with returned sections or productRetailerIdsLimits: max 10 category rows per list; max 30 products per product_list message. Use truncated: true in payload response to paginate.
Creates a product catalog in Meta and saves it in ChatYug. WABA is inferred from your API key.
| Field | Required | Description |
|---|---|---|
catalogName | ✓ | Display name for the catalog |
vertical | ✓ | commerce (recommended), generic, local_service_businesses, offline_commerce, or other Meta verticals |
curl -X POST https://chatyug.com/api/external/catalogs \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"catalogName": "My Shop Catalog", "vertical": "commerce"}'Returns all active WhatsApp product catalogs linked to your WABA.
curl -X GET https://chatyug.com/api/external/catalogs \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"total": 2,
"catalogs": [
{
"Catalog_Id": 1,
"Meta_Catalog_Id": "980328057290841",
"Catalog_Name": "My Shop Catalog",
"Description": "Main product catalog",
"Product_Count": 45,
"Is_Active": true,
"Created_At": "2025-01-15T10:30:00.000Z",
"Last_Synced_At": "2025-04-01T08:00:00.000Z"
}
]
}Fetch all products from a catalog. catalogId can be the Meta Catalog ID or internal Catalog_Id.
| Parameter | Type | Description |
|---|---|---|
page | integer | Page number (default: 1) |
limit | integer | Products per page (default: 50, max: 200) |
search | string | Search by name, description, or retailer ID |
category | string | Filter by category name or slug from GET /catalogs/:id/categories |
availability | string | in stock or out of stock |
curl -X GET "https://chatyug.com/api/external/catalogs/980328057290841/products?page=1&limit=20&availability=in+stock" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"products": [
{
"Product_Id": 101,
"Meta_Product_Id": "5678901234567",
"Product_Name": "Premium Cotton T-Shirt",
"Description": "100% cotton, available in all sizes",
"Retailer_ID": "TSHIRT-WHITE-M",
"Currency": "INR",
"Price": "599.00",
"Image_URL": "https://example.com/tshirt.jpg",
"Product_URL": "https://example.com/products/tshirt",
"Availability": "in stock",
"Category": "Apparel",
"Brand": "MyBrand",
"Inventory": 150
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"pages": 3
}
}Returns distinct product labels (not separate Meta entities). Categories are the category field on products; empty categories are unsupported.
| Parameter | Type | Description |
|---|---|---|
inStockOnly | boolean | Default true — only count in-stock products |
curl -X GET "https://chatyug.com/api/external/catalogs/980328057290841/categories" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"catalogId": "980328057290841",
"categories": [
{ "name": "Kitchen Appliances", "slug": "cat_kitchen_appliances", "productCount": 5 },
{ "name": "Dairy", "slug": "cat_dairy", "productCount": 3 }
],
"interactiveListSections": [
{
"title": "Categories",
"rows": [
{ "id": "cat_kitchen_appliances", "title": "Kitchen Appliances", "description": "5 products" },
{ "id": "cat_dairy", "title": "Dairy", "description": "3 products" }
]
}
]
}Use slug as list_reply row id and pass it back to ?category= on product-list-payload. Row title max 24 chars (Meta limit).
Set category on products by SKU. A category only appears in GET after at least one product is assigned.
curl -X POST https://chatyug.com/api/external/catalogs/980328057290841/categories/assign \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "name": "Dairy", "retailerIds": ["MILK-1L", "YOGURT-500G"] }'curl -X PUT https://chatyug.com/api/external/catalogs/980328057290841/categories \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "from": "Dairy", "to": "Milk Products" }'Clears the label on matching products (they become Uncategorized).
curl -X DELETE https://chatyug.com/api/external/catalogs/980328057290841/categories/cat_dairy \ -H "Authorization: Bearer YOUR_API_KEY"
Returns sections and productRetailerIds for POST /messages/product-list. No hardcoded product lists — built dynamically from catalog DB.
| Parameter | Type | Description |
|---|---|---|
category | string | Category slug from GET /categories (e.g. cat_dairy) |
groupByCategory | boolean | If true and no category, one section per category (max 30 products total) |
curl -X GET "https://chatyug.com/api/external/catalogs/980328057290841/product-list-payload?category=cat_dairy" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"catalogId": "980328057290841",
"sections": [
{
"title": "Dairy",
"product_items": [
{ "product_retailer_id": "MILK-1L" },
{ "product_retailer_id": "YOGURT-500G" }
]
}
],
"productRetailerIds": ["MILK-1L", "YOGURT-500G"],
"totalProducts": 2,
"truncated": false
}truncated: true means more than 30 in-stock products matched — send additional product-list messages with the remaining IDs.
ChatYug forwards inbound messages to your webhook. Your app owns keyword detection and the category → product list journey.
async function onWebhook(event) {
if (event.eventType !== 'message') return;
const msg = event.data?.message;
const from = event.data?.from;
const catalogId = 'YOUR_META_CATALOG_ID';
const phoneNumberId = event.phoneNumberId;
if (msg?.type === 'text' && /^(shop|catalogue)$/i.test(msg.text?.body?.trim())) {
const { interactiveListSections } = await api('GET', `/catalogs/${catalogId}/categories`);
await api('POST', '/messages/interactive', {
phoneNumberId, to: from, interactiveType: 'list',
bodyText: 'Choose a category', listButtonText: 'View Categories',
sections: interactiveListSections
});
return;
}
if (msg?.interactive?.type === 'list_reply') {
const slug = msg.interactive.list_reply.id;
const { sections } = await api('GET', `/catalogs/${catalogId}/product-list-payload?category=${slug}`);
await api('POST', '/messages/product-list', {
phoneNumberId, to: from, catalogId, sections,
bodyText: `Browse ${msg.interactive.list_reply.title}`
});
}
}Full reference: docs/INTEGRATOR_WHATSAPP_COMMERCE_REFERENCE.md §4.3
Upload a JPEG, PNG, or WebP file (max 5MB). Returns a public HTTPS imageUrl to pass into create/update product. You can also skip this and pass any existing public CDN URL as imageUrl.
Multipart field name: image
curl -X POST https://chatyug.com/api/external/catalogs/upload-image \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "image=@/path/to/product.jpg"
{
"success": true,
"message": "Image uploaded successfully",
"data": {
"imageUrl": "https://chatyug.com/uploads/product-images/product-1720856400000-123.jpg",
"imagePath": "/uploads/product-images/product-1720856400000-123.jpg",
"filename": "product-1720856400000-123.jpg",
"size": 84210,
"mimeType": "image/jpeg"
}
}Add a new product to a catalog. The product is synced to Meta's catalog and saved in ChatYug.
| Field | Required | Description |
|---|---|---|
productName | ✓ | Product name (max 200 chars) |
price | ✓ | Price in major units (e.g. 599 for ₹599; stored internally as smallest currency unit) |
currency | — | Currency code (default: INR) |
retailerId | — | Your unique product SKU. Auto-generated if omitted. |
description | — | Product description |
imageUrl | ✓ | Public HTTPS image URL (required for Meta). Use POST /catalogs/upload-image or your CDN. |
productUrl | ✓ | Full http(s) product or shop page URL. Becomes Meta link shown under the description in WhatsApp. Never defaults to chatyug.com. |
availability | — | in stock (default) or out of stock |
category | — | Browse category label (e.g. Dairy, Kitchen Appliances) — used for category picker flow |
brand | — | Brand name |
inventory | — | Stock count (integer) |
Required by vertical: For commerce/generic, only productName, price, imageUrl, productUrl are required — address/lat/long are not used. For local_service_businesses / offline_commerce: also send full address, or lat+long, or postal code alone (LOCALITY_REQUIRED if missing). brand / inventory remain optional. | ||
curl -X POST https://chatyug.com/api/external/catalogs/980328057290841/products \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"productName": "Premium Cotton T-Shirt",
"description": "100% cotton, comfortable fit",
"price": 599,
"currency": "INR",
"retailerId": "TSHIRT-WHITE-M",
"imageUrl": "https://example.com/tshirt.jpg",
"productUrl": "https://example.com/products/tshirt",
"availability": "in stock",
"category": "Apparel & Accessories",
"brand": "MyBrand",
"inventory": 150
}'{
"success": true,
"message": "Product created successfully",
"data": {
"productId": 101,
"metaProductId": "5678901234567",
"retailerId": "TSHIRT-WHITE-M",
"productName": "Premium Cotton T-Shirt",
"price": 599,
"currency": "INR"
}
}Update product details (price, stock, name, etc.). Only include the fields you want to change.
curl -X PUT https://chatyug.com/api/external/catalogs/980328057290841/products/TSHIRT-WHITE-M \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"price": 499,
"availability": "in stock",
"inventory": 200
}'{
"success": true,
"message": "Product updated successfully",
"data": { "productId": 101, "retailerId": "TSHIRT-WHITE-M" }
}Deletes the product from Meta and ChatYug by SKU (retailerId). No portal required. If Meta delete fails, ChatYug still removes the local row and may return metaWarning.
curl -X DELETE https://chatyug.com/api/external/catalogs/980328057290841/products/TSHIRT-WHITE-M \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"message": "Product deleted successfully",
"data": { "productId": 101, "retailerId": "TSHIRT-WHITE-M", "productName": "Premium Cotton T-Shirt" }
}List sale / coupon / auto offers registered for a catalogue (any WABA keyed by your API key).
curl -X GET https://chatyug.com/api/external/catalogs/980328057290841/offers \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"offers": [
{
"offerId": 1,
"applicationType": "SALE",
"valueType": "EXACT_SALE_PRICE",
"salePrice": 225.90,
"targetSelection": "SPECIFIC_PRODUCTS",
"targetRetailerIds": ["TSHIRT-WHITE-M"],
"status": "ACTIVE"
}
]
}Sale (applicationType: SALE) sets Meta sale_price for WhatsApp product-card strikethrough. Coupon / Auto use Meta Offers API (FB/IG checkout), not WhatsApp coupon fields. No ChatYug.com defaults; works for every WABA.
| Field | Required | Description |
|---|---|---|
applicationType | ✓ | SALE | AUTOMATIC_AT_CHECKOUT | BUYER_APPLIED |
valueType | ✓ | EXACT_SALE_PRICE | PERCENTAGE | FIXED_AMOUNT (EXACT_SALE_PRICE only with SALE) |
salePrice | * | Exact sale price in major units (e.g. 225.90) when valueType=EXACT_SALE_PRICE |
percentOff | * | 1–100 when valueType=PERCENTAGE |
fixedAmountOff | * | Amount off in major units when valueType=FIXED_AMOUNT |
targetSelection | — | SPECIFIC_PRODUCTS (default) or ALL_CATALOG_PRODUCTS |
targetRetailerIds | * | SKU array required for SPECIFIC_PRODUCTS |
couponCode | * | Required for BUYER_APPLIED |
startAt / endAt | — | ISO timestamps (optional) |
curl -X POST https://chatyug.com/api/external/catalogs/980328057290841/offers \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"applicationType": "SALE",
"valueType": "EXACT_SALE_PRICE",
"salePrice": 225.90,
"targetSelection": "SPECIFIC_PRODUCTS",
"targetRetailerIds": ["TSHIRT-WHITE-M"]
}'Deactivates an offer. For SALE offers, clears Meta sale_price on targeted products.
curl -X DELETE https://chatyug.com/api/external/catalogs/offers/1 \ -H "Authorization: Bearer YOUR_API_KEY"
Send an interactive product list message. Customer can browse and add items to cart directly in WhatsApp. Pass either productRetailerIds[] (single section) or sections[] (multi-section / per-category).
curl -X POST https://chatyug.com/api/external/messages/product-list \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "919876543210",
"catalogId": "980328057290841",
"sections": [
{
"title": "Dairy",
"product_items": [
{ "product_retailer_id": "MILK-1L" },
{ "product_retailer_id": "YOGURT-500G" }
]
}
],
"headerText": "🛍️ Our Latest Collection",
"bodyText": "Check out our top picks just for you!",
"footerText": "Tap a product to add to cart"
}'{
"success": true,
"message": "Product list message sent",
"data": { "messageId": "wamid.HBgMOTE5ODc2NTQzMjEw..." }
}Send a single product card. Ideal for upsells or highlighting a specific product.
curl -X POST https://chatyug.com/api/external/messages/single-product \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "919876543210",
"catalogId": "980328057290841",
"productRetailerId": "TSHIRT-WHITE-M",
"bodyText": "We thought you might love this! 😍"
}'{
"success": true,
"message": "Single product message sent",
"data": { "messageId": "wamid.HBgMOTE5ODc2NTQzMjEw..." }
}Manage WhatsApp Commerce orders — retrieve order details, update status through the full pipeline, add notes, and send customer notifications programmatically. Configure auto-acknowledgement and per-WABA order numbers via GET/PUT /commerce/settings (or the ChatYug portal Commerce Settings page).
eventType: order (+ enriched data.chatyug)GET /orders/:id — line items, flow_token, and checkout_submission (answers + media URLs once the customer completes checkout Flow)POST /messages/flow with flowToken = order flow_token (see Commerce Flows tab)nfm_reply (push) and/or analytics / checkout_submission (pull, includes media)PUT /orders/:id/status and optional POST /orders/:id/notifypending → confirmed → shipped → delivered (or cancelled). Setting a status automatically sends a WhatsApp notification to the customer unless you pass "notifyCustomer": false.
id is the internal ChatYug primary key (use it in /orders/:orderId paths). order_number is the per-WABA display number (prefix + sequence). Customer WhatsApp messages and status notifies show the display number. Older orders may have order_number: null — fall back to id.
Returns commerce settings for the API key WABA. Includes auto-ack, order numbering, and option_lists (named option arrays for dynamic Flows). Catalog link, cart Meta toggles, and RSA keys are configured in the portal (not via this endpoint).
curl -X GET https://chatyug.com/api/external/commerce/settings \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"settings": {
"auto_ack_enabled": true,
"auto_ack_type": "text",
"auto_ack_body": "✅ Order Received!\\n\\nOrder #{{order_number}}\\n{{items}}\\n\\nTotal: {{currency}} {{total}}\\n\\nWe'll confirm your order shortly. Thank you! 🙏",
"auto_ack_template_name": null,
"auto_ack_template_language": "en",
"auto_ack_template_vars": null,
"order_number_prefix": "ORD-",
"order_number_pad": 4,
"order_number_next": 7,
"auto_send_checkout_flow": false,
"checkout_flow_id": null,
"option_lists": {
"cities": [
{ "id": "amd", "title": "Ahmedabad" },
{ "id": "bhu", "title": "Bharuch" }
]
}
}
}Ack placeholders: {{order_number}}, {{items}}, {{total}}, {{currency}}, {{customer_name}}. If checkout flow auto-sends successfully, the text/template ack is skipped. option_lists feeds dynamic Flow Dropdown/Radio via resolveProviders: ["commerce_settings_lists"].
Partial update. When autoAckEnabled: true, you must provide free text (autoAckType: "text" + autoAckBody) or an approved template (autoAckType: "template" + autoAckTemplateName). Disable ack with autoAckEnabled: false (no WhatsApp ack after cart order). Use optionLists for named dynamic Flow Dropdown/Radio lists (filled via resolveProviders: ["commerce_settings_lists"] on send).
| Field | Type | Description |
|---|---|---|
autoAckEnabled | boolean | Enable/disable post-order acknowledgement |
autoAckType | string | text or template |
autoAckBody | string | Free-text body with placeholders (required when enabled + text) |
autoAckTemplateName | string | APPROVED Meta template name (required when enabled + template) |
autoAckTemplateLanguage | string | Language code (default en) |
autoAckTemplateVars | string[] | Ordered body params, e.g. ["order_number","items","total"] |
orderNumberPrefix | string | Prefix for new orders (e.g. ORD-) |
orderNumberPad | integer | Zero-pad width 0–10 (0 = no pad) |
orderNumberNext | integer | Next sequence to allocate (≥1). Does not rewrite old orders. |
autoSendCheckoutFlow | boolean | Optional — auto-send checkout Flow after cart order |
checkoutFlowId | string | Optional — Meta Flow ID for checkout |
optionLists / option_lists | object | Named lists for dynamic Flows: { "cities": [{ "id":"amd","title":"Ahmedabad" }, …] } |
curl -X PUT https://chatyug.com/api/external/commerce/settings \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"autoAckEnabled": true,
"autoAckType": "text",
"autoAckBody": "✅ Order Received!\\n\\nOrder #{{order_number}}\\n{{items}}\\n\\nTotal: {{currency}} {{total}}\\n\\nThank you!",
"orderNumberPrefix": "ORD-",
"orderNumberPad": 4,
"orderNumberNext": 1,
"optionLists": {
"cities": [
{ "id": "amd", "title": "Ahmedabad" },
{ "id": "bhu", "title": "Bharuch" }
]
}
}'curl -X PUT https://chatyug.com/api/external/commerce/settings \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "autoAckEnabled": false }'Returns paginated orders for your WABA. Filter by status and date range.
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by: pending, confirmed, shipped, delivered, cancelled |
page | integer | Page number (default: 1) |
pageSize | integer | Results per page (default: 20) |
dateFrom | string | Filter from date (YYYY-MM-DD) |
dateTo | string | Filter to date (YYYY-MM-DD) |
dateFromUtc | string | Optional ISO datetime (UTC) start bound |
dateToUtc | string | Optional ISO datetime (UTC) end bound |
curl -X GET "https://chatyug.com/api/external/orders?status=pending&page=1&pageSize=20" \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"total": 42,
"page": 1,
"pageSize": 20,
"orders": [
{
"id": 101,
"order_number": "ORD-0007",
"customer_phone": "919876543210",
"customer_name": "Rahul Sharma",
"status": "pending",
"total_amount": "4999.00",
"currency": "INR",
"items_count": 2,
"payment_method": null,
"customer_note": "Please pack carefully",
"created_at": "2025-04-07T10:30:00.000Z",
"items": [
{ "product_retailer_id": "TSHIRT-WHITE-M", "quantity": 1, "item_price": "599", "currency": "INR" }
]
}
]
}Get complete details of a single order including all items, shipping address, flow_token, and checkout_submission (latest Flow Analytics submit for that token, with media attachments[], or null if not completed yet).
curl -X GET https://chatyug.com/api/external/orders/101 \ -H "Authorization: Bearer YOUR_API_KEY"
{
"success": true,
"order": {
"id": 101,
"order_number": "ORD-0007",
"customer_phone": "919876543210",
"customer_name": "Rahul Sharma",
"waba_id": "815098678039367",
"meta_catalog_id": "980328057290841",
"status": "confirmed",
"total_amount": "4999.00",
"currency": "INR",
"items_count": 2,
"payment_method": "cod",
"customer_note": "Please pack carefully",
"status_notes": "Order verified and packed",
"notified_at": "2025-04-07T11:00:00.000Z",
"flow_token": "order_1744012345_abc12",
"created_at": "2025-04-07T10:30:00.000Z",
"updated_at": "2025-04-07T11:00:00.000Z",
"items": [
{ "product_retailer_id": "TSHIRT-WHITE-M", "quantity": 1, "item_price": "599", "currency": "INR" },
{ "product_retailer_id": "SHOES-001", "quantity": 1, "item_price": "4400", "currency": "INR" }
],
"shipping_address": {
"customer_name": "Rahul Sharma",
"delivery_address": "12, MG Road",
"city": "Bharuch",
"pincode": "392001",
"payment_method": "cod"
},
"checkout_submission": {
"eventId": 69,
"submittedAt": "2025-04-07T10:35:00.000Z",
"payload": { "customer_name": "Rahul Sharma", "delivery_address": "12, MG Road" },
"attachments": [
{
"field": "photo_id",
"mediaType": "image",
"downloadUrl": "https://chatyug.com/api/external/commerce/flows/analytics/events/69/media/photo_id",
"metadataUrl": "https://chatyug.com/api/external/commerce/flows/analytics/events/69/media/photo_id?format=json"
}
],
"hasMedia": true
}
}
}Call attachments[].downloadUrl with the same Bearer API key. Shortcut for order-linked Flow answers — same data as Flow Analytics submit events.
Move an order through the pipeline. Automatically sends a WhatsApp status update to the customer (disable with "notifyCustomer": false).
| Field | Required | Description |
|---|---|---|
status | ✓ | One of: pending, confirmed, shipped, delivered, cancelled |
note | — | Internal note / tracking info (included in customer notification) |
notifyCustomer | — | true (default) to auto-send WhatsApp update, false to skip |
# Confirm an order — customer gets "✅ Order Confirmed" WhatsApp message
curl -X PUT https://chatyug.com/api/external/orders/101/status \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "confirmed",
"note": "Your order has been verified and is being packed.",
"notifyCustomer": true
}'
# Ship — attach tracking
curl -X PUT https://chatyug.com/api/external/orders/101/status \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "shipped",
"note": "Tracking ID: DTDC123456789. Expected delivery: 3-5 days.",
"notifyCustomer": true
}'{
"success": true,
"message": "Order status updated to shipped",
"notifySent": true
}Add an internal note to an order without changing its status. Useful for recording tracking numbers, packing details, etc.
curl -X POST https://chatyug.com/api/external/orders/101/note \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"note": "Customer requested gift wrapping. AWB: DTDC123456789"
}'{ "success": true, "message": "Note added to order" }Send a custom WhatsApp message to the customer about their order. Omit message to use the default status-based message.
# With custom message
curl -X POST https://chatyug.com/api/external/orders/101/notify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "🚚 Your order #101 has been dispatched!\n\nTracking: DTDC123456789\nEstimated delivery: Apr 10–12\n\nTrack here: https://track.dtdc.com/123456789"
}'
# Default status-based message (omit message field)
curl -X POST https://chatyug.com/api/external/orders/101/notify \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'{
"success": true,
"message": "Notification sent to customer",
"messageId": "wamid.HBgMOTE5ODc2NTQzMjEw..."
}| HTTP Code | Meaning | Example |
|---|---|---|
401 | Unauthorized | Missing or invalid API key |
400 | Bad Request | Missing required field / invalid status value |
404 | Not Found | Order or catalog does not exist / not accessible |
500 | Server Error | Internal error — check message field |
{ "success": false, "message": "status must be one of: pending, confirmed, shipped, delivered, cancelled" }ChatYug pushes real-time events to your HTTPS endpoint when customers message you, when delivery status changes, and when cart orders arrive. Configure in Webhook Settings.
X-Chatyug-Event-Id, X-Chatyug-Signature (HMAC-SHA256 when secret is set). Use eventId for idempotency.
| eventType | When fired |
|---|---|
message | Customer sends text, media, button/list reply, or WhatsApp Flow submission (nfm_reply) |
status | Message sent / delivered / read / failed |
order | Customer submits a WhatsApp cart order |
test | Sent from Webhook Settings → Send Test Event |
{
"eventType": "message",
"userId": 34,
"wabaId": "1957290828491918",
"phoneNumberId": "1079034885291122",
"eventId": "wamid.HBgM....",
"occurredAt": "2026-06-23T10:10:00.000Z",
"data": {
"metadata": { "phone_number_id": "1079034885291122" },
"contacts": [{ "profile": { "name": "Rahul" }, "wa_id": "919876543210" }],
"message": {
"id": "wamid....",
"type": "interactive",
"interactive": {
"type": "button_reply",
"button_reply": { "id": "DIST_01", "title": "Distributor A" }
}
}
}
}{
"eventType": "status",
"eventId": "wamid.HBgM....",
"data": {
"status": { "id": "wamid....", "status": "delivered", "timestamp": "1719156600", "recipient_id": "919876543210" }
}
}{
"eventType": "order",
"data": {
"order": {
"catalog_id": "980328057290841",
"product_items": [{ "product_retailer_id": "TSHIRT-WHITE-M", "quantity": 2, "item_price": 599, "currency": "INR" }]
},
"chatyug": {
"order_id": 135,
"order_number": "135",
"items_count": 2,
"total_amount": 1198,
"currency": "INR",
"thumbnail_url": "https://cdn.example.com/tshirt.jpg",
"items": [
{
"product_retailer_id": "TSHIRT-WHITE-M",
"product_name": "White T-Shirt",
"quantity": 2,
"item_price": 599,
"currency": "INR",
"image_url": "https://cdn.example.com/tshirt.jpg"
}
]
}
}
}data.order is raw Meta. Use additive data.chatyug for product names, images, totals, and ChatYug order_id.
{
"eventType": "message",
"eventId": "wamid.HBgM....",
"data": {
"metadata": { "phone_number_id": "1079034885291122" },
"contacts": [{ "profile": { "name": "Rahul" }, "wa_id": "919876543210" }],
"message": {
"from": "919876543210",
"id": "wamid....",
"timestamp": "1719156600",
"type": "interactive",
"interactive": {
"type": "nfm_reply",
"nfm_reply": {
"response_json": "{\"flow_token\":\"order_1744012345_abc12\",\"customer_name\":\"Rahul\",\"delivery_address\":\"12 MG Road\",\"photo_id\":{\"id\":\"META_MEDIA_ID\"}}",
"body": "Sent",
"name": "flow"
}
}
}
}
}Parse response_json. Correlate with flow_token. PhotoPicker fields often have Meta media IDs only on the webhook — use Flow Analytics attachments[] or GET /orders/:id → checkout_submission.attachments for ChatYug downloadUrls (Bearer API key).
See Delivery & Retry Policy below for automatic retry behaviour and handler requirements.
After each failed attempt (non-2xx HTTP response, 8-second timeout, or network/DNS error), ChatYug waits before the next attempt:
| After failed attempt | Wait before next try |
|---|---|
| 1 | 1 minute |
| 2 | 2 minutes |
| 3 | 10 minutes |
| 4 | 60 minutes |
| 5 and later | 360 minutes (6 hours) |
This typically results in ~12–13 delivery attempts over the 48-hour window. After 48 hours without a successful delivery, the event is marked failed in ChatYug's delivery log. Contact ChatYug support if you need help recovering missed events.
X-Chatyug-Signature on the raw request body (if a secret is configured).eventId (or X-Chatyug-Event-Id header) against your processed-events store; skip if already handled.200 (or any 2xx) immediately — within 8 seconds.eventId may be delivered more than once during retries (e.g. your server times out after processing but before returning 2xx). Always deduplicate on eventId.
| Setting | Value |
|---|---|
| HTTP timeout per attempt | 8 seconds |
| Rate limit | 300 events per minute per WABA |
| Acknowledgement | Return HTTP 2xx to stop retries for that event |
Full troubleshooting guide: Webhook Retry & Troubleshooting
Author screens in the portal under WhatsApp Messaging → Flow Design (drag-and-drop templates, Approve/Publish, Test Send, Analytics). Use this External API for list/create/publish/send and analytics from your CRM. Lead, survey, and job forms typically use Footer action complete and do not need a Commerce flow endpoint. Configure Commerce Settings endpoint + RSA only when a Footer uses data_exchange (checkout).
Guides: Flow Design Guide · Commerce Flows API & MCP · Dynamic Flow options. On manage paths, flowId is the local ChatYug id; on POST /messages/flow, pass Meta’s meta_flow_id as flowId.
POST /messages/flow with flowToken = order flow_token. Then GET /orders/:id returns checkout_submission (payload + media attachments) when the customer submits — same files as the analytics media endpoints below.
What you are building: a template Flow. Live values arrive in initialScreenData (and optional resolveProviders) when you call POST /messages/flow or use cart auto-send.
Recommended checkout screens:
${data.product_name} / ${data.order_total}; Radio bound to ${data.address_options} (saved addresses + NEW).flowToken = order flow_token so answers appear on GET /orders/:id → checkout_submission.What to put in initialScreenData:
| Data | Flow bind | Send / fill |
|---|---|---|
| Order summary | ${data.product_name}, order_total | Cart auto-send or initialScreenData (+ flowToken) |
| Saved-address picker | Radio ${data.address_options} | [{id,title},…] including {id:"NEW",…} |
| Each saved address | ${data.a1_customer_name}, a1_pincode, … | Same send: a1_*, a2_*, … (ids must match option ids) |
| CRM name / phone | ${data.customer_name} | initialScreenData from your CRM |
| Cities / branches | ${data.cities} | optionLists + resolveProviders: ["commerce_settings_lists"] |
| Cart lines / catalog | cart_items / catalog_options | Matching resolveProviders entry |
Screen-to-screen: Footer navigate payload must include every key on the next screen’s data model, or Meta returns INVALID_NAVIGATE_ACTION_PAYLOAD.
${data…} on WhatsApp means the key was not passed at send time.
Full curl + troubleshooting: Download PDF §3.6.1 · docs guide. No endpoint needed unless Footer uses data_exchange.
curl -X GET https://chatyug.com/api/external/commerce/flows -H "Authorization: Bearer YOUR_API_KEY"
curl -X GET https://chatyug.com/api/external/commerce/flows/12 -H "Authorization: Bearer YOUR_API_KEY"
curl -X POST https://chatyug.com/api/external/commerce/flows \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Checkout Form", "category": "OTHER", "flowJson": { "version": "7.3", "screens": [] }}'curl -X PUT https://chatyug.com/api/external/commerce/flows/12 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "Checkout Form v2", "flowJson": { "version": "7.3", "screens": [] }}'curl -X POST https://chatyug.com/api/external/commerce/flows/12/publish \ -H "Authorization: Bearer YOUR_API_KEY"
Send a published Flow. Pass Meta’s meta_flow_id as flowId. Use flowToken = order flow_token to bind answers to GET /orders/:id → checkout_submission. Webhook: nfm_reply.
initialScreenData is where your CRM puts order summary, address_options, a1_* address fields, CRM name, etc. Optional resolveProviders merges cart lines / settings lists / catalog. See GUIDE accordion + PDF §3.6.1.
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",
"flowToken": "order_1744012345_abc12",
"bodyText": "Complete your delivery details",
"ctaText": "Open",
"initialScreenData": {
"product_name": "Amul Protein Water × 2",
"order_total": "INR 502.00",
"customer_name": "Rahul Sharma",
"address_options": [
{ "id": "1", "title": "Rahul · 392001 · MG Rd" },
{ "id": "NEW", "title": "Add new address" }
],
"a1_choice_id": "1",
"a1_customer_name": "Rahul Sharma",
"a1_mobile_number": "919876543210",
"a1_delivery_address": "12 MG Road",
"a1_city": "Bharuch",
"a1_pincode": "392001"
}
}'Tip: No placeholders? Omit initialScreenId / initialScreenData. Empty navigate {} → Meta #131009. Keep each screen under 100 components.
List send/submit events. Query: flowId (local id), eventType, phone, fromDate, toDate, page, pageSize, healMedia.
Each event includes a flat attachments array and a hasMedia flag for uploaded photos/documents — no need to parse nested payload objects. See the media access accordion below.
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"
format=xlsx (default) or json. Always limited to customer submit rows (form answers).
curl -OJ "https://chatyug.com/api/external/commerce/flows/analytics/export?flowId=12&format=xlsx" \ -H "Authorization: Bearer YOUR_API_KEY"
Download one PhotoPicker / DocumentPicker field from a submit event. Query format=json returns metadata; otherwise streams the file. MCP: get_flow_media.
If the stored copy was pruned, ChatYug re-downloads it from Meta before responding — so this endpoint keeps working when the plain public URL would 404.
# Metadata only curl "https://chatyug.com/api/external/commerce/flows/analytics/events/EVENT_ID/media/photo_75ke?format=json" \ -H "Authorization: Bearer YOUR_API_KEY" # Download the actual file curl -L -o photo.jpg \ "https://chatyug.com/api/external/commerce/flows/analytics/events/EVENT_ID/media/photo_75ke" \ -H "Authorization: Bearer YOUR_API_KEY"
When a customer uploads a photo or document in a Flow Design form, ChatYug stores the file and exposes it on the analytics response. Every event carries a flat attachments array:
{
"id": 69,
"event_type": "submit",
"phone": "919876543210",
"hasMedia": true,
"attachments": [
{
"field": "photo_75ke",
"type": "image",
"fileName": "photo.jpg",
"mimeType": "image/jpeg",
"metaMediaId": "123456789012345",
"url": "https://chatyug.com/received_media/flow/.../image_....jpg",
"downloadUrl": "https://chatyug.com/api/external/commerce/flows/analytics/events/69/media/photo_75ke",
"metadataUrl": "https://chatyug.com/api/external/commerce/flows/analytics/events/69/media/photo_75ke?format=json"
}
]
}| Field | Use it for |
|---|---|
downloadUrl | Recommended. Authenticated download of the real bytes. Self-heals from Meta if the local file is missing. |
metadataUrl | Returns { url, mimeType, fileName } without transferring the file. |
url | Public link (no auth) for embedding. Can 404 if the file was pruned. |
field | Flow Design field name — use as :fieldName on the media endpoint. |
type | image, document, or video (from MIME). |
Two-step integration — list submissions, then download each file:
// 1. List submissions
const res = await fetch(
'https://chatyug.com/api/external/commerce/flows/analytics?flowId=12&eventType=submit',
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const { events } = await res.json();
// 2. Save every uploaded file
for (const ev of events) {
for (const att of ev.attachments || []) {
const file = await fetch(att.downloadUrl, {
headers: { Authorization: `Bearer ${API_KEY}` }
});
const buf = Buffer.from(await file.arrayBuffer());
require('fs').writeFileSync(`${ev.id}-${att.fileName}`, buf);
}
}healMedia=0 to skip it when you only need text answers.export?format=json returns the same attachments array; format=xlsx writes clickable media links into the sheet.404 with the metaMediaId so you can reconcile.
Keyword-triggered automation flows. Requires automation permission on the WABA. Incoming keywords are delivered via the message webhook — your system matches keywords and drives the journey.
curl -X GET "https://chatyug.com/api/external/chatbot/flows?published=true" \ -H "Authorization: Bearer YOUR_API_KEY"
curl -X POST https://chatyug.com/api/external/chatbot/flows \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"flowName": "Shop keyword",
"triggerKeywords": "SHOP,CATALOGUE",
"flowData": { "nodes": [], "edges": [] }
}'curl -X GET https://chatyug.com/api/external/chatbot/flows/42 -H "Authorization: Bearer YOUR_API_KEY"
curl -X PUT https://chatyug.com/api/external/chatbot/flows/42 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"flowName": "Updated name", "isActive": true}'Endpoints for third-party platforms that receive inbound webhooks and need to read conversations, send interactive replies (buttons/lists), and fetch inbound media URLs.
session.sessionOpen based on the last inbound customer message.
curl -X GET https://chatyug.com/api/external/me \ -H "Authorization: Bearer YOUR_API_KEY"
interactiveType: button (1–3 buttons) or list (sections with rows). Use within 24h of customer message. For category browse, pass sections from GET /catalogs/:id/categories → interactiveListSections.
curl -X POST https://chatyug.com/api/external/messages/interactive \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "917016793529",
"interactiveType": "list",
"headerText": "Shop by Category",
"bodyText": "Choose a category to browse products",
"listButtonText": "View Categories",
"sections": [
{
"title": "Categories",
"rows": [
{ "id": "cat_dairy", "title": "Dairy", "description": "3 products" },
{ "id": "cat_kitchen_appliances", "title": "Kitchen Appliances", "description": "5 products" }
]
}
]
}'Customer reply arrives as webhook interactive.list_reply with id = category slug.
curl -X POST https://chatyug.com/api/external/messages/interactive \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phoneNumberId": "YOUR_PHONE_NUMBER_ID",
"to": "917016793529",
"interactiveType": "button",
"bodyText": "Choose distributor",
"buttons": [
{ "id": "DIST_A", "title": "Distributor A" },
{ "id": "DIST_B", "title": "Distributor B" }
]
}'curl -X GET "https://chatyug.com/api/external/conversations?phoneNumberId=YOUR_PHONE_NUMBER_ID&page=1&pageSize=50" \ -H "Authorization: Bearer YOUR_API_KEY"
curl -X GET "https://chatyug.com/api/external/conversations/12345/messages?limit=100&offset=0" \ -H "Authorization: Bearer YOUR_API_KEY"
Returns a stable ChatYug URL for inbound/outbound attachments. If only a Meta media ID is stored, ChatYug downloads and persists under /received_media/. Do not use expired Meta lookaside CDN links.
curl -X GET https://chatyug.com/api/external/messages/98765/media \ -H "Authorization: Bearer YOUR_API_KEY"
Use ChatYug MCP so an AI assistant can help you run WhatsApp Messaging, CRM, Marketing, Commerce, and Chatbot flows (~85 tools) from conversation — without opening every screen yourself. Generate a token in the MCP Tokens section above. Full guide: ChatYug MCP help · tool catalog · usage guidelines.
https://mcp.chatyug.com/mcpAuthorization: Bearer mcp_… (include Bearer and a space)| Client | Where the token goes |
|---|---|
| Claude | Add URL https://mcp.chatyug.com/mcp, leave OAuth Client ID/Secret empty, click Connect, then sign in with ChatYug and Allow. For attached images: allowlist mcp.chatyug.com under Capabilities → Code execution (required), or use the browser upload link if org policy blocks allowlisting. Optional: Request headers / Claude Code with Bearer mcp_…. |
| ChatGPT | Custom connector with the same URL. Prefer OAuth / sign-in if offered; otherwise Bearer mcp_…. |
| Gemini | Web Connected Apps: URL https://mcp.chatyug.com/mcp → Copy redirect URI → create Client ID/Secret at https://mcp.chatyug.com/oauth/gemini-setup → paste into Advanced settings → ChatYug login. CLI: Bearer mcp_… header. |
| Other MCP clients | Same URL; OAuth Connect when supported, otherwise Authorization Bearer header. |
mcp.chatyug.com.prepare_media_upload → curl → send_media_message).Full guideline: ChatYug MCP — sending media.
Trial plans are read-only. Monthly and Annual plans can send messages and update CRM data as allowed. Never share your token in chat or email. Revoke it on this page if it is exposed.
Complete code examples in multiple programming languages:
'719142414620783',
'to' => '919876543210',
'type' => 'template',
'templateName' => 'order_confirmation',
'templateLanguage' => 'en',
'templateVariables' => ['John Doe', 'ORD-12345', '₹1,299']
];
$ch = curl_init($apiUrl);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
'Authorization: Bearer ' . $apiKey,
'Content-Type: application/json'
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
if ($httpCode === 200 && $result['success']) {
echo "Message sent! ID: " . $result['data']['messageId'];
} else {
echo "Error: " . $result['message'];
}
?>
import requests
api_key = "YOUR_API_KEY"
url = "https://chatyug.com/api/external/send-message"
headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
payload = {
"phoneNumberId": "719142414620783",
"to": "917016793529",
"type": "template",
"templateName": "order_confirmation",
"templateLanguage": "en",
"templateVariables": ["John Doe", "ORD-12345", "₹1,299"]
}
response = requests.post(url, headers=headers, json=payload)
if response.status_code == 200:
result = response.json()
print(f"Message sent! ID: {result['data']['messageId']}")
else:
print(f"Error: {response.text}")
const axios = require('axios');
const apiKey = 'YOUR_API_KEY';
const url = 'https://chatyug.com/api/external/send-message';
const payload = {
phoneNumberId: '719142414620783',
to: '919876543210',
type: 'template',
templateName: 'order_confirmation',
templateLanguage: 'en',
templateVariables: ['John Doe', 'ORD-12345', '₹1,299']
};
axios.post(url, payload, {
headers: {
'Authorization': `Bearer ${apiKey}`,
'Content-Type': 'application/json'
}
})
.then(response => {
console.log('Message sent!', response.data.data.messageId);
})
.catch(error => {
console.error('Error:', error.response?.data?.message || error.message);
});
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
var apiKey = "YOUR_API_KEY";
var url = "https://chatyug.com/api/external/send-message";
var httpClient = new HttpClient();
httpClient.DefaultRequestHeaders.Add("Authorization", $"Bearer {apiKey}");
var payload = new
{
phoneNumberId = "719142414620783",
to = "919876543210",
type = "template",
templateName = "order_confirmation",
templateLanguage = "en",
templateVariables = new[] { "John Doe", "ORD-12345", "₹1,299" }
};
var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await httpClient.PostAsync(url, content);
var responseBody = await response.Content.ReadAsStringAsync();
if (response.IsSuccessStatusCode)
{
Console.WriteLine("Message sent!");
Console.WriteLine(responseBody);
}
else
{
Console.WriteLine($"Error: {responseBody}");
}