添加群发活动

创建短信群发活动或 WhatsApp 群发活动。

请求 URL

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

请求参数

参数 是否必填 类型 说明
name 是 String 群发活动号码。
channel_type 是 String 群发活动所使用的消息渠道类型。
取值范围：
  • sms：SMS 渠道。
  • whatsapp：WhatsApp 渠道。
omnichannel_id 是 Integer 群发活动所使用的消息渠道的 ID。
注： 可使用 查询特定消息渠道 接口查询渠道 ID。
sender 是 Integer 与指定消息渠道关联的号码 ID。
注： 可使用 查询特定消息渠道 接口查询渠道 ID。
recipient_type 是 String 向群发活动添加收信人的方式。
取值范围：
  • input：手动添加收信人。
  • phonebook：从指定企业联系人群组中添加收信人。
number_list 否 Array <Number_List> 群发活动的收信人号码。
注：
  • 该参数在 recipient_type 设为 input 时必填。
  • 号码必须为 E.164 格式。
recipient_id 否 Integer 存储收信人电话号码的企业联系人群组 ID。
注：
  • 该参数在 recipient_type 设为 phonebook 时必填。
  • 可使用 搜索特定企业联系人群组 接口查询此 ID。
  • 企业联系人群组中存储的号码需为 E.164 格式。
recipient_num_type 否 String 指定在所选企业联系人群组中获取收信人号码的电话号码字段类型。
注： 该参数在 recipient_type 设为 phonebook 时必填。
取值范围：
  • business_number：办公号码
  • business_number2：办公号码 2
  • mobile_number：手机号码
  • mobile_number2：手机号码 2
  • home_number：家庭号码
  • home_number2：家庭号码 2
  • business_fax：公司传真
  • home_fax：家庭传真
  • other_number：其他
content_type 是 String 消息内容的类型。

取值范围：

  • text：文本消息。
  • document：文件消息。
  • template：WhatsApp 消息模板。
content 否 String SMS 群发活动的消息内容。
注： 该参数在 content_type 设为 text 或 document 时必填。
  • 对于纯文本的短信群发活动，可直接在此参数中传递文本内容 (支持表情符号)。
  • 对于带文件的短信群发活动，需要先 上传所需文件，然后将返回的文件信息以 JSON 字符串格式传递到此参数中。
更多信息，请参见下方 API 示例。
msg_param 否 String 需要填充到模板中的消息参数，以 JSON 字符串格式提供。
注： 该参数在 content_type 设为 template 时必填。
如需发送消息模板，需先 获取所需的 WhatsApp 消息模板，然后使用模板信息以及要替换模板占位符 (变量) 的具体值来构建消息对象。具体结构请参考下方的 MSG_Param 说明。
send_type 是 String 活动的消息发送时间。

取值范围：

  • immediately：活动保存后立即发送消息。
  • schedule：在指定时间发送消息。
  • draft：活动被保存为草稿，暂不发送消息。
send_time 否 Integer 活动指定发送时间的时间戳。
注： 该参数在 send_type 设为 schedule 时必填。
send_mode 是 String 活动发送模式。

取值范围：

  • new_session：发送活动消息时自动创建新会话，并分配给指定对象。
  • direct：直接发送消息，不创建新会话。
assign_to_type 否 String 新建群发活动会话将被分配到的目的地类型。
注： 该参数在 send_mode 设为 new_session 时必填。

取值范围：

  • extension：分机。
  • queue：消息队列。
assign_to_id 否 Integer 新建群发活动会话将被分配到的目的地的 ID。
注：
Number_List
参数 是否必填 类型 说明
number 是 String 收信人电话号码，以 E.164 格式传送。

例如，+12025550101。
MSG_Param
注： 可使用 查询 WhatsApp 模板 时获得的信息填写以下字段。
参数 是否必填 类型 说明
id 是 Integer PBX 中的消息模板 ID。
template_id 是 String 来自 WhatsApp 平台的原始模板 ID。
name 是 String 模板名称。
language 是 Object<Template_Lang> 模板语言。
parameter_format 是 String 模板中占位符的引用方式。

取值范围：

  • POSITIONAL：占位符按位置引用。例如，{{1}}、{{2}}。
  • NAMED：占位符按变量名引用。例如，{{name}}、{{code}}。
components 否 Array<Components> WhatsApp 消息模板的消息组件列表 (以 JSON 字符串格式传送)。
注： 如果模板仅包含静态文本 (无变量或按钮)，此参数可为空。

要传送模板消息时，你可以通过此参数为模板中的占位符 (变量) 和所需按钮参数赋值。更多信息，请参见 WhatsApp 消息模板组件说明。
Template_Lang
参数 是否必填 类型 说明
code 是 String 模板所使用语言的代码。

响应参数

参数 类型 说明
errcode Integer 返回错误码。
  • 0：请求成功。
  • 非零值：请求失败。
注： 更多错误码和错误信息说明，请参见 错误码 & 错误信息。
errmsg String 返回信息。
  • SUCCESS：请求成功。
  • FAILURE：请求失败。
id Integer 群发活动的 ID。

示例

  • 创建一个纯文本的短信群发活动。

    请求示例

    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  
}

    响应示例

    HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 249
}
  • 创建一个带文件的短信群发活动。
    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) # 实际文件内容的二进制数据

------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. 创建群发活动。

      请求示例

      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  
}

      响应示例

      HTTP/1.1 200 OK
{
    "errcode": 0,
    "errmsg": "SUCCESS",
    "id": 249
}
  • 创建 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",
            "[{\"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. 创建群发活动。

      请求示例

      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 
}

      响应示例

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