Send a Message in a Message Session

Send a message in a specific message session, or initiate a message session.

Request URL

POST {base_url}/{api_path}/message/send?access_token={access_token}

Request parameters


Parameter	Required	Type	Description
sender_type	Yes	Integer	The type of the sender. Valid value: `1`: Extension user. `9`: Third-party message analytics platform (transmitted via API)
sender_no	No	String	The identifier of the sender. Valid value: If `sender_type` is set to `1`, this parameter is REQUIRED, which can be used to specify the extension number. If `sender_type` is set to `9`, enter `api` or leave it blank.
session_id	No	Integer	The unique ID of the message session, specifying which session the message will be sent through. Note: You can query the message session ID using Search Specific Message Sessions. When initiating a message session, omit this parameter. However, if there is an existing session where the values of `channel`, `did_number`, and `to` all match those specified in the request, the message will be sent within that session instead of creating a new one.
channel	No	String	The type of the message channel via which the message will be sent. Note: This parameter is REQUIRED when initiating a message session (The parameter `session_id` is omitted). Valid value: `general` `apidaze` `athena` `bandwidth` `flowroute` `ixica` `siptrunk` `skyetel` `telnyx` `twilio` `vetta` `voicemeup` `whatsapp` `facebook` `livechat`
did_number	No	String	The DID number associated with the message channel. Note: This parameter is REQUIRED when initiating a message session (The parameter `session_id` is omitted). You can query the corresponding DID number using Search Specific Message Channels.
to	No	String	The external number to which the message will be sent. Note: This parameter is REQUIRED when initiating a message session (The parameter `session_id` is omitted). The value may start with a `+`, and can include digits, the characters `(`, `)`, `.`, `-`, `*`, `#`, and spaces.
msg_kind	No	Integer	The category of the message to be sent. Valid value: `0`: Normal message. `1`: WhatsApp template message.
msg_type	No	Integer	The type of the message content. Value value: `0`: User message.
msg_body	No	String	The text content of the message. Note: For normal message (`msg_kind` is set to `0`), either `msg_body` or `files` must be provided.
files	No	Array<File_Info>	The detailed information of the file to be sent. Note: For normal message (`msg_kind` is set to `0`), either `msg_body` or `files` must be provided. You can upload the desired file using Upload Files for Messaging, the pass the returned file information in this parameter. Only one file is supported per message.
whatsapp_msg_param	No	String	Message parameters to be filled into a WhatsApp message template, provided in JSON-formatted string. Note: This parameter is REQUIRED when `msg_kind` is set to `1`. To send a template message, 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 more information, see WhatsApp Message Template Component Description.
tag	No	String	Facebook message tag. Note: This parameter is REQUIRED when sending messages in a Facebook message session outside the 24-hour messaging window, otherwise the message sending will fail. Valid value: `ACCOUNT_UPDATE`: Tags the message you are sending as a non-recurring update to customer's application or account. `CONFIRMED_EVENT_UPDATE`: Tags the message you are sending as a reminder of an upcoming event or an update for an event in progress for which the customer is registered. `HUMAN_AGENT`: Provide human agent support in cases where a customer's issue cannot be resolved in the standard messaging window. `POST_PURCHASE_UPDATE`: Tags the message you are sending as an update for a recent purchase made by the customer.
request_id	No	String	The ID of the request, which can be used to identify and track the sent message. Note: The length must not exceed 127 characters.

File_Info


Parameter	Required	Type	Description
id	No	String	The ID of the file.
name	No	String	The name of the file.
uri	Yes	String	The URI for accessing the file.
type	No	String	File type.
size	No	Integer	File size (Unit: Byte).

Response parameters

Tip: You can get notified about the specific message delivery status by monitoring the API event (30032) Message Sending Result.


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.
msg_id	Integer	The unique ID of the message.
session_id	Integer	The unique ID of the message session.

Examples

Send an image file via an existing message session of extension user 1003.

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
        }
    ]
}

Send the file within a specific message session (ID: 3077).

Request example

POST /openapi/v1.0/message/send?access_token=QTkYRnZyCPVJb6rS8Ttw4mqRQUbslN67 HTTP/1.1

Host: yeastardocs.example.yeastarcloud.com
Content-Type: application/json
{
  "sender_type": 1,
  "sender_no": "1003", 
  "session_id": 3077,  
  "msg_kind": 0,  
  "msg_type": 0,  
  "files": [
        {
            "id": "65a7872eedb341068369fe67664e0fa1",
            "name": "demo.jpeg",
            "uri": "20250725/65a7872eedb341068369fe67664e0fa1",
            "type": "image/jpeg",
            "size": 88555
        }
    ],
  "request_id": "imgmsg-1003-20240918170355"
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "msg_id": 10273,
    "session_id": 3077
}

Send a message via an existing Facebook session (ID: 3069) outside the 24-hour messaging window.

Request example

POST /openapi/v1.0/message/send?access_token=f1G3MaqlX4pjCtiQwv9bGZyJd5OCt4JL HTTP/1.1
Host: 192.168.33.98:8088
Content-Length: 264

{
  "sender_type": 1, 
  "sender_no": "1003", 
  "session_id": 3069,
  "msg_kind": 0,  
  "msg_type": 0,   
  "msg_body": "Your account details have been updated.",  
  "tag": "ACCOUNT_UPDATE"
}

Response example

HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "msg_id": 10252,
    "session_id": 3069
}

Initiate a WhatsApp session and send a WhatsApp template message.

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
        }
    ]
}

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 session via a WhatsApp channel.

Request example

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

Host: yeastardocs.example.yeastarcloud.com
Content-Type: application/json
{
  "sender_type": 1, 
  "sender_no": "1003", 
  "channel":"whatsapp",
  "did_number": "+15550193510", 
  "to": "+14155552671",
  "msg_kind": 1,  
  "msg_type": 0,  
  "whatsapp_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\":\"\"}]}]}"
}

Response example

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