API Documentation

Introduction

Welcome to our Communication API documentation. This API provides a unified interface to send messages across multiple channels including RCS, SMS, Email, WhatsApp, and Voice.

Base URL

Getting Started

To get started, you'll need an API key. Sign up for an account and generate your API key from the dashboard.

1. Sign up for a developer account
2. Verify your email address
3. Generate your API key from the dashboard
4. Start making requests to the API

Rate Limits

API requests are limited to 1000 requests per hour per API key. If you exceed this limit, you'll receive a 429 Too Many Requests response.

Authentication

All API requests must be authenticated using a Bearer token included in the Authorization header.

How to Authenticate

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY_HERE
Content-Type: application/json

Getting Your API Key

You can generate API keys from your account dashboard. We recommend using different keys for different environments (development, staging, production).

Error Handling

The API uses conventional HTTP response codes to indicate the success or failure of an API request.

HTTP Status Codes

Error Response Format

{
    "error": {
        "code": "invalid_request",
        "message": "The request was invalid",
        "details": {
            "param": "email",
            "reason": "invalid_format"
        }
    }
}

Create SMS Template

This endpoint allows you to create and save a new SMS template. Templates include details like template name, entity ID, template ID, content, and sender ID. Each template is associated with a user and cost is calculated automatically based on SMS parts.

HTTP Request

Request Parameters

Request Payload

{
  "template_name": "otp_alert",
  "entity_id": "1234567890",
  "template_id": "DLT12345",
  "content": "Hello { name }, your OTP is { otp }.",
  "sender_id": "ABCDEF"
}

List SMS Templates

This endpoint retrieves stored SMS templates for the authenticated user. You can fetch all templates or a specific template by passing its {id}. Templates include DLT details, cost, and status labels like Pending for approval, Approved, and Rejected.

HTTP Request

{id} is optional. If provided → returns a single template for this user. If omitted → returns a list of the user's templates (latest first).

Response Fields

Example Response – Single Template

{
  "success": true,
  "data": {
    "template_id": 1,
    "template_name": "otp_alert",
    "entity_id": "1234567890",
    "dlt_template_id": "DLT12345",
    "sender_id": "ABCDEF",
    "status": "Approved",
    "content": "Hello { name }, your OTP is { otp }.",
    "char_count": 32,
    "sms_units": 1,
    "encoding": "GSM-7",
    "cost": 0.25,
    "has_url": false,
    "created_at": "2025-01-01 10:00:00",
    "updated_at": "2025-01-01 10:00:00"
  }
}

Example Response – List

{
  "success": true,
  "data": [
    {
      "template_id": 2,
      "template_name": "promo_sms",
      "entity_id": "1234567890",
      "dlt_template_id": "DLT67890",
      "sender_id": "ABCDEF",
      "status": "Pending for approval",
      "content": "Big sale is live now!",
      "char_count": 25,
      "sms_units": 1,
      "encoding": "GSM-7",
      "cost": 0.25,
      "has_url": false,
      "created_at": "2025-01-02 09:00:00",
      "updated_at": "2025-01-02 09:00:00"
    }, {
            "template_id": 155,
            "template_name": "testing otp Api shreyash",
            "entity_id": "1234567890",
            "dlt_template_id": "1107171290275316198",
            "sender_id": "LFCSPL",
            "status": "Rejected",
            "content": "Dear {name}, your One Time Password (OTP) is {otp}. Please use this code to complete your verification. Do not share this OTP with anyone. This code is valid for a limited time only. Thank you.",
            "char_count": 205,
            "sms_units": 2,
            "encoding": "GSM-7",
            "cost": 4,
            "has_url": false,
            "created_at": "2025-12-24 12:31:31",
            "updated_at": "2025-12-24 12:38:33"
        },
        {
            "template_id": 154,
            "template_name": "testing otp Api shreyash",
            "entity_id": "1234567890",
            "dlt_template_id": "1107171290275316198",
            "sender_id": "LFCSPL",
            "status": "Pending for approval",
            "content": "Dear {name}, your One Time Password (OTP) is {otp}. Please use this code to complete your verification. Do not share this OTP with anyone. This code is valid for a limited time only. Thank you.",
            "char_count": 205,
            "sms_units": 2,
            "encoding": "GSM-7",
            "cost": 4,
            "has_url": false,
            "created_at": "2025-12-24 12:30:45",
            "updated_at": "2025-12-24 12:30:45"
        }
  ]
}

Send SMS

This endpoint allows you to send SMS messages to one or more recipients. It supports both non-personalized (bulk) and personalized (customized per recipient) messages. Unicode messages (e.g., Hindi, Tamil) are also supported.

Note: Personalized messages use an XML-based API and support up to 100 recipients per request. Non-personalized: 300 recipients per request (POST); 200 recipients when using GET with comma-separated numbers.

HTTP Request

GET is also supported for non-personalized only (see below).

Request Parameters (POST)

Request Payload Examples (POST)

{
  "template_id": 123,
  "unicode": 0,
  "personalized": 0,
  "numbers": ["9876543210", "9123456780"]
}

{
  "template_id": 123,
  "unicode": 0,
  "personalized": 1,
  "numbers": [
    { "number": "9876543210", "name": "Sanjay", "otp": "123456" },
    { "number": "9123456780", "name": "Amit", "otp": "654321" }
  ]
}

{
  "senderid": "ABCDEF",
  "message": "Hello {name}, your OTP is {otp}.",
  "unicode": 0,
  "personalized": 1,
  "numbers": [
    { "number": "9876543210", "name": "Sanjay", "otp": "123456" },
    { "number": "9123456780", "name": "Amit", "otp": "654321" }
  ]
}

SMS List Report

This endpoint retrieves the delivery report of a previously sent SMS batch. You must provide the gateway_ref_id (returned as reference_id when sending SMS) to fetch the associated logs for each recipient.

Note: Each SMS message is stored individually in the sms_logs table with per-message details including:

• message_content - The actual message sent to each recipient
• cost - Per-message cost calculated based on SMS units
• sms_units - Number of SMS segments used
• message_length - Character count of the message
• status - Delivery status (submitted, delivered, failed)

