Add a Message Campaign

Add a message campaign, either SMS campaign or WhatsApp campaign.

Request URL

POST {base_url}/{api_path}/message_campaign/create?access_token={access_token}

Request parameters

Parameter	Required	Type	Description
name	Yes	String	The name of the message campaign.
channel_type	Yes	String	The type of the message channel used by the campaign.Valid value: sms: SMS channel. whatsapp: WhatsApp channel.
omnichannel_id	Yes	Integer	The ID of the message channel used by the campaign. Note: You can query the ID using Search Specific Message Channels.
sender	Yes	Integer	The ID of the number associated with the specified message channel. Note: You can query the ID using Search Specific Message Channels.
recipient_type	Yes	String	The method used to add recipients to the campaign. Valid value: input: Add recipients by manual input. phonebook: Add recipients from a specified phonebook.
number_list	No	Array <Number_List>	The phone numbers for the campaign. Note: This parameter is REQUIRED when recipient_type is set to input. The number should be in E.164 format.
recipient_id	No	Integer	The ID of the phonebook where the recipients' phone numbers are stored.Note: This parameter is REQUIRED when recipient_type is set to phonebook. You can query the ID using Search Specific Phonebooks. The number stored in the phonebook should be in E.164 format.
recipient_num_type	No	String	The type of phone number field from which to retrieve the recipient's number in the specified phonebook.Note:This parameter is REQUIRED when recipient_type is set to phonebook. Valid value: business_number business_number2 mobile_number mobile_number2 home_number home_number2 business_fax home_fax other_number
content_type	Yes	String	The type of the message content. Valid value: text: Text. document: File. template: WhatsApp message template.
content	No	String	Message content for SMS campaign. Note: This parameter is REQUIRED when content_type is set to text or document. For SMS campaign with plain text, directly pass the text (emojis are also supported) in this parameter. For SMS campaign with file, you need to first upload the desired file, then pass the returned file information in this parameter in JSON-formatted string. For more information, see the API examples below.
msg_param	No	String	Message parameters to be filled into the template, provided in JSON-formatted string. Note: This parameter is REQUIRED when content_type is set to template. To send a message template, you need to first get the desired WhatsApp message template, then construct the message object with the template information and the desired values for placeholders (variables) in the template. For the specific structure, see the description of MSG_Param below.
send_type	Yes	String	When the campaign message should be sent. Valid value: immediately: Messages are sent as soon as the campaign is saved. schedule: Messages are sent at a scheduled time. draft: The campaign is saved as a draft and no messages are sent.
send_time	No	Integer	The timestamp (in seconds) of the scheduled time when the campaign messages should be sent. Note: This parameter is REQUIRED when send_type is set to schedule.
send_mode	Yes	String	The sending mode of the campaign. Valid value: new_session: New sessions will be created and assigned to a specified destination when sending campaign messages. direct: Messages will be sent directly without creating new sessions.
assign_to_type	No	String	The type of the destination to which new campaign sessions will be assigned. Note: This parameter is REQUIRED when send_mode is set to new_session. Valid value: extension: Extension. queue: Message queue.
assign_to_id	No	Integer	The ID of the destination to which new campaign sessions will be assigned. Note: This parameter is REQUIRED when send_mode is set to new_session. You can query the ID using Search Specific Extensions or Get Menu Options (menu= message_queue).

Number_List

Parameter	Required	Type	Description
number	Yes	String	Recipient's phone number in E.164 format. For example, ++254703424344.

MSG_ParamNote:You can fill in the values with the information you get when querying a WhatsApp template.

Parameter	Required	Type	Description
id	Yes	Integer	The ID of the message template in the PBX system.
template_id	Yes	String	The original template ID from the WhatsApp platform.
name	Yes	String	Template name.
language	Yes	Object<Template_Lang>	Template language.
parameter_format	Yes	String	Whether placeholders are referenced by position or by variable name. Valid value: POSITIONAL: Placeholders are referenced by their position, such as {{1}}, {{2}}. NAMED: Placeholders are referenced by their variable names, such as {{name}}, {{code}}.
components	No	Array<Components>	The list of message components for WhatsApp message template in JSON-formatted string. Note: If the template contains only static text (no variables or buttons), this parameter can be left empty. You can use this parameter to provide values for template placeholders (variables) and required button parameters. For more information, see WhatsApp Message Template Component Description.

Template_Lang

Parameter	Required	Type	Description
code	Yes	String	The language code used for the template.

