在消息会话中发送消息

在指定消息会话中发送消息，或发起新的消息会话。

请求 URL

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

请求参数

参数 是否必填 类型 说明
sender_type 是 Integer 发送者的类型。
取值范围：
  • 1：分机用户。
  • 9：第三方分析平台 (消息通过二次开发接口传递)
sender_no 否 String 发送者的标识。
取值范围：
  • 此参数在 sender_type 设为 1 时必填，用于指定分机号码。
  • 若 sender_type 设为 9，可设置此参数为 api 或留空。
session_id 否 Integer 消息会话的唯一 ID，用于指定消息将通过哪个会话发送。
注：
  • 可使用 搜索特定消息会话 接口查询消息会话 ID。
  • 若要创建消息会话，则不传此参数。但如果有已存在会话的 channel、did_number 和 to 的值与请求中设定的值均一致，则消息会直接在该会话中发送，而不会创建会话。
channel 否 String 消息发送所使用的消息渠道类型。
注： 此参数在创建消息会话 (即不传 session_id 参数) 时必填。
取值范围：
  • general
  • apidaze
  • athena
  • bandwidth
  • flowroute
  • ixica
  • siptrunk
  • skyetel
  • telnyx
  • twilio
  • vetta
  • voicemeup
  • whatsapp
  • facebook
  • livechat
did_number 否 String 与消息渠道绑定的 DID 号码。
注：
  • 此参数在创建消息会话 (即不传 session_id 参数) 时必填。
  • 可使用 查询特定消息渠道 接口查询对应的 DID 号码。
to 否 String 消息发送的目标外部号码。
注：
  • 此参数在创建消息会话 (即不传 session_id 参数) 时必填。
  • 支持 + 开头，且可包含数字、符号 (、)、.、-、*、# 以及空格。
msg_kind 否 Integer 要发送的消息的类别。
取值范围：
  • 0：普通消息。
  • 1：WhatsApp 模板消息。
msg_type 否 Integer 消息内容的类型。
取值范围：
  • 0：用户信息。
msg_body 否 String 消息的文本内容。
注： 对于普通消息 (即 msg_kind 设为 0)，msg_body 和 files 两个参数必传一个。
files 否 Array<File_Info> 要发送的文件的详细信息。
注：
  • 对于普通消息 (即 msg_kind 设为 0)，msg_body 和 files 两个参数必传一个。
  • 你可以使用 上传消息文件 接口上传文件，然后将返回的文件信息填入此参数传递。
  • 一次仅支持发送一个文件。
whatsapp_msg_param 否 String 需要填充到 WhatsApp 模板中的消息参数，以 JSON 字符串格式提供。
注： 该参数在 msg_kind 设为 1 时必填。
如需发送消息模板，需先 获取所需的 WhatsApp 消息模板，然后使用模板信息以及要替换模板占位符 (变量) 的具体值来构建消息对象。更多信息，请参见 WhatsApp 消息模板组件说明。
tag 否 String Facebook 消息标签。
注： 如果要在超出了 24 小时标准消息窗口的 Facebook 会话中发送消息，此参数必填，否则消息发送会失败。
取值范围：
  • ACCOUNT_UPDATE：将消息标记为针对其应用或账户的不定期更新。
  • CONFIRMED_EVENT_UPDATE：将消息标记为近期事件的提醒，或客户已注册的进行中的事件的更新。
  • HUMAN_AGENT：在无法在标准消息窗口内解决客户问题的情况下，提供人工客服支持。
  • POST_PURCHASE_UPDATE：将消息标记为针对客户最近购买行为的更新。
request_id 否 String 请求的 ID，可用于识别和追踪已发送的消息。
注： 长度不可超过 127 个字符。
File_Info
参数 是否必填 类型 说明
id 否 String 文件 ID。
name 否 String 文件名称，
uri 是 String 可用于访问文件的 URI。
type 否 String 文件类型。
size 否 Integer 文件大小 (单位：字节)。

响应参数

注： 可通过监控 API 事件 (30032) 消息发送结果 获取关于具体消息传递状态的事件通知。
参数 类型 说明
errcode Integer 返回错误码。
  • 0：请求成功。
  • 非零值：请求失败。
注： 更多错误码和错误信息说明，请参见 错误码 & 错误信息。
errmsg String 返回信息。
  • SUCCESS：请求成功。
  • FAILURE：请求失败。
msg_id Integer 消息的唯一 ID。
session_id Integer 消息会话的唯一 ID。

示例

  • 通过分机 1003 的现有消息会话发送图像文件。
    1. 上传消息文件。

      请求示例

      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

      响应示例

      HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "list": [
        {
            "id": "65a7872eedb341068369fe67664e0fa1",
            "name": "demo.jpeg",
            "uri": "20250725/65a7872eedb341068369fe67664e0fa1",
            "type": "image/jpeg",
            "size": 88555
        }
    ]
}
    2. 在指定消息会话 (ID：3077) 中发送文件。

      请求示例

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

      响应示例

      HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "msg_id": 10273,
    "session_id": 3077
}
  • 在超出了 24 小时标准消息窗口的 Facebook 会话 (ID：3069) 中发送消息。

    请求示例

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

    响应示例

    HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "msg_id": 10252,
    "session_id": 3069
}
  • 创建一个 WhatsApp 会话并发送 WhatsApp 模板消息。
    1. 获取 WhatsApp 消息模板。

      请求示例

      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

      响应示例

      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. 根据 WhatsApp 消息模板组件说明 拼接模板消息内容，并转义为 JSON 字符串。
       {\"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. 通过 WhatsApp 消息渠道创建消息会话。

      请求示例

      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\":\"\"}]}]}"
}

      响应示例

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