HTTP Request

Path Parameter

Example Request

curl -X GET 'https://multichannel.insignsms.com/api/v1/sms/reports/GATEWAY_REF_12345' \
--header 'Authorization: Bearer YOUR_API_KEY'

Create RCS Template

This endpoint allows you to create a new Rich Communication Services (RCS) template. Supported types include: plain text, standalone card, and carousel. Templates must be approved before use.

HTTP Request

Request Parameters

Request Payload Examples (Plain Text - Without Personalization)

Note: Suggestions are optional for plain text templates. Maximum 4 CTA buttons allowed if suggestions are provided.

{
  "template_name": "welcome_message",
  "template_type": "plain_text",
  "data": {
    "content": {
      "plainText": "Welcome to our service! We're here to help you."
    }
  }
}

{
  "template_name": "welcome_message_cta",
  "template_type": "plain_text",
  "data": {
    "content": {
      "plainText": "Welcome to our service! Click below to get started.",
      "suggestions": [
        {
          "action": {
            "plainText": "Visit Website",
            "openUrl": {
              "url": "https://example.com"
            }
          }
        },
        {
          "reply": {
            "plainText": "Get Help",
            "postBack": {
              "data": "help"
            }
          }
        }
      ]
    }
  }
}

Request Payload Examples (Plain Text - With Personalization)

Note: Use variables like {{name}}, {{place}}, {{number}}, {{email}}, {{phone}} for personalization. When sending messages, provide personalization data to replace these variables.

{
  "template_name": "welcome_message_personalized",
  "template_type": "plain_text",
  "data": {
    "content": {
      "plainText": "Hello {{name}}, welcome to our service! Your phone number is {{phone}} and email is {{email}}."
    }
  }
}

{
  "template_name": "welcome_message_personalized_cta",
  "template_type": "plain_text",
  "data": {
    "content": {
      "plainText": "Hello {{name}}, welcome to our service from {{place}}! Your phone number is {{number}}.",
      "suggestions": [
        {
          "action": {
            "plainText": "Visit Website",
            "openUrl": {
              "url": "https://example.com"
            }
          }
        },
        {
          "reply": {
            "plainText": "Get Help",
            "postBack": {
              "data": "help"
            }
          }
        }
      ]
    }
  }
}

Request Payload Examples (Standalone - Without Personalization)

Note: Suggestions are required for standalone templates. Maximum 4 CTA buttons allowed per card.

