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:
Number_List
Parameter Required Type Description
number Yes String Recipient's phone number in E.164 format.

For example, +12025550101.
MSG_Param
Note: 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: yeastardocs.example.yeastarcloud.com
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.
    1. Upload the desired file.

      Request example

      POST /openapi/v1.0/message/batchupload?access_token=cIRvlHGgdMSuY0eiWE9JkXLCcHZHRTXm HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com
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
        }
    ]
}
    2. Create a message campaign.

      Request example

      POST /openapi/v1.0/message_campaign/create?access_token=YAuOvAdHfaqJ8Ni46FDdM9zgK7jYa6mE HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com
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.
    1. 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: yeastardocs.example.yeastarcloud.com

      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
        }
    ]
}
    2. 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\":\"\"}]}]}
    3. Create a message campaign using the template.

      Request example

      POST /openapi/v1.0/message_campaign/create?access_token=YAuOvAdHfaqJ8Ni46FDdM9zgK7jYa6mE HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com
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
}