> ## Documentation Index
> Fetch the complete documentation index at: https://help.commbox.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Send a WhatsApp template message from Emarsys
> API that enables Emarsys automation workflows to send pre-approved WhatsApp templates to recipients. This specialized endpoint processes webhook data from Emarsys using a simplified flat key-value format, allowing seamless integration between Emarsys marketing automations and WhatsApp business messaging via CommBox.
## OpenAPI
````json POST /emarsys/sendwhatsapptemplate/{ENCRYPTED_STREAM_ID}
{
"openapi": "3.0.3",
"info": {
"title": "CommBox API",
"x-logo": {
"url": "https://www.commbox.io/logo/commbox_logo_large.png"
},
"version": "2.07",
"termsOfService": "https://www.commbox.io/end-user-license-agreement-eula/",
"contact": {
"name": "commbox",
"url": "https://www.commbox.io",
"email": "contactus@commbox.io"
}
},
"servers": [
{
"url": "https://api.commbox.io/",
"description": "Production server"
}
],
"security": [
{
"BearerAuth": []
}
],
"tags": [
{
"name": "Core",
"description": "
Systemwide verification"
},
{
"name": "Objects",
"description": "
Objects are conversations between the AI Agent or the human agent and the customers, where each segment of the conversation is referred to as a Child. Every conversation must have a designated Stream – a communication channel such as Chat, Email, Text/SMS, etc., through which the conversation takes place.
The Object APIs category concentrates on a specific conversation, where the Stream is part of the identifying parameters. In contrast, the Streams APIs category, the Channel is the focal point of the request, and the objects and users are the filtering aspects."
},
{
"name": "Media",
"description": "Converting media files to Base64"
},
{
"name": "AI Services",
"description": "APIs that provide AI capabilities by the platform. "
},
{
"name": "Streams",
"description": "
Streams are communication channels used in CommBox, such as Chat, WhatsApp, SMS/Text, etc. In the Streams category of APIs, the channel is the focal point of the request, and the objects and users are the filtering aspects. See the Enums Section for available channels and their CommBox code."
},
{
"name": "Tags",
"description": "
Tags are a classification tool for summarizing aspects of the conversation or the user. It can mark the conversation to indicate a new sale or identify a customer as not interested in the product. To help manage the Tags assets, Tags can be grouped with a common identifier."
},
{
"name": "SMS",
"description": "
Sending customers **SMS messages** (Texting) requires an initial opt-in step, which is not offered by CommBox and is the sole responsibility of the sending entity (Business)."
},
{
"name": "WhatsApp",
"description": "
CommBox facilitates activities in **WABA** for the clients. Our platform helps clients create new templates and manage existing ones.
**Opt-in for WhatsApp**
Before sending WhatsApp messages to someone, you must first receive opt-in permission confirming that they wish to receive future messages from you on WhatsApp. This can be done using any channel your business uses to communicate with people — your website, app, email, retail location, etc.- The opt-in must be an active opt-in, which means it must be triggered by a user action, such as entering a phone number or checking a box to indicate consent.
- The opt-in must clearly state your business’ name.
- Clear opt-in messaging so that the customers know what type(s) of messaging they are signing up for.
For more information, please visit: https://developers.facebook.com/docs/whatsapp/guides/opt-in/"
},
{
"name": "Campaigns",
"description": "Send WhatsApp campaigns via an API. Campaigns are reflected in the metrics page in the platform."
},
{
"name": "Users",
"description": "
**Users** are people recorded in CommBox and they include both the business side and the customers.
Managers are APIs that deal with the business personas such as Admins, Agents, Team leaders, etc., and they include **Profiles**, **Presence**, **Assignments**, **Notifications**, and **Teams** sub-categories.
General USERS"
},
{
"name": "Managers",
"description": "
The **MANAGERS** APIs category relates to activities involving the Admins, Team Leaders, Agents, and any other business-related persona. This category includes **Profiles**, **Presence**, **Assignments**, **Notifications**, and **Teams** sub-categories."
},
{
"name": "Profiles",
"description": "
**Profiles** relate to system permissions and enabled activities assigned to a group of agents (managers).
When looking for a specific user, the USER ID is required.
The profile ID is required when selecting a specific profile (See Enum section)."
},
{
"name": "Presence",
"description": "
The Presence APIs relate to the agent availability status. Active and ready for assignment, Busy, or Away from the desk. Additional statuses can be created by the admin."
},
{
"name": "Assignments",
"description": "
The **Assignments** category relates to conversations (Objects) assigned to a specific agent."
},
{
"name": "Teams",
"description": "A Team is a group of agents with specific business agendas, roles, and permissions. Admins and Team Managers can set up Team Managers to create and manage teams and give those teams specific inbox filters, tags, and knowledge-based assets."
},
{
"name": "Audiences",
"description": "The Audiences APIs allow the creation, editing and listing of organizational audiences used for campaigns."
},
{
"name": "Forms",
"description": "The Forms APIs allow agents to assist customers in completing and signing forms issued by the organization. Once the customer submits the form, a new object is created that includes a link to the original conversation and stores the completed, signed form as an attachment."
},
{
"name": "Authentication",
"description": "Authentication APIs provide accessibility to the system."
},
{
"name": "Automation",
"description": "
Automation APIs are related to chatbot capabilities."
},
{
"name": "Transcription",
"description": "
**Transcription** turns a call recording into readable, speaker-attributed messages inside the conversation."
}
],
"x-tagGroups": [
{
"name": "API Calls",
"tags": [
"Core",
"Objects",
"Media",
"AI Services",
"Streams",
"Tags",
"SMS",
"WhatsApp",
"Users",
"Managers",
"Profiles",
"Presence",
"Assignments",
"Teams",
"Audiences",
"Forms",
"Authentication",
"Automation"
]
}
],
"paths": {
"/emarsys/sendwhatsapptemplate/{ENCRYPTED_STREAM_ID}": {
"post": {
"tags": [
"WhatsApp"
],
"summary": "Send a WhatsApp template message from Emarsys",
"description": "API that enables Emarsys automation workflows to send pre-approved WhatsApp templates to recipients. This specialized endpoint processes webhook data from Emarsys using a simplified flat key-value format, allowing seamless integration between Emarsys marketing automations and WhatsApp business messaging via CommBox.\n",
"operationId": "EmarsysSendWhatsAppTemplate",
"parameters": [
{
"in": "path",
"name": "ENCRYPTED_STREAM_ID",
"required": true,
"schema": {
"type": "string"
},
"description": "The encrypted stream identifier for your WhatsApp channel in CommBox"
}
],
"security": [
{
"jwtAuth": []
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WhatsAppEmarsysTemplateRequest"
},
"examples": {
"basicTemplate": {
"summary": "Basic text-only template",
"value": {
"to": "9725551234",
"templateName": "simple_notification",
"template.language.code": "en"
}
},
"templateWithBodyParams": {
"summary": "Template with body parameters",
"value": {
"to": "9725551234",
"templateName": "multiple_params_in_body",
"template.language.code": "en_GB",
"body.1.value": "https://www.commbox.io",
"body.2.value": "Product Launch",
"body.3.value": "March 15th"
}
},
"templateWithHeaderParam": {
"summary": "Template with text header and body parameter",
"value": {
"to": "9725551234",
"templateName": "text_header_body",
"template.language.code": "en",
"header.type": "text",
"header.value": "Important Update",
"body.1.value": "Your order has shipped"
}
},
"documentAttachment": {
"summary": "Template with document attachment",
"value": {
"to": "9725551234",
"templateName": "document_template",
"template.language.code": "en_US",
"header.type": "document",
"header.value": "https://www.example.com/resources/document.pdf",
"header.filename": "product-catalog.pdf",
"body.1.value": "Our latest catalog"
}
},
"imageAttachment": {
"summary": "Template with image attachment",
"value": {
"to": "9725551234",
"templateName": "image_template",
"template.language.code": "en",
"header.type": "image",
"header.value": "https://www.example.com/images/product.jpg",
"body.1.value": "Check out our new product!"
}
},
"imageAttachmentWithMediaId": {
"summary": "Template with image attachment using Media ID",
"value": {
"to": "9725551234",
"templateName": "image_template",
"template.language.code": "en",
"header.type": "image",
"header.value": "913225593849516",
"body.1.value": "Check out our new product!"
}
},
"videoAttachment": {
"summary": "Template with video attachment",
"value": {
"to": "9725551234",
"templateName": "video_template",
"template.language.code": "en",
"header.type": "video",
"header.value": "https://www.example.com/videos/product-demo.mp4",
"body.1.value": "Product demonstration"
}
},
"videoAttachmentWithMediaId": {
"summary": "Template with video attachment using Media ID",
"value": {
"to": "9725551234",
"templateName": "video_template",
"template.language.code": "en",
"header.type": "video",
"header.value": "27f8b007-7750-418e-9852-b4f8b7f95b9f",
"body.1.value": "Product demonstration"
}
},
"documentAttachmentWithMediaId": {
"summary": "Template with document attachment using Media ID",
"value": {
"to": "9725551234",
"templateName": "document_template",
"template.language.code": "en",
"header.type": "document",
"header.value": "550197337025434",
"header.filename": "file-sample_150kB.pdf",
"body.1.value": "PDF document"
}
},
"dynamicButton": {
"summary": "Template with dynamic URL button",
"value": {
"to": "9725551234",
"templateName": "dynamic_url",
"template.language.code": "en",
"button.value": "https://www.commbox.io/support?user=12345",
"body.1.value": "Click for support"
}
},
"callButton": {
"summary": "Template with Call a Phone Number button",
"value": {
"to": "9725551234",
"templateName": "Call_a_phone_num_btn",
"template.language.code": "en"
}
},
"multipleButtons": {
"summary": "Template with Call and Visit Website buttons",
"value": {
"to": "9725551234",
"templateName": "Call_and_Visit_a_Website_btns",
"template.language.code": "en"
}
},
"staticUrlButton": {
"summary": "Template with Static URL button",
"value": {
"to": "9725551234",
"templateName": "static_url",
"template.language.code": "en",
"body.1.value": "Your Name"
}
},
"quickReplyButtons": {
"summary": "Template with Quick Reply buttons",
"value": {
"to": "9725551234",
"templateName": "3 buttons",
"template.language.code": "en",
"body.1.value": "Your Name"
}
},
"authTemplate": {
"summary": "Authentication template with copy button",
"value": {
"to": "9725551234",
"templateName": "auth_template",
"template.language.code": "en",
"button.value": "COPY",
"body.1.value": "455455"
}
},
"createConversationObject": {
"summary": "Template with conversation object creation",
"value": {
"to": "9725551234",
"templateName": "customer_support",
"template.language.code": "en",
"body.1.value": "Order #12345",
"object.substreamid": 0,
"object.statusid": 1,
"object.content": "{\"orderId\":\"12345\"}",
"object.user.uniqueid": "67890",
"object.user.lastname": "Doe",
"object.user.firstname": "John",
"object.user.phone1": "9725551234",
"object.user.email": "john.doe@example.com",
"object.user.remarks": "Returning customer"
}
},
"documentWithObjectData": {
"summary": "Document template with conversation object creation",
"value": {
"to": "9725551234",
"templateName": "doc1",
"template.language.code": "en",
"header.type": "document",
"header.value": "https://denverzoo.org/wp-content/uploads/2018/09/African-lion.pdf",
"header.filename": "African-lion.pdf",
"body.1.value": "hello",
"object.substreamid": 0,
"object.statusid": 1,
"object.content": "{}",
"object.user.uniqueid": "01234567",
"object.user.lastname": "Doe",
"object.user.firstname": "John",
"object.user.phone1": "9725551234",
"object.user.email": "john.doe@example.com",
"object.user.remarks": "some remark for user"
}
},
"scheduledMessage": {
"summary": "Scheduled template message",
"value": {
"to": "9725551234",
"templateName": "reminder",
"template.language.code": "en",
"body.1.value": "appointment tomorrow",
"schedule": 1739365010
}
}
}
},
"application/x-www-form-urlencoded": {
"schema": {
"$ref": "#/components/schemas/WhatsAppEmarsysTemplateRequest"
}
}
}
},
"responses": {
"200": {
"description": "Operation successful",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
},
"example": {
"status": "200",
"description": "Operation successful",
"response_time": "2024-08-06T07:51:52.2581942Z",
"data": [
{
"recipient": "9725551234",
"id": "gBEGlyVGZjUpAgmyuqAHfxbHmnQ",
"status": 200,
"object_id": 38383744
}
]
}
}
}
},
"206": {
"description": "Partial success (some messages succeeded, some failed)",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PartialSuccessResponse"
},
"example": {
"status": "206",
"description": "Some messages failed",
"response_time": "2024-08-06T07:51:52.2581942Z",
"data": [
{
"recipient": "9725551234",
"id": "gBEGlyVGZjUpAgmyuqAHfxbHmnQ",
"status": 200,
"object_id": 38383744
},
{
"recipient": "9725559876",
"status": 400,
"failed": "invalid — Not a valid WhatsApp user"
}
]
}
}
}
},
"400": {
"description": "Bad request, could not process the input data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ErrorResponse"
},
"example": {
"status": "400",
"description": "Missing parameter templateName",
"response_time": "2024-08-06T07:51:52.2581942Z",
"data": [
{
"recipient": "9725551234",
"status": 400,
"failed": "Missing required parameter"
}
]
}
}
}
},
"401": {
"description": "Unauthorized - The supplied credentials, if any, are not sufficient to access the resource",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 401
},
"description": {
"type": "string",
"example": "Unauthorized"
},
"response_time": {
"type": "string",
"format": "date-time",
"example": "2025-02-06T07:51:52.2581942Z"
}
}
}
}
}
},
"404": {
"description": "Not found - The requested resource is not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 404
},
"description": {
"type": "string",
"example": "Not Found"
},
"response_time": {
"type": "string",
"format": "date-time",
"example": "2025-02-06T07:51:52.2581942Z"
}
}
}
}
}
},
"429": {
"description": "Too Many Requests - Too many requests have been made in a short period of time (Throttling)",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 429
},
"description": {
"type": "string",
"example": "Too Many Requests"
},
"response_time": {
"type": "string",
"format": "date-time",
"example": "2025-02-06T07:51:52.2581942Z"
}
}
}
}
}
},
"500": {
"description": "Server Error - The server could not return the representation due to an internal server error",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"status": {
"type": "integer",
"example": 500
},
"description": {
"type": "string",
"example": "Internal Server Error"
},
"response_time": {
"type": "string",
"format": "date-time",
"example": "2025-02-06T07:51:52.2581942Z"
}
}
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"WhatsAppEmarsysTemplateRequest": {
"type": "object",
"required": [
"to",
"templateName",
"template.language.code"
],
"properties": {
"to": {
"type": "string",
"description": "The recipient's phone number with country code (no + symbol)",
"example": "9725551234"
},
"templateName": {
"type": "string",
"description": "The name of the approved WhatsApp template",
"example": "welcome_message"
},
"template.language.code": {
"type": "string",
"description": "The language code for the template",
"example": "en"
},
"schedule": {
"type": "integer",
"description": "Unix timestamp for scheduled message delivery (optional)",
"example": 1739365010
},
"header.type": {
"type": "string",
"description": "Type of header content (if template has a header)",
"enum": [
"text",
"image",
"document",
"video"
],
"example": "image"
},
"header.value": {
"type": "string",
"description": "Content for the header (URL or Media ID)",
"example": "https://example.com/image.jpg"
},
"header.filename": {
"type": "string",
"description": "Filename for document attachments (required for document headers)",
"example": "product-catalog.pdf"
},
"body.1.value": {
"type": "string",
"description": "Content for the first body placeholder",
"example": "John"
},
"body.2.value": {
"type": "string",
"description": "Content for the second body placeholder",
"example": "Premium Plan"
},
"body.3.value": {
"type": "string",
"description": "Content for the third body placeholder",
"example": "March 15, 2025"
},
"button.value": {
"type": "string",
"description": "Dynamic value for button (if template has dynamic buttons)",
"example": "https://example.com/support"
},
"object.substreamid": {
"type": "integer",
"description": "The substream ID in CommBox (for conversation object creation)",
"example": 0
},
"object.statusid": {
"type": "integer",
"description": "The status ID in CommBox (for conversation object creation)",
"example": 1
},
"object.content": {
"type": "string",
"description": "Additional content for the conversation object (JSON string)",
"example": "{\"subject\":\"Welcome Message\"}"
},
"object.user.uniqueid": {
"type": "string",
"description": "Unique identifier for the user",
"example": "12345678"
},
"object.user.lastname": {
"type": "string",
"description": "User's last name",
"example": "Doe"
},
"object.user.firstname": {
"type": "string",
"description": "User's first name",
"example": "John"
},
"object.user.phone1": {
"type": "string",
"description": "User's phone number",
"example": "9725551234"
},
"object.user.email": {
"type": "string",
"description": "User's email address",
"example": "john.doe@example.com"
},
"object.user.remarks": {
"type": "string",
"description": "Additional notes about the user",
"example": "Returning customer"
}
},
"additionalProperties": true,
"description": "Request schema for sending WhatsApp template messages. The minimal required parameters are\nto, templateName, and template.language.code. Additional parameters depend on the template\nstructure and whether conversation objects should be created in CommBox.\n"
},
"SuccessResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Status code as string",
"example": "200"
},
"description": {
"type": "string",
"description": "Human-readable description of the response",
"example": "Operation successful"
},
"response_time": {
"type": "string",
"description": "Timestamp of the response",
"example": "2024-08-06T07:51:52.2581942Z"
},
"data": {
"type": "array",
"description": "Array of recipient results",
"items": {
"type": "object",
"properties": {
"recipient": {
"type": "string",
"description": "Recipient's phone number",
"example": "9725551234"
},
"id": {
"type": "string",
"description": "Message ID from WhatsApp",
"example": "gBEGlyVGZjUpAgmyuqAHfxbHmnQ"
},
"status": {
"type": "integer",
"description": "Status code for this recipient",
"example": 200
},
"object_id": {
"type": "integer",
"description": "CommBox conversation object ID (if created)",
"example": 38383744
}
}
}
}
},
"required": [
"status",
"description",
"response_time",
"data"
]
},
"PartialSuccessResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Status code as string",
"example": "206"
},
"description": {
"type": "string",
"description": "Human-readable description of the response",
"example": "Some messages failed"
},
"response_time": {
"type": "string",
"description": "Timestamp of the response",
"example": "2024-08-06T07:51:52.2581942Z"
},
"data": {
"type": "array",
"description": "Array of recipient results (mix of success and failure)",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"recipient": {
"type": "string",
"example": "9725551234"
},
"id": {
"type": "string",
"example": "gBEGlyVGZjUpAgmyuqAHfxbHmnQ"
},
"status": {
"type": "integer",
"example": 200
},
"object_id": {
"type": "integer",
"example": 38383744
}
}
},
{
"type": "object",
"properties": {
"recipient": {
"type": "string",
"example": "9725559876"
},
"status": {
"type": "integer",
"example": 400
},
"failed": {
"type": "string",
"example": "invalid — Not a valid WhatsApp user"
}
}
}
]
}
}
},
"required": [
"status",
"description",
"response_time",
"data"
]
},
"ErrorResponse": {
"type": "object",
"properties": {
"status": {
"type": "string",
"description": "Error status code as string",
"example": "400"
},
"description": {
"type": "string",
"description": "Human-readable description of the error",
"example": "Missing parameter templateName"
},
"response_time": {
"type": "string",
"description": "Timestamp of the response",
"example": "2024-08-06T07:51:52.2581942Z"
},
"data": {
"type": "array",
"description": "Array of recipient error details",
"items": {
"type": "object",
"properties": {
"recipient": {
"type": "string",
"description": "Recipient's phone number",
"example": "9725551234"
},
"status": {
"type": "integer",
"description": "Error status code",
"example": 400
},
"failed": {
"type": "string",
"description": "Failure reason",
"example": "Missing required parameter"
}
}
}
}
},
"required": [
"status",
"description",
"response_time"
]
}
},
"securitySchemes": {
"jwtAuth": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "JWT",
"description": "JWT token for authentication. The token should be generated using the Secret Key\nprovided in the CommBox Emarsys Module settings.\n"
},
"BearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "API key is needed to authorize requests. You can get your API key via the management console. A Bearer Token is needed to be set in the Authorization header of every API call. For additional support you can contact us."
}
}
}
}
````