{
  "template_name": "product_card",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/image.jpg",
                "forceRefresh": false
              }
            },
            "cardTitle": "Special Offer",
            "cardDescription": "Get 50% off on all products today!",
            "suggestions": [
              {
                "action": {
                  "plainText": "Visit Now",
                  "postBack": {
                    "data": "visit_now_election24"
                  },
                  "openUrl": {
                    "url": "https://elections24.eci.gov.in/"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

{
  "template_name": "product_card_reply",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/image.jpg",
                "forceRefresh": false
              }
            },
            "cardTitle": "Special Offer",
            "cardDescription": "Get 50% off on all products today!",
            "suggestions": [
              {
                "reply": {
                  "plainText": "Yes, Absolutely",
                  "postBack": {
                    "data": "suggestion_1"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

{
  "template_name": "calendar_event_card",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/image.jpg",
                "forceRefresh": false
              }
            },
            "cardTitle": "RCS Seminar",
            "cardDescription": "Join us for an informative session",
            "suggestions": [
              {
                "action": {
                  "plainText": "Mark Your Calendar",
                  "postBack": {
                    "data": "SA1L1C1"
                  },
                  "createCalendarEvent": {
                    "startTime": "2023-06-26T15:01:23Z",
                    "endTime": "2023-06-26T18:01:23Z",
                    "title": "RCS Seminar",
                    "description": "Session 1 of 4"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

{
  "template_name": "location_card",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/image.jpg",
                "forceRefresh": false
              }
            },
            "cardTitle": "Visit Our Store",
            "cardDescription": "Find us at our location",
            "suggestions": [
              {
                "action": {
                  "plainText": "Visit Now",
                  "postBack": {
                    "data": "SA1L1C1"
                  },
                  "showLocation": {
                    "coordinAtes": {
                      "latitude": 21.5937,
                      "longitude": 78.9629
                    },
                    "label": "Label - Show Location"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

{
  "template_name": "dialer_card",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/image.jpg",
                "forceRefresh": false
              }
            },
            "cardTitle": "Call Us Now",
            "cardDescription": "Speak with our support team",
            "suggestions": [
              {
                "action": {
                  "plainText": "Dial Now",
                  "postBack": {
                    "data": "SA1L1C1"
                  },
                  "dialerAction": {
                    "phoneNumber": "+918779619155"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

{
  "template_name": "multi_cta_card",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/image.jpg",
                "forceRefresh": false
              }
            },
            "cardTitle": "Special Offer",
            "cardDescription": "Get 50% off on all products today!",
            "suggestions": [
              {
                "action": {
                  "plainText": "Visit Now",
                  "postBack": {
                    "data": "visit_now"
                  },
                  "openUrl": {
                    "url": "https://example.com/"
                  }
                }
              },
              {
                "reply": {
                  "plainText": "Yes, Absolutely",
                  "postBack": {
                    "data": "suggestion_1"
                  }
                }
              },
              {
                "action": {
                  "plainText": "Dial Now",
                  "postBack": {
                    "data": "dial_action"
                  },
                  "dialerAction": {
                    "phoneNumber": "+918779619155"
                  }
                }
              },
              {
                "action": {
                  "plainText": "Show Location",
                  "postBack": {
                    "data": "location_action"
                  },
                  "showLocation": {
                    "coordinAtes": {
                      "latitude": 21.5937,
                      "longitude": 78.9629
                    },
                    "label": "Our Store Location"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

Request Payload Examples (Standalone - With Personalization)

Note: Use variables like {{name}}, {{place}}, {{number}}, {{email}} for personalization. Suggestions are required for standalone templates. When sending messages, provide personalization data to replace these variables.

{
  "template_name": "product_card_personalized",
  "template_type": "standalone",
  "data": {
    "content": {
      "richCardDetails": {
        "standalone": {
          "cardOrientation": "VERTICAL",
          "content": {
            "cardMedia": {
              "mediaHeight": "MEDIUM",
              "contentInfo": {
                "fileUrl": "https://example.com/image.jpg",
                "forceRefresh": false
              }
            },
            "cardTitle": "Special Offer for {{name}}",
            "cardDescription": "Hello {{name}} from {{place}}, get 50% off! Your phone number is {{number}} and email is {{email}}.",
            "suggestions": [
              {
                "action": {
                  "plainText": "Visit Now",
                  "postBack": {
                    "data": "visit_now"
                  },
                  "openUrl": {
                    "url": "https://example.com/"
                  }
                }
              }
            ]
          }
        }
      }
    }
  }
}

Request Payload Examples (Carousel - Without Personalization)

Note: Suggestions are required for each carousel card. Maximum 8 cards allowed per carousel. Maximum 4 CTA buttons allowed per card.

{
  "template_name": "product_carousel",
  "template_type": "carousel",
  "data": {
    "content": {
      "richCardDetails": {
        "carousel": {
          "cardWidth": "MEDIUM_WIDTH",
          "contents": [
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 1",
              "cardDescription": "Description for product 1",
              "suggestions": [
                {
                  "action": {
                    "plainText": "Visit Now",
                    "openUrl": {
                      "url": "https://example.com"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 2",
              "cardDescription": "Description for product 2",
              "suggestions": [
                {
                  "action": {
                    "plainText": "Visit Now",
                    "openUrl": {
                      "url": "https://example.com"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

{
  "template_name": "multi_cta_carousel",
  "template_type": "carousel",
  "data": {
    "content": {
      "richCardDetails": {
        "carousel": {
          "cardWidth": "MEDIUM_WIDTH",
          "contents": [
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Special Offer",
              "cardDescription": "Get 50% off on all products today!",
              "suggestions": [
                {
                  "action": {
                    "plainText": "Visit Now",
                    "openUrl": {
                      "url": "https://example.com/"
                    }
                  }
                },
                {
                  "reply": {
                    "plainText": "Yes, Absolutely",
                    "postBack": {
                      "data": "suggestion_1"
                    }
                  }
                },
                {
                  "action": {
                    "plainText": "Dial Now",
                    "dialerAction": {
                      "phoneNumber": "+918779619155"
                    }
                  }
                },
                {
                  "action": {
                    "plainText": "Show Location",
                    "showLocation": {
                      "coordinAtes": {
                        "latitude": 21.5937,
                        "longitude": 78.9629
                      },
                      "label": "Our Store Location"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

{
  "template_name": "max_cards_carousel",
  "template_type": "carousel",
  "data": {
    "content": {
      "richCardDetails": {
        "carousel": {
          "cardWidth": "MEDIUM_WIDTH",
          "contents": [
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 1",
              "cardDescription": "Description for product 1",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product1"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 2",
              "cardDescription": "Description for product 2",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product2"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 3",
              "cardDescription": "Description for product 3",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product3"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 4",
              "cardDescription": "Description for product 4",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product4"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 5",
              "cardDescription": "Description for product 5",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product5"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 6",
              "cardDescription": "Description for product 6",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product6"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 7",
              "cardDescription": "Description for product 7",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product7"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 8",
              "cardDescription": "Description for product 8",
              "suggestions": [
                {
                  "action": {
                    "plainText": "View Details",
                    "openUrl": {
                      "url": "https://example.com/product8"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

Request Payload Examples (Carousel - With Personalization)

Note: Use variables like {{name}}, {{place}}, {{number}}, {{email}}, {{phone}}, {{product}} for personalization. Suggestions are required for each carousel card. Maximum 8 cards allowed per carousel. When sending messages, provide personalization data to replace these variables.

{
  "template_name": "product_carousel_personalized",
  "template_type": "carousel",
  "data": {
    "content": {
      "richCardDetails": {
        "carousel": {
          "cardWidth": "MEDIUM_WIDTH",
          "contents": [
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 1",
              "cardDescription": "{{name}} form {{place}} and phone number is {{number}} with {{email}}",
              "suggestions": [
                {
                  "action": {
                    "plainText": "Visit Now",
                    "openUrl": {
                      "url": "https://example.com"
                    }
                  }
                }
              ]
            },
            {
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://www.wikihow.com/images/2/22/Get-the-URL-for-Pictures-Step-30-Version-2.jpg"
                }
              },
              "cardTitle": "Product 2",
              "cardDescription": "{{phone}} Description {{name}} for {{product}} 2",
              "suggestions": [
                {
                  "action": {
                    "plainText": "Visit Now",
                    "openUrl": {
                      "url": "https://example.com"
                    }
                  }
                }
              ]
            }
          ]
        }
      }
    }
  }
}

List Templates

This endpoint retrieves stored Rich Communication Services (RCS) templates. You can fetch all templates or a specific template by passing its {id}. Supported types include plain_text, standalone, and carousel.

HTTP Request

{id} is optional. If provided → returns single template. If omitted → returns list of templates.

Response Fields

Example Response – Plain Text

{
  "success": true,
  "data": {
    "template_id": 101,
    "template_name": "welcome_msg",
    "template_type": "plain_text",
    "status": "approved",
    "data": {
      "content": {
        "plainText": "Hello {{ name }}, welcome aboard!",
        "suggestions": [
          {
            "action": {
              "plainText": "ssn",
              "openUrl": {
                "url": "https://example.com"
              }
            }
          },
          {
            "reply": {
              "plainText": "Thanks",
              "postBack": {
                "data": "thanks"
              }
            }
          }
        ]
      }
    }
  }
}

Example Response – Standalone

{
  "success": true,
  "data": {
    "template_id": 102,
    "template_name": "promo_card",
    "template_type": "standalone",
    "status": "approved",
    "data": {
      "content": {
        "richCardDetails": {
          "standalone": {
            "cardOrientation": "VERTICAL",
            "content": {
              "cardTitle": "Big Sale!",
              "cardDescription": "Up to 70% off electronics.",
              "cardMedia": {
                "mediaHeight": "MEDIUM",
                "contentInfo": {
                  "fileUrl": "https://example.com/sale.png"
                }
              },
              "suggestions": [
                {
                  "action": {
                    "plainText": "ssn",
                    "openUrl": {
                      "url": "https://example.com"
                    }
                  }
                },
                {
                  "reply": {
                    "plainText": "Shop Now",
                    "postBack": {
                      "data": "shop"
                    }
                  }
                }
              ]
            }
          }
        }
      }
    }
  }
}

Example Response – Carousel

{
  "success": true,
  "data": {
    "template_id": 103,
    "template_name": "product_carousel",
    "template_type": "carousel",
    "status": "approved",
    "data": {
      "content": {
        "richCardDetails": {
          "carousel": {
            "cardWidth": "MEDIUM",
            "contents": [
              {
                "cardTitle": "Laptop",
                "cardDescription": "Powerful and portable.",
                "cardMedia": {
                  "mediaHeight": "MEDIUM",
                  "contentInfo": {
                    "fileUrl": "https://example.com/laptop.png"
                  }
                },
                "suggestions": [
                  {
                    "action": {
                      "plainText": "ssn",
                      "openUrl": {
                        "url": "https://example.com"
                      }
                    }
                  }
                ]
              },
              {
                "cardTitle": "Smartphone",
                "cardDescription": "Latest Android device.",
                "cardMedia": {
                  "mediaHeight": "MEDIUM",
                  "contentInfo": {
                    "fileUrl": "https://example.com/phone.png"
                  }
                },
                "suggestions": [
                  {
                    "action": {
                      "plainText": "ssn",
                      "openUrl": {
                        "url": "https://example.com"
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      }
    }
  }
}

Send RCS Message

This endpoint allows you to send an RCS message using an approved template. Messages can be sent to multiple contacts (up to 50 numbers per request). The API supports personalization using template variables (e.g., {{name}}, {{email}}) that are replaced with actual values per recipient. When using personalization, only 1 contact is allowed per request.

HTTP Request

Request Parameters

Personalization

Personalization allows you to customize message content per recipient using template variables. Variables in your template should use double curly braces format: {{variableName}}.

• Template Variables: Use {{name}}, {{email}}, {{amount}}, or any custom variable names in your template content.
• Supported Fields: Personalization works in plainText (Type 1), cardTitle and cardDescription (Type 2), and carousel card titles/descriptions (Type 3).
• Limitation: When using personalization, you can only send to 1 contact per request.

Request Payload

Non-Personalized (Bulk Send)

{
    "templateId": 123,
    "contacts": ["9876543210", "9123456780"]
}

Personalized (Single Contact)

{
    "templateId": 123,
    "contacts": ["9876543210"],
    "personalization": [
        {
            "name": "John Doe",
            "email": "john@example.com",
            "amount": "₹1,500"
        }
    ]
}

Create Domain

This endpoint allows you to add and register a new domain for sending emails. You must provide a valid domain name and an envelope name.

HTTP Request

Request Parameters

Request Payload

{
  "domain": "example.com",
  "envelopeName": "noreply"
}

Fetch Domain DNS Records

This endpoint retrieves the required DNS records (DKIM, Custom Envelope, Inbound) for a specific domain that you have registered.

HTTP Request

Path Parameters

Get Domain Status

This endpoint retrieves a list of your domains based on their verification status.

HTTP Request

Path Parameters

Delete Domain

This endpoint allows you to delete a registered domain from your account.

HTTP Request

Path Parameters

Create Email Template

This endpoint allows you to create a reusable email template. You must provide a template name and the HTML content.

HTTP Request

Request Parameters

Request Payload

{
  "template_name": "Welcome Email",
  "type": "html",
  "code_content": "<h1>Welcome [%NAME%]!</h1><p>Your code is: [%CODE%]</p>"
}

List all Templates

This endpoint retrieves a list of all email templates created under your account.

HTTP Request

Response Fields

List Specific Template

This endpoint retrieves a specific email template by its ID.

HTTP Request

Path Parameters

Delete Template

This endpoint allows you to delete a specific email template by its ID.

HTTP Request

Path Parameters

Simple Email Send

This endpoint allows you to send a single email. You can specify the recipient, subject, content, and sender details.

HTTP Request

Request Parameters

Request Payload

{
    "to": "user@example.com",
    "subject": " Test Email",
    "content_string": "<h1>Team Update</h1><p>Important information for the team.</p>",
    "type": "html",
    "from_email": "noreply@yourdomain.com",
    "from_name": "your Company"
}

Rich Email with Personalizations

This endpoint provides advanced options for sending emails, including per-recipient personalization using attributes, using a pre-defined template ID, and attaching files.

HTTP Request

Request Parameters

Multiple Recipients

This endpoint allows you to send the same email to multiple recipients in a single API call. The `to` parameter should be an array of email address strings.

HTTP Request

Request Parameters

Request Payload

{
  "to": ["exampl1@gmail.com", "exampl2@gmail.com"],
  "subject": "Team Update",
  "content_string": "<h1>Team Update</h1><p>Important information for the team.</p>",
  "type": "html",
  "from_email": "example.com",
  "from_name": "Your Company"
}

Template-based Email

Send emails using a pre-defined template. This method is ideal for campaigns where you need to merge dynamic data for each recipient. It also supports enabling or disabling open and click tracking.

HTTP Request

Request Parameters

Request Payload

{
  "from": {
    "email": "example.com",
    "name": "Your Company"
  },
  "template_id": 172,
  "personalizations": [
    {
      "to": [
        {
          "email": "shreyasnalawade2002@gmail.com",
          "name": "John Doe"
        }
      ]
    }
  ],
  "settings": {
    "open_track": true,
    "click_track": true
  }
}

Scheduled Email

This endpoint allows you to schedule an email to be sent at a future time. You must provide a future Unix timestamp for the schedule parameter.

HTTP Request

Request Parameters

Request Payload Examples

Plain Text

{
  "to": "exampl2@gmail.com",
  "subject": "Scheduled Email",
  "content_string": "This email was scheduled to be sent later.",
  "schedule": 1757998707,
  "from_email": "example.com",
  "from_name": "Your Company"
}

HTML Content

{
  "to": "exampl2@gmail.com",
  "subject": "Scheduled Email",
  "content_string": "<h1>Team Update</h1><p>Important information for the team.</p>",
  "type": "html",
  "schedule": 1757998707,
  "from_email": "example.com",
  "from_name": "Your Company"
}

Create Text Template

This endpoint allows you to create a text-based WhatsApp template. Text templates are simple message templates that contain only text content.

HTTP Request

Request Headers

Request Parameters

Request Payload

{
  "name": "template_name_sn2",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, This is a test message from sn",
      "example": {
        "body_text": [
          [
            "John Doe"
          ]
        ]
      }
    }
  ]
}

Create Media Template

This endpoint allows you to create a media-based WhatsApp template. Media templates can include images, videos, or documents along with text content. The media must be uploaded first using the Create Media Handle endpoint to get a media handle.

HTTP Request

Request Payload Example (Document Template)

{
  "name": "TEMPLATE_NAME",
  "language": "en",
  "category": "UTILITY",
  "components": [
    {
      "type": "HEADER",
      "format": "DOCUMENT",
      "example": {
        "header_handle": [
          "4::YXBwbGljYXRpb24vcGRm:ARbRac-7KRV919yIfV5nBwdQ7Gg6EQUyWW_BF8TMpBD_vQES-jRDnh_ljDxHQYqm5blYGoXD1jWowPkPTlQ2Pr2XZwOHoFTW2VM5l2EDBkGQBA:e:1705221283:256725303808337:100052252050649:ARa0nL2E0drGk4fXSCs"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}. Your account is now LIVE, enjoy our services!",
      "example": {
        "body_text": [
          [
            "Name"
          ]
        ]
      }
    }
  ]
}

Request Payload Example (Image Template)

{
  "name": "TEMPLATE_NAME",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "MEDIA_HANDLE_FROM_UPLOAD"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Check out our new product!",
      "example": {
        "body_text": []
      }
    }
  ]
}

Create Location Template

This endpoint allows you to create a location-based WhatsApp template. Location templates include geographic coordinates and location information in the header.

HTTP Request

Request Payload Example

{
  "name": "location_test",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "LOCATION"
    },
    {
      "type": "BODY",
      "text": "Hello {{1}}. Your account is now LIVE, enjoy our services!",
      "example": {
        "body_text": [
          [
            "Name"
          ]
        ]
      }
    }
  ]
}

Create Catalog Template

This endpoint allows you to create a catalog-based WhatsApp template. Catalog templates display product catalogs with images, prices, and descriptions. These templates include a catalog button that opens the business catalog.

HTTP Request

Request Payload Example

{
  "name": "intro_catalog_offer",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Now shop for your favourite products right here on WhatsApp! Get Rs {{1}} off on all orders above {{2}}Rs! Valid for your first {{3}} orders placed on WhatsApp!",
      "example": {
        "body_text": [
          [
            "100",
            "400",
            "3"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Best grocery deals on WhatsApp!"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "CATALOG",
          "text": "View catalog"
        }
      ]
    }
  ]
}

Create Multi Product Template

This endpoint allows you to create a multi-product WhatsApp template. Multi-product templates allow you to showcase multiple products in a single message with a button to view all items.

HTTP Request

Request Payload Example

{
  "name": "abandoned_cart",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Forget something, {{1}}?",
      "example": {
        "header_text": [
          "Pablo"
        ]
      }
    },
    {
      "type": "BODY",
      "text": "Looks like you left these items in your cart, still interested? Use code {{1}} to get 10% off!",
      "example": {
        "body_text": [
          [
            "10OFF"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "MPM",
          "text": "View items"
        }
      ]
    }
  ]
}

Create Carousel Template

This endpoint allows you to create a carousel-based WhatsApp template. Carousel templates display multiple cards in a swipeable format, each with its own header, body, and buttons.

HTTP Request

Request Payload Example

{
  "name": "summer_carousel_sales_2024_v1",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Summer is here, and we have the freshest produce around! Use code {{1}} to get {{2}} off your next order.",
      "example": {
        "body_text": [
          [
            "15OFF",
            "15%"
          ]
        ]
      }
    },
    {
      "type": "CAROUSEL",
      "cards": [
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": {
                "header_handle": [
                  "4::aW1hZ2UvanBlZw==:ARb52CTUac8FTuSZdkoCXGdeoxDZPHtGa3LSZmQjIxGnvDhg3hJQe37IRYld6flatNuZiaa89a6M_23HGH0ylis7w1O6pILkUxR-TrLlKp-mYA:e:1708173546:256725303808337:100052252050649:ARbcwlC3kHgZ7vaMLbQ"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Rare lemons for unique lemon Tea. Use code {{1}} to get {{2}} off all produce.",
              "example": {
                "body_text": [
                  [
                    "LEOOFF15",
                    "15%"
                  ]
                ]
              }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Send more like this"
                },
                {
                  "type": "QUICK_REPLY",
                  "text": "need price detail"
                }
              ]
            }
          ]
        },
        {
          "components": [
            {
              "type": "HEADER",
              "format": "IMAGE",
              "example": {
                "header_handle": [
                  "4::aW1hZ2UvcG5n:ARZrkzRYQS-SePQKO6o4eUFKsYqaEsuBXuuqmE8oJIFOwnrX8-cpujg_887eN0qZPntQnacOHTAZMQuC7WV4nuaJ2S5_9btVL7IJJ34k4f35PA:e:1708174367:256725303808337:100052252050649:ARaGtQPC_FWyQgaXFPk"
                ]
              }
            },
            {
              "type": "BODY",
              "text": "Card 2 Test body {{1}} and {{2}}",
              "example": {
                "body_text": [
                  [
                    "MELONOFF15",
                    "15%"
                  ]
                ]
              }
            },
            {
              "type": "BUTTONS",
              "buttons": [
                {
                  "type": "QUICK_REPLY",
                  "text": "Send more like this"
                },
                {
                  "type": "QUICK_REPLY",
                  "text": "need price detail"
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Create Limited Time Offer Template

This endpoint allows you to create a limited time offer WhatsApp template. These templates are designed for time-sensitive promotions and offers with expiration dates.

HTTP Request

Request Payload Example

{
  "name": "limited_time_offer",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "IMAGE",
      "example": {
        "header_handle": [
          "4::aW1h"
        ]
      }
    },
    {
      "type": "LIMITED_TIME_OFFER",
      "limited_time_offer": {
        "text": "Expiring offer!",
        "has_expiration": true
      }
    },
    {
      "type": "BODY",
      "text": "Good news, {{1}}! Use code {{2}} to get 25% off all Caribbean Destination packages!",
      "example": {
        "body_text": [
          [
            "Harsh",
            "HOTS25"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "COPY_CODE",
          "example": "HOTS25"
        },
        {
          "type": "URL",
          "text": "Book now!",
          "url": "https://awesomedestinations.com/offers?code={{1}}",
          "example": [
            "https://awesomedestinations.com/offers?ref=n3mtql"
          ]
        }
      ]
    }
  ]
}

Create Coupon Code Template

This endpoint allows you to create a coupon code WhatsApp template. Coupon templates include discount codes and promotional offers with a copy code button for easy redemption.

HTTP Request

Request Payload Example

{
  "name": "coupon_code_fall2023_25off",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Our Fall Sale is on!"
    },
    {
      "type": "BODY",
      "text": "Shop now through November and use code {{1}} to get {{2}} off of all merchandise!",
      "example": {
        "body_text": [
          [
            "25OFF",
            "25%"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Unsubscribe"
        },
        {
          "type": "COPY_CODE",
          "example": "250FF"
        }
      ]
    }
  ]
}

Create Call To Action Button Template

This endpoint allows you to create a call-to-action button WhatsApp template. These templates include interactive URL buttons (both dynamic and static) for user actions.

HTTP Request

Request Payload Example

{
  "name": "TEMPLATE_NAME",
  "language": "en",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "Hi {{1}}, This is test template",
      "example": {
        "body_text": [
          [
            "John"
          ]
        ]
      }
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "URL",
          "text": "Dynamic Link",
          "url": "https://www.example.com/{{1}}",
          "example": "https://www.example.com/test"
        },
        {
          "type": "URL",
          "text": "Static Link",
          "url": "https://www.example.com"
        }
      ]
    }
  ]
}

Create Flows Template

This endpoint allows you to create a flows-based WhatsApp template. Flows templates enable interactive experiences with forms and dynamic content. Users can interact with forms, surveys, and other dynamic experiences directly within WhatsApp.

HTTP Request

Request Payload Example

{
  "name": "example_template_name",
  "language": "en_US",
  "category": "MARKETING",
  "components": [
    {
      "type": "BODY",
      "text": "This is a flows as template demo"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "FLOW",
          "text": "Open flow!",
          "flow_id": "",
          "navigate_screen": "Flows Json screen name",
          "flow_action": "navigate"
        }
      ]
    }
  ]
}

Edit Template Category

This endpoint allows you to update the category of an existing WhatsApp template. You can change the category between MARKETING and UTILITY.

HTTP Request

Path Parameters

Request Parameters

Request Payload

{
  "category": "MARKETING"
}

Edit Template Components

This endpoint allows you to update the components of an existing WhatsApp template. You can modify headers, body, footer, and buttons.

HTTP Request

Request Parameters

Request Payload Example

{
  "components": [
    {
      "type": "HEADER",
      "format": "TEXT",
      "text": "Fall Sale"
    },
    {
      "type": "BODY",
      "text": "Hi {{1}}, our Fall Sale is on! Use promo code {{2}} Get an extra 25% off every order above $350!",
      "example": {
        "body_text": [
          [
            "Mark",
            "FALL25"
          ]
        ]
      }
    },
    {
      "type": "FOOTER",
      "text": "Not interested in any of our sales? Tap Stop Promotions"
    },
    {
      "type": "BUTTONS",
      "buttons": [
        {
          "type": "QUICK_REPLY",
          "text": "Stop promotions"
        }
      ]
    }
  ]
}

Get All Templates

This endpoint retrieves a list of all WhatsApp message templates for your WhatsApp Business Account. The response format matches Meta's API response.

HTTP Request

Path Parameters

Query Parameters (Optional)

Get Specific Template

This endpoint retrieves details of a specific WhatsApp message template by its ID. The response format matches Meta's API response.

HTTP Request

Path Parameters

Delete Template

This endpoint allows you to delete a WhatsApp message template. You can delete by template ID (hsm_id) and name, or by name alone.

HTTP Request

Query Parameters

Send Message

This endpoint allows you to send WhatsApp messages. It supports multiple message types including template messages, text messages, media messages, interactive messages, and location messages.

HTTP Request

Note: The {waba_id} in the URL should be replaced with your WhatsApp Business Account ID. However, the actual API uses phone_number_id for sending messages. See individual message type sections for details.

Supported Message Types

• Template Messages: Send messages using approved templates
• Text Messages: Send session text messages
• Media Messages: Send images, videos, documents, audio, or stickers
• Interactive Messages: Send buttons, lists, flows, catalog messages, product messages
• Location Messages: Send location coordinates

Send Text Message

Send a session text message to a WhatsApp user. This is used for customer service conversations within the 24-hour messaging window.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "text",
  "text": {
    "preview_url": false,
    "body": "This is a test message"
  }
}

Request Parameters

Send Media Message

Send media messages including images, videos, documents, audio files, or stickers. Media can be sent by providing a media ID (from uploaded media) or a direct URL.

HTTP Request

Supported Media Types

• image - JPEG, PNG, GIF, WebP
• video - MP4, 3GP
• document - PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX
• audio - MP3, OGG, AMR, M4A
• sticker - WebP

Request Payload Example (Image)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "image",
  "image": {
    "id": "MEDIA-OBJECT-ID"
  }
}

Request Payload Example (Image with URL)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "image",
  "image": {
    "link": "https://example.com/image.jpg",
    "caption": "Optional caption text"
  }
}

Send Interactive Message

Send interactive messages including reply buttons, CTA URL buttons, lists, flows, catalog messages, product messages, and address messages.

HTTP Request

Interactive Message Types

• button - Reply buttons (up to 3 buttons)
• cta_url - Call-to-action URL button
• list - List messages with sections and rows
• flow - Interactive flows
• catalog_message - Catalog message
• product - Single product message
• product_list - Multi-product message
• address_message - Address request message

Request Payload Example (Reply Buttons)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "body": {
      "text": "BUTTON_TEXT"
    },
    "action": {
      "buttons": [
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_1",
            "title": "BUTTON_TITLE_1"
          }
        },
        {
          "type": "reply",
          "reply": {
            "id": "UNIQUE_BUTTON_ID_2",
            "title": "BUTTON_TITLE_2"
          }
        }
      ]
    }
  }
}

Request Payload Example (List)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "PHONE_NUMBER",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": {
      "type": "text",
      "text": "HEADER_TEXT"
    },
    "body": {
      "text": "BODY_TEXT"
    },
    "footer": {
      "text": "FOOTER_TEXT"
    },
    "action": {
      "button": "BUTTON_TEXT",
      "sections": [
        {
          "title": "SECTION_1_TITLE",
          "rows": [
            {
              "id": "SECTION_1_ROW_1_ID",
              "title": "SECTION_1_ROW_1_TITLE",
              "description": "SECTION_1_ROW_1_DESCRIPTION"
            }
          ]
        }
      ]
    }
  }
}

Send Location Message

Send a location message with geographic coordinates. This is useful for sharing business locations, delivery addresses, or meeting points.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "to": "PHONE_NUMBER",
  "type": "location",
  "location": {
    "longitude": -122.425332,
    "latitude": 37.758056,
    "name": "Facebook HQ",
    "address": "1 Hacker Way, Menlo Park, CA 94025"
  }
}

Request Parameters

Mark Message as Read

Mark a message as read. This endpoint allows you to mark incoming messages as read, which updates the read status in WhatsApp.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "status": "read",
  "message_id": "MESSAGE_ID"
}

Request Parameters

Send Text Template Message

Send a text template message to a WhatsApp user. Text templates contain only text content and can include variables for personalization.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "welcome_message",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John"
          }
        ]
      }
    ]
  }
}

Request Parameters

Send Media Template

Send a template message with media (image, video, or document) in the header. The media can be static or include variables.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "product_promo",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/image.jpg"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "50%"
          }
        ]
      }
    ]
  }
}

Media Types

• Image: Use "type": "image" with image.link or image.id
• Video: Use "type": "video" with video.link or video.id
• Document: Use "type": "document" with document.link or document.id

Send Interactive Template

Send a template message with interactive buttons (quick reply buttons or call-to-action buttons). Interactive templates allow users to respond quickly with predefined options.

HTTP Request

Request Payload (Quick Reply Buttons)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "survey_template",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": "0",
        "parameters": [
          {
            "type": "payload",
            "payload": "YES"
          }
        ]
      }
    ]
  }
}

Send Location Template

Send a template message with a location in the header. The location can be static or include variables for dynamic locations.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "store_location",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": 19.0760,
              "longitude": 72.8777,
              "name": "Mumbai Store",
              "address": "123 Main Street, Mumbai"
            }
          }
        ]
      }
    ]
  }
}

Send Template (with variables)

Send a template message with dynamic variables. Variables allow you to personalize template messages with user-specific data like names, dates, amounts, etc.

HTTP Request

Request Payload (Multiple Variables)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "ORD-12345"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "John Doe"
          },
          {
            "type": "text",
            "text": "$99.99"
          },
          {
            "type": "text",
            "text": "2024-01-15"
          }
        ]
      }
    ]
  }
}

Variable Types

• Text: Use "type": "text" with text parameter
• Currency: Use "type": "currency" with currency object
• DateTime: Use "type": "date_time" with date_time object

Send Template (CTA Button)

Send a template message with Call-to-Action (CTA) buttons. CTA buttons can include URL buttons or phone number buttons that allow users to take immediate action.

HTTP Request

Request Payload (URL Button)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "promo_template",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "https://example.com/promo"
          }
        ]
      }
    ]
  }
}