Response parameters

Parameter	Type	Description
errcode	Integer	Returned error code. 0: Succeed. Non-zero value: Failed. Note: You can check the error code and error message in Error Code and Error Message.
errmsg	String	Returned message. SUCCESS: Succeed. FAILURE: Failed.
id	Integer	The ID of the message campaign.

Examples

Create an SMS campaign with plain text.

Request example

POST /openapi/v1.0/message_campaign/create?access_token=YAuOvAdHfaqJ8Ni46FDdM9zgK7jYa6mE HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: application/json
{
  "name": "SummerSale202507",  
  "channel_type": "sms",  
  "omnichannel_id": 7,  
  "sender": 7,  
  "recipient_type": "input",  
  "number_list": [
    {
      "number": "+8613800001111"  
    },
    {
      "number": "+8613800002222"  
    },
    {
      "number": "+8613800003333"  
    }
  ],
   "content_type": "text",  
   "content": "Summer’s best deals are on now—up to 50% off! 🌞 Drop by and treat yourself to something special ✨.",  
   "send_type": "scheduled",  
   "send_time": 1753898766, 
   "send_mode": "new_session", 
   "assign_to_type": "extension", 
   "assign_to_id": 2  
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 249
}

Create an SMS campaign with file.

Upload the desired file.

Request example

POST /openapi/v1.0/message/batchupload?access_token=cIRvlHGgdMSuY0eiWE9JkXLCcHZHRTXm HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="files"; filename="/D:/projects/files/demo.jpeg"
Content-Type: image/jpeg

(binary data) # actual file content here
------WebKitFormBoundary7MA4YWxkTrZu0gW

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "list": [
        {
            "id": "65a7872eedb341068369fe67664e0fa1",
            "name": "demo.jpeg",
            "uri": "20250725/65a7872eedb341068369fe67664e0fa1",
            "type": "image/jpeg",
            "size": 88555
        }
    ]
}

Create a message campaign.

Request example

POST /openapi/v1.0/message_campaign/create?access_token=YAuOvAdHfaqJ8Ni46FDdM9zgK7jYa6mE HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: application/json
{
  "name": "API-SMS-CAHNNEL-File",  
  "channel_type": "sms",  
  "omnichannel_id": 7,  
  "sender": 7,  
  "recipient_type": "input",  
  "number_list": [
    {
      "number": "+8613800001111"  
    },
    {
      "number": "+8613800002222"  
    },
    {
      "number": "+8613800003333"  
    }
  ],
   "content_type": "document",  
   "content": "{\"id\":\"65a7872eedb341068369fe67664e0fa1\",\"name\":\"demo.jpeg\",\"uri\":\"20250725/65a7872eedb341068369fe67664e0fa1\",\"type\":\"image/jpeg\",\"size\":88555}", 
   
   "send_type": "draft",  
   "send_time": 1753898766, 
   "send_mode": "new_session", 
   "assign_to_type": "extension", 
   "assign_to_id": 2  
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 249
}

Create a WhatsApp campaign.

Get the information of the desired WhatsApp template.

Request example

GET /openapi/v1.0/message_channel/whatsapp_template?omnichannel_id=1&access_token=FOgrNFKY6xVQcUxw3pfMTFqCAG6lBulV&search_value=discount HTTP/1.1
Host: 192.168.5.150:8088

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "total_number": 1,
    "data": [
        {
            "id": 1773,
            "template_id": "1293546285747227",
            "name": "discount_campaign",
            "parameter_format": "NAMED",
            "language": "en",
            "category": "MARKETING",
            "sub_category": "CUSTOM",
            "components_data": "[{\"type\":\"HEADER\",\"format\":\"IMAGE\"},{\"type\":\"BODY\",\"text\":\"Hello! 👋\\n\\nAs a valued  {{customertier}} member, we’re excited to share a special {{offertype}} with you! 🎁\\nEnjoy {{offerdetails}}—available until {{expirydate}}.\\n\\nIf you have any questions or want to redeem your offer, simply reply to this message or contact our team.\\n\\nThank you for choosing {{companyname}}! 💙\"},{\"type\":\"BUTTONS\",\"buttons\":[{\"type\":\"FLOW\",\"text\":\"Redeem Offer\",\"flow_id\":657693363952373,\"flow_action\":\"NAVIGATE\",\"navigate_screen\":\"SIGN_UP\"},{\"type\":\"URL\",\"text\":\"Visit website\",\"url\":\"https://test.com/\"},{\"type\":\"VOICE_CALL\",\"text\":\"Contact us\"}]}]",
            "omnichannel_id": 1
        }
    ]
}

