发送全局广播消息

大约 12 分钟

发送全局广播消息

即时通讯 IM 支持向 app 所有在线用户发送全局广播消息以及发送聊天室全局广播消息。该功能默认关闭，使用前需联系声网商务开通。

前提条件

要调用即时通讯 RESTful API，请确保满足以下要求：

已在声网控制台open in new window 开通配置即时通讯 IM 服务。
已从服务端获取 app token，详见使用 Token 鉴权。
了解即时通讯 IM API 的调用频率限制，详见接口频率限制。

公共参数

请求参数

参数	类型	是否必需	描述
`host`	String	是	即时通讯 IM 分配的用于访问 RESTful API 的域名。
`app_id`	String	是	声网为每个项目自动分配的 App ID，作为项目唯一标识。

响应参数

参数	类型	描述
`action`	String	请求方法。
`uri`	String	请求 URL。
`path`	String	请求路径，属于请求 URL 的一部分，开发者无需关注。
`entities`	JSON	响应实体。
`timestamp`	Long	HTTP 响应的 Unix 时间戳，单位为毫秒。
`duration`	Int	从发送 HTTP 请求到响应的时长，单位为毫秒。

认证方式

即时通讯 IM RESTful API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时，都必须在请求头部填入如下 Authorization 字段：

Authorization: Bearer YourAppToken

为提高项目的安全性，声网使用 Token（动态密钥）对即将登录即时通讯系统的用户进行鉴权。即时通讯 IM RESTful API 推荐使用 app token 的鉴权方式，详见使用 Token 鉴权。

向 app 在线用户发送广播消息

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

广播消息只向 app 下的在线用户发送。
广播消息不支持离线存储，即离线用户收不到这些消息。
广播消息写入服务端会话列表，默认不支持漫游功能。如果需要，请联系声网商务开通。

发送频率：每分钟限 1 次，每天限 50 次（可联系商务提升该上限）。

HTTP 请求

POST https://{host}/app-id/{app_id}/messages/users/broadcast

路径参数

参数及说明详见公共参数。

参数	类型	是否必需	描述
`Content-Type`	String	是	内容类型。请填 `application/json`。
`Authorization`	String	是	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。

请求 body

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

参数	类型	是否必需	描述
`from`	String	否	广播消息发送方的用户 ID。若不传入该字段，服务器默认设置为管理员，即 `admin`；若传入字段但值为空字符串 (“”)，请求失败。
`msg`	JSON	是	消息体包含的信息。
`msg.type`	String	是	广播消息类型： - `txt`：文本消息； - `img`：图片消息； - `audio`：语音消息； - `video`：视频消息； - `file`：文件消息； - `loc`：位置消息； - `cmd`：透传消息； - `custom`：自定义消息。
`msg.msg`	String	是	消息内容。
`ext`	JSON	否	广播消息支持扩展字段，可添加自定义信息。不能对该参数传入 `null`。

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

HTTP 响应

响应 body

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

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

参数	类型	描述
`data.id`	JSON	广播 ID。

其他参数及说明详见公共参数。

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

示例

请求示例

发送文本广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/users/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "txt",
        "msg": "send broadcast to all online users"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    }
}'

发送图片广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/users/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "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",
    "ext": {
        "extKey": "extValue"
    }
}'

发送语音广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/users/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "audio",
        "url": "https://XXXX/XXXX/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42",
        "filename": "testaudio.amr",
        "length": 10,
        "secret": "HfXXXXCjM"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    }
}'

发送视频广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/users/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "video",
        "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",
    "ext": {
        "extKey": "extValue"
    }
}'

发送文件广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/users/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "file",
        "filename":"test.txt",
        "secret":"1-g0XXXXua",
        "url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    }
}'

发送位置广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/users/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "loc",
        "lat": "39.966",
        "lng":"116.322",
        "addr":"中国北京市海淀区中关村"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    }
}'

发送透传广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/users/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "cmd",
        "action":"action1"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    }
}'

发送自定义广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

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

响应示例

{
  "path": "/messages/users/broadcast",
  "uri": "https://XXXX/XXXX/XXXX/messages/users/broadcast",
  "timestamp": 1699944653964,
  "organization": "XXXX",
  "application": "331d42e6-ad85-XXXX-XXXX-d1fb6fef9f12",
  "action": "post",
  "data": {
    "id": 1173998498812376874
   },
  "duration": 1,
  "applicationName": "XXXX"
}

错误码

对于应用全局广播消息，如果返回的 HTTP 状态码非 200，表示请求失败。除了发送普通消息的常见错误码，还可能提示以下错误码：

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	invalid_request_body	Request body is invalid. Please check body is correct.	请求体格式不正确。	检查请求体内容是否合法(字段类型是否正确)。
400	illegal_argument	from can't be empty	请求参数 `from` 是空字符串。	输入正确的请求参数 `from` 。若不传该字段，服务器会默认设置为 `admin`。
400	illegal_argument	ext must be JSONObject	请求参数 `ext` 类型不正确。	输入正确的请求参数 `ext`（JSON 格式）。
403	forbidden_op	message broadcast service is unopened	未开通发送广播消息的功能配置。	联系商务开通。

此外，你可以参考发送单聊消息、发送群聊消息和发送聊天室消息的错误码了解可能的原因。

发送聊天室全局广播消息