Request Payload (Phone Number Button)

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "contact_template",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "button",
        "sub_type": "phone_number",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "+919321012345"
          }
        ]
      }
    ]
  }
}

Send Authentication Template

Send an authentication template message with a one-time password (OTP) for user verification. Authentication templates are used for login, account verification, and security purposes.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "otp_verification",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "123456"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "https://example.com/verify?code=123456"
          }
        ]
      }
    ]
  }
}

Send Catalog Template Message

Send a template message that displays a product from your catalog. This allows customers to view product details directly in WhatsApp.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "product_showcase",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "PRODUCT123"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "catalog",
            "catalog_id": "CATALOG_ID",
            "product_retailer_id": "PRODUCT123"
          }
        ]
      }
    ]
  }
}

Send Multi-Product Template

Send a template message that displays multiple products from your catalog in a single message. This is useful for showcasing product collections or related items.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "product_collection",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Summer Collection"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "product_list",
            "catalog_id": "CATALOG_ID",
            "product_items": [
              {
                "product_retailer_id": "PRODUCT123"
              },
              {
                "product_retailer_id": "PRODUCT456"
              },
              {
                "product_retailer_id": "PRODUCT789"
              }
            ]
          }
        ]
      }
    ]
  }
}

Send Carousel Template

Send a template message with a carousel of products or items. Carousel templates display multiple cards that users can swipe through horizontally.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "product_carousel",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "Featured Products"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Check out our latest collection"
          }
        ]
      }
    ]
  }
}