Construct the template message content according to WhatsApp Message Template Component Description, and convert it into a JSON-formatted string.

 {\"id\":1773,\"template_id\":\"1293546285747227\",\"name\":\"discount_campaign\",\"language\":{\"code\":\"en\"},\"parameter_format\":\"NAMED\",\"components\":[{\"type\":\"HEADER\",\"parameters\":[{\"type\":\"IMAGE\",\"file_list\":[{\"id\":\"d8b23d56d9974cdb90d6c2d6927861b9\",\"name\":\"demo.jpeg\",\"uri\":\"20250725/d8b23d56d9974cdb90d6c2d6927861b9\",\"type\":\"image/jpeg\",\"size\":88555}]}]},{\"type\":\"BODY\",\"parameters\":[{\"type\":\"TEXT\",\"text\":\"VIP\",\"parameter_name\":\"customertier\"},{\"type\":\"TEXT\",\"text\":\"discount\",\"parameter_name\":\"offertype\"},{\"type\":\"TEXT\",\"text\":\"20% off for all products\",\"parameter_name\":\"offerdetails\"},{\"type\":\"TEXT\",\"text\":\"July 31, 2025\",\"parameter_name\":\"expirydate\"},{\"type\":\"TEXT\",\"text\":\"SmartMal\",\"parameter_name\":\"companyname\"}]},{\"type\":\"BUTTONS\",\"parameters\":[{\"type\":\"FLOW\",\"text\":\"\"},{\"type\":\"URL\",\"text\":\"\"},{\"type\":\"VOICE_CALL\",\"text\":\"\"}]}]}

Create a message campaign using the template.

Request example

POST /openapi/v1.0/message_campaign/create?access_token=YAuOvAdHfaqJ8Ni46FDdM9zgK7jYa6mE HTTP/1.1
Host: 192.168.5.150:8088
Content-Type: application/json
{
  "name": "Exclusive Discount Alert",  
  "channel_type": "whatsapp",  
  "omnichannel_id": 1,  
  "sender": 1,  
  "recipient_type": "phonebook",  
  "recipient_id":28,   
  "recipient_num_type":"business_number", 
  "content_type": "template",  
  "msg_param":"{\"id\":1773,\"template_id\":\"1293546285747227\",\"name\":\"discount_campaign\",\"language\":{\"code\":\"en\"},\"parameter_format\":\"NAMED\",\"components\":[{\"type\":\"HEADER\",\"parameters\":[{\"type\":\"IMAGE\",\"file_list\":[{\"id\":\"d8b23d56d9974cdb90d6c2d6927861b9\",\"name\":\"demo.jpeg\",\"uri\":\"20250725/d8b23d56d9974cdb90d6c2d6927861b9\",\"type\":\"image/jpeg\",\"size\":88555}]}]},{\"type\":\"BODY\",\"parameters\":[{\"type\":\"TEXT\",\"text\":\"VIP\",\"parameter_name\":\"customertier\"},{\"type\":\"TEXT\",\"text\":\"discount\",\"parameter_name\":\"offertype\"},{\"type\":\"TEXT\",\"text\":\"20% off for all products\",\"parameter_name\":\"offerdetails\"},{\"type\":\"TEXT\",\"text\":\"July 31, 2025\",\"parameter_name\":\"expirydate\"},{\"type\":\"TEXT\",\"text\":\"SmartMal\",\"parameter_name\":\"companyname\"}]},{\"type\":\"BUTTONS\",\"parameters\":[{\"type\":\"FLOW\",\"text\":\"\"},{\"type\":\"URL\",\"text\":\"\"},{\"type\":\"VOICE_CALL\",\"text\":\"\"}]}]}", 
  "send_type": "draft",  
  "send_time": 1753898766, 
  "send_mode": "new_session", 
  "assign_to_type": "extension", 
  "assign_to_id": 2 
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 249
}

Follow us

Follow us

Add a Message Campaign

Request URL

Request parameters

Response parameters

Examples

Follow us

Business Needs

Ecosystem

Business Communication Suite

Ticketing System

Training

Frequently Asked Questions

Contact Us

Visit our Office

Add a Message Campaign

Request URL

Request parameters

Response parameters

Examples