可通过该接口向 app 下的所有活跃聊天室（聊天室至少存在一个成员，而且曾经至少发送过一条消息）发送广播消息，支持所有消息类型。该功能默认关闭，如果需要，请联系声网商务开通。

发送频率：每分钟最多可发 10 次，而且每天最多可发 100 次广播消息。

HTTP 请求

POST https://{host}/app-id/{app_id}/messages/chatrooms/broadcast

路径参数

参数及说明详见公共参数。

请求 header

参数	类型	是否必需	描述
`Content-Type`	String	是	内容类型。请填 `application/json`。
`Authorization`	String	是	App 管理员的鉴权 token，格式为 `Bearer YourAppToken`，其中 `Bearer` 为固定字符，后面为英文空格和获取到的 app token。

请求 body

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

参数	类型	是否必需	描述
`from`	String	否	广播消息发送方的用户 ID。若不传入该字段，服务器默认设置为管理员，即 “admin”；若传入字段但值为空字符串 (“”)，请求失败。
`chatroom_msg_level`	String	否	聊天室消息优先级： - `high`：高； - （默认）`normal`：普通； - `low`：低。
`msg`	JSON	是	消息体包含的信息。
`msg.type`	String	是	广播消息类型： - `txt`：文本消息； - `img`：图片消息； - `audio`：语音消息； - `video`：视频消息； - `file`：文件消息； - `loc`：位置消息； - `cmd`：透传消息； - `custom`：自定义消息。
`msg.msg`	String	是	消息内容。
`ext`	JSON	否	广播消息支持扩展字段，可添加自定义信息。不能对该参数传入 `null`。同时，推送通知也支持自定义扩展字段，详见 APNs 自定义显示和 Android 推送字段说明。

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

发送图片消息
发送语音消息
发送视频消息
发送文件消息
发送位置消息
发送透传消息
发送自定义消息

HTTP 响应

响应 body

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

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

参数	类型	描述
`data.id`	JSON	广播 ID。

其他参数及说明详见公共参数。

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

示例

请求示例

发送文本广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "txt",
        "msg": "send broadcast to all chatroom"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

发送图片广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "img",
        "filename":"testimg.jpg",
        "secret":"VfXXXXNb_",
        "url":"https://XXXX/app-id/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252",
        "size":{
           "width":480,
           "height":720
        }
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

发送语音广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "audio",
        "url": "https://XXXX/app-id/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42",
        "filename": "testaudio.amr",
        "length": 10,
        "secret": "HfXXXXCjM"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

发送视频广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "video",
        "thumb" : "https://XXXX/app-id/XXXX/chatfiles/67279b20-7f69-11e4-8eee-21d3334b3a97",
        "length" : 0,
        "secret":"VfXXXXNb_",
        "file_length" : 58103,
        "thumb_secret" : "ZyXXXX2I",
        "url" : "https://XXXX/app-id/XXXX/chatfiles/671dfe30-XXXX-XXXX-ba67-8fef0d502f46"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

发送文件广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "file",
        "filename":"test.txt",
        "secret":"1-g0XXXXua",
        "url":"https://XXXX/app-id/XXXX/chatfiles/d7eXXXX7444"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

发送位置广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "loc",
        "lat": "39.966",
        "lng":"116.322",
        "addr":"中国北京市海淀区中关村"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

发送透传广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "cmd",
        "action":"action1"
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

发送自定义广播消息

# 将 <YourAppToken> 替换为你在服务端生成的 App Token

curl -L 'https://XXXX/app-id/XXXX/messages/chatrooms/broadcast' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "msg": {
        "type": "custom",
        "customEvent": "custom_event",
    },
    "from": "admin",
    "ext": {
        "extKey": "extValue"
    },
    "chatroom_msg_level": "low"
}'

响应示例

{
  "path": "/messages/chatrooms/broadcast",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatrooms/broadcast",
  "timestamp": 1699944653964,
  "action": "post",
  "data": {
    "id": 1173998498812376874
   },
  "duration": 1
}

错误码

HTTP 状态码	错误类型	错误提示	可能原因	处理建议
400	invalid_request_body	Request body is invalid. Please check body is correct.	请求体格式不正确。	检查请求体内容是否合法(字段类型是否正确)。
400	illegal_argument	from can't be empty	请求参数 `from` 是空字符串。	输入正确的请求参数 `from` 。若不传该字段，服务器会默认设置为 `admin`。
400	illegal_argument	ext must be JSONObject	请求参数 `ext` 类型不正确。	输入正确的请求参数 `ext`（JSON 格式）。
403	forbidden_op	message broadcast service is unopened	未开通发送聊天室广播消息的功能配置。	联系商务开通。

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

发送全局广播消息

# 发送全局广播消息

# 前提条件

# 公共参数

# 请求参数

# 响应参数

# 认证方式

# 向 app 在线用户发送广播消息

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

# 发送聊天室全局广播消息

# HTTP 请求

# 路径参数

# 请求 header

# 请求 body

# HTTP 响应

# 响应 body

# 示例

# 请求示例

# 响应示例

# 错误码

发送全局广播消息

前提条件

公共参数

请求参数

响应参数

认证方式

向 app 在线用户发送广播消息

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码

发送聊天室全局广播消息

HTTP 请求

路径参数

请求 header

请求 body

HTTP 响应

响应 body

示例

请求示例

响应示例

错误码