Note: Carousel templates are created at template creation time. When sending, you reference the carousel template name and provide any required variables.

Send Coupon Code Template

Send a template message with a coupon code for discounts or promotions. Coupon code templates help drive customer engagement and conversions.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "coupon_promo",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "SAVE50"
          },
          {
            "type": "text",
            "text": "50%"
          },
          {
            "type": "text",
            "text": "2024-12-31"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "https://example.com/redeem?code=SAVE50"
          }
        ]
      }
    ]
  }
}

Send Limited Time Offer Template

Send a template message with a limited-time offer or flash sale. These templates create urgency and encourage immediate action from customers.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "flash_sale",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "text",
            "text": "Flash Sale - 24 Hours Only!"
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "70%"
          },
          {
            "type": "text",
            "text": "2024-01-20 23:59:59"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "text",
            "text": "https://example.com/sale"
          }
        ]
      }
    ]
  }
}

Send Flows Template

Send a template message with a WhatsApp Flow. Flows enable rich, interactive experiences within WhatsApp, allowing users to complete forms, surveys, bookings, and more without leaving the chat.

HTTP Request

Request Payload

{
  "messaging_product": "whatsapp",
  "recipient_type": "individual",
  "to": "+919321012345",
  "type": "template",
  "template": {
    "name": "booking_flow",
    "language": {
      "code": "en"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Book your appointment"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": "0",
        "parameters": [
          {
            "type": "flow",
            "flow_token": "FLOW_TOKEN",
            "flow_id": "FLOW_ID",
            "flow_cta": "Book Now",
            "flow_action_payload": {
              "screen": "BOOKING_SCREEN"
            }
          }
        ]
      }
    ]
  }
}

