向 app 所有用户发送广播消息

大约 6 分钟

向 app 所有用户发送广播消息

功能说明

可通过该接口向 app 下的所有用户发送广播消息，支持所有消息类型：

  • 广播消息向 app 下的所有用户发送。
  • 广播消息支持离线存储，若用户离线，服务器会存储离线消息（默认 7 天），若你集成了离线推送，则服务器会发送离线通知。
  • 广播消息写入服务端会话列表，支持消息漫游。
  • 广播消息支持计入消息未读数。
  • 广播消息没有消息 ID，只有广播 ID。
  • 广播消息不触发 发送前回调。

功能开通

发送广播消息功能默认关闭，使用前需联系环信商务开通。

开通功能后，你可以向 app 所有用户发送广播消息、向 app 在线用户发送广播消息，向 app 下的所有活跃聊天室发送广播消息。

调用频率上限

  1. 每 30 分钟限 1 次，不支持上调。超限上报 429 错误，即 "This request has reached api limit"。
  2. 每天限 3 次，支持联系商务上调。超限上报 403 错误，即 "broadcast message limit exceeded"。
  3. 每秒最多可向 1000 个用户发消息，不支持上调。

请求 URL

POST https://{host}/{org_name}/{app_name}/messages/broadcast

关于请求 URL 中的参数说明，详见 请求 URL 参数介绍。

请求示例

  • 发送文本广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "txt",
        "msg": "send broadcast to all users"
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'
  • 发送图片广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "img",
        "filename":"testimg.jpg",
        "secret":"VfXXXXNb_",
        "url":"https://XXXX/XXXX/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252",
        "size":{
           "width":480,
           "height":720
        }
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'
  • 发送语音广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "audio",
        "url": "https://XXXX/XXXX/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42",
        "filename": "testaudio.amr",
        "length": 10,
        "secret": "HfXXXXCjM"
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'
  • 发送视频广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "video",
        "filename": "1418105136313.mp4",
        "thumb" : "https://XXXX/XXXX/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",
        "length" : 0,
        "secret":"VfXXXXNb_",
        "file_length" : 58103,
        "thumb_secret" : "ZyXXXX2I",
        "url" : "https://XXXX/XXXX/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'
  • 发送文件广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "file",
        "filename":"test.txt",
        "secret":"1-g0XXXXua",
        "url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444"
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'
  • 发送位置广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "loc",
        "lat": "39.966",
        "lng":"116.322",
        "addr":"中国北京市海淀区中关村"
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'
  • 发送透传广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "cmd",
        "action":"action1"
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'
  • 发送自定义广播消息
# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -X POST 'https://XXXX/XXXX/XXXX/messages/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "target_type": "users",
    "msg": {
        "type": "custom",
        "customEvent": "custom_event",
    },
    "from": "admin",
    "appkey": "XXXX",
    "ext": {
        "extKey": "extValue"
    }
}'

请求 header 参数

关于 Content-Type 和 Authorization 字段的说明，详见 请求 header 参数说明。

请求 body 参数

以下为发送文本类型的广播消息的请求 body。

参数类型是否必需描述
target_typeString是广播消息接收方。固定值为 users，表示 app 下的所有用户。
fromString否广播消息发送方的用户 ID。若不传入该字段，服务器默认设置为管理员，即 admin；若传入字段但值为空字符串 ("")，请求失败。
msgJSON是消息体包含的信息。
msg.typeString是广播消息类型：
- txt：文本消息；
- img：图片消息；
- audio：语音消息；
- video：视频消息；
- file：文件消息；
- loc：位置消息；
- cmd：透传消息；
- custom：自定义消息。
msg.msgString是消息内容。
extJSON否广播消息支持扩展字段，可添加自定义信息。不能对该参数传入 null。

不同类型的消息的请求体只在 msg 字段有差别，其他参数相同。除了 type 字段，msg 字段中包含的参数与单聊、群聊和聊天室消息的请求体中的 body 字段含义相同，详见 发送单聊消息、发送群聊消息 或 发送聊天室消息中的消息 body 的参数说明。

响应示例

{
    "path": "/messages/broadcast",
    "uri": "https://XXXX/XXXX/XXXX/messages/broadcast",
    "timestamp": 1745565192019,
    "organization": "XXXX",
    "application": "5371aaa4-4a53-XXXX-XXXX-2bc6b3e401d7",
    "action": "post",
    "data": {
        "id": 1365344904091349007
    },
    "duration": 0,
    "applicationName": "XXXX"
}

响应 body 字段

对于各类型的广播消息来说，响应中包含的各字段相同。

如果返回的 HTTP 状态码为 200，表示请求成功，响应 body 包含如下字段：

参数类型描述
data.idJSON广播 ID。

响应体中的其他参数说明如下表所示：

字段类型描述
pathString请求路径，属于请求 URL 的一部分，开发者无需关注。
uriString请求 URL。
timestampLongUnix 时间戳，单位为毫秒。
organizationString环信即时通讯 IM 为每个公司（组织）分配的唯一标识，与请求参数 org_name 相同。
applicationString应用在系统内的唯一标识。该标识由系统生成，开发者无需关心。
actionString请求方法。
durationInt从发送请求到响应的时长，单位为毫秒。
applicationNameString你在环信控制台创建应用时填入的应用名称，与请求参数 app_name 相同。

如果返回的 HTTP 状态码非 200，表示请求失败。你可以参考 响应状态码了解可能的原因。

错误码

HTTP 状态码错误类型错误提示可能原因处理建议
400illegal_argumentext must be JSONObjectext 不为空时，必须是 JSON 结构。若设置 ext，只能传入 JSON 格式的数据。
400illegal_argumentfrom can't be emptyfrom 不能为空。from 为必填字段，必须设置。
400illegal_argumenttarget_type can only be 'users'target_type 的值只能为 users。target_type 的值只能为 users，不能传入其他值。
400illegal_argumenttarget_type must be providedtarget_type 不能为空。target_type 不能为空，只能传入 users。
403forbidden_opmessage broadcast service is unopened未开通发送广播消息的功能配置。联系商务开通。
429-This request has reached api limit每 30 分钟限调接口 1 次。该限制不支持上调，请降低发送频率。
403forbidden_opbroadcast message limit exceeded每天接口调用次数超限（默认 3 次）。联系商务上调 API 调用频率上限。

关于其他错误，你可以参考 响应状态码 了解可能的原因。

上次编辑于:
环信 IM 文档 Version: 1.0.0 ©️环信