Flow Parameters

Get Media by ID

Retrieve media metadata and URL from a media ID. This is useful when you receive a media ID in webhooks and need to fetch the actual media file.

HTTP Request

Path Parameters

Get Media by URL

Download media content from a media URL. This endpoint fetches the actual media file (image, video, document, etc.) from the provided URL.

HTTP Request

Query Parameters

Upload Media

Upload a media file to create a media ID that can be used for sending media messages. Supports images, videos, documents, audio files, and stickers (max 25MB).

HTTP Request

Request Parameters (Multipart Form Data)

Create Media Handle

Upload a media file to create a media handle. creates a media handle that can be used in template creation.

HTTP Request

Request Parameters (Multipart Form Data)

Create Voice Template

This endpoint allows you to create a simple voice broadcast template. The template will be created with a clip ID (campaign ID) from the voice gateway. Audio duration is automatically calculated from the provided audio URL or file.

HTTP Request

Request Parameters

Request Payload Example

{
  "template_name": "welcome_call",
  "audio_url": "https://example.com/audio/welcome.mp3"
}

Response

Success Response (201 Created)

{
  "success": true,
  "message": "Template created successfully and is pending approval.",
  "clip_id": "1dd74936699b11edadb60cc47a338ee6"
}

The clip_id is the campaign ID returned from the voice gateway. Use this clip_id when sending voice messages.

Create Voice DTMF Template

This endpoint allows you to create a voice template with DTMF (Dual-Tone Multi-Frequency) capture capabilities. This enables interactive voice calls where recipients can press keys on their phone to provide input.

HTTP Request

Request Parameters

Request Payload Example

{
  "template_name": "survey_call",
  "audio_url": "https://example.com/audio/survey.mp3",
  "dtmflength": "1",
  "dtmftimeout": "10",
  "retry": "2",
  "retrykey": "0"
}

Response

Success Response (201 Created)

{
  "success": true,
  "message": "Template created successfully and is pending approval.",
  "clip_id": "2ee85047700c22fedea71dd58b449ff7"
}

List Voice Templates

This endpoint retrieves voice templates. You can fetch all templates or a specific template by passing its ID.

HTTP Request

{id} is optional. If provided → returns single template. If omitted → returns list of templates.

Response Fields

Response Example

{
  "success": true,
  "templates": [
    {
      "id": 1,
      "template_name": "welcome_call",
      "clip_id": "1dd74936699b11edadb60cc47a338ee6",
      "audio_file": "https://example.com/audio/welcome.mp3",
      "duration": "30",
      "type": "1",
      "status": "1",
      "created_at": "2025-01-15T10:30:00.000000Z"
    }
  ],
  "count": 1
}

Send Voice Message

This endpoint allows you to send voice calls to one or more recipients using an approved template. The message is processed asynchronously via Kafka, and you'll receive a reference ID immediately.

HTTP Request

Request Parameters

Request Payload Example

{
  "clip_id": "1dd74936699b11edadb60cc47a338ee6",
  "numbers": ["9876543210", "9123456780"],
  "retry": 2,
  "retrytime": 900
}

Note: retry and retrytime are optional. If both are 0 or not provided, no retries will be attempted.

Response

Success Response (202 Accepted)

{
  "status": "accepted",
  "referenceId": "c6b9d8e4-12f3-4b9c-9f8a-abcdef123456"
}

The referenceId is a local reference ID. Use this to track the batch status. The actual gateway reference ID will be available in the report after processing.

Get Voice Report

This endpoint retrieves the delivery report of a previously sent voice batch. You must provide the batch_id (returned from the send message response or from the batch record) to fetch the associated logs for each recipient.

HTTP Request

Path Parameter

Response Example

{
  "success": true,
  "batch": {
    "id": 1,
    "user_id": 7,
    "template_id": 1,
    "clip_id": "1dd74936699b11edadb60cc47a338ee6",
    "gateway_ref_id": "ACK123456",
    "total_numbers": 2,
    "status": "submitted",
    "cost": 0.50,
    "duration": "30",
    "created_at": "2025-01-15T12:34:56.000000Z"
  },
  "logs": [
    {
      "id": 1,
      "voice_batch_id": 1,
      "recipient_number": "9876543210",
      "status": "submitted",
      "reference_id": "ACK123456",
      "duration": null,
      "dtmf": null,
      "error_code": null,
      "error_message": null,
      "created_at": "2025-01-15T12:34:56.000000Z"
    },
    {
      "id": 2,
      "voice_batch_id": 1,
      "recipient_number": "9123456780",
      "status": "submitted",
      "reference_id": "ACK123456",
      "duration": null,
      "dtmf": null,
      "error_code": null,
      "error_message": null,
      "created_at": "2025-01-15T12:34:56.000000Z"
    }
  ]
}

Postman API Collections

Download ready-to-use Postman collections for each service. These collections include all endpoints with pre-configured requests, examples, and response schemas. Simply import the JSON file into Postman and start testing immediately.