发送群聊消息

大约 23 分钟

发送群聊消息

本文展示如何调用环信 IM RESTful API 在服务端实现群聊场景中全类型消息的发送与接收,包括文本消息、图片消息、语音消息、视频消息、透传消息和自定义消息。

群组聊天场景下,发送各类型的消息调用需调用同一 RESTful API,不同类型的消息只是请求体中的 body 字段内容存在差异,发送方式与单聊类似,详见发送单聊消息

提示

  1. 接口调用过程中,请求体和扩展字段的总长度不能超过 5 KB。
  2. 群组中发送的消息均同步给发送方。

发送频率:对于单个应用来说,调用该 API 每次最多向 3 个群组发送消息,而且该 API 存在以下两个限制:

  • 每秒最多可发送 20 条消息:例如,你每次向 3 个群组发送消息,即发送了 3 条消息,你每秒最多可调用 7 次。第 8 次调用时,则报 403 错误。
  • 每秒最大可调用 20 次:例如,你每次调用该 API 向单个群组发送消息,可调用 20 次。第 21 次调用时会报 429 错误。

前提条件

要调用环信即时通讯 REST API,请确保满足以下要求:

公共参数

请求参数

参数类型是否必需描述
hostString环信即时通讯 IM 分配的用于访问 RESTful API 的域名。详见 获取环信即时通讯 IM 的信息
org_nameString环信即时通讯 IM 为每个公司(组织)分配的唯一标识。详见 获取环信即时通讯 IM 的信息
app_nameString你在环信即时通讯云控制台创建应用时填入的应用名称。详见 获取环信即时通讯 IM 的信息

响应参数

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

认证方式

环信即时通讯 REST API 要求 Bearer HTTP 认证。每次发送 HTTP 请求时,都必须在请求头部填入如下 Authorization 字段:

Authorization: Bearer YourAppToken

为提高项目的安全性,环信使用 Token(动态密钥)对即将登录即时通讯系统的用户进行鉴权。本文涉及的所有消息管理 REST API 都需要使用 App Token 的鉴权方式,详见 使用 App Token 鉴权

发送文本消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

参数类型是否必需描述
Content-TypeString内容类型。填入 application/json
AcceptString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

下表为发送各类消息的通用请求体,为 JSON 对象,是所有消息的外层结构。与单聊消息类似,不同类型的消息的请求体只是 body 字段内容存在差异。

提示

  1. 群聊消息的通用请求体中的参数与发送单聊消息类似,唯一区别在于群聊中的 to 字段表示消息接收方群组 ID 数组。
参数类型是否必需描述
fromString消息发送方的用户 ID。若不传入该字段,服务器默认设置为 admin

提示

1. 服务器不校验传入的用户 ID 是否存在,因此,如果你传入的用户 ID 不存在,服务器并不会提示,仍照常发送消息。
2. 若传入字段但值为空字符串 (“”),请求失败。

toArray消息接收方群组 ID 数组。每次最多可向 3 个群组发送消息。

提示

服务器不校验传入的群组 ID 是否存在,因此,如果你传入的群组 ID 不存在,服务器并不会提示,仍照常发送消息。

typeString消息类型:
- txt:文本消息;
- img:图片消息;
- audio:语音消息;
- video:视频消息;
- file:文件消息;
- loc:位置消息;
- cmd:透传消息;
- custom:自定义消息。
bodyJSON消息内容。body 包含的字段见下表说明。
routetypeString若传入该参数,其值为 ROUTE_ONLINE,表示接收方只有在线时才能收到消息,若接收方离线则无法收到消息。若不传入该参数,无论接收方在线还是离线都能收到消息。
extJSON消息支持扩展字段,可添加自定义信息。不能对该参数传入 null。同时,推送通知也支持自定义扩展字段,详见 APNs 自定义显示Android 推送字段说明
ext.em_ignore_notificationBool是否发送静默消息:
- true:是;
- (默认)false:否。
发送静默消息指用户离线时,环信即时通讯 IM 服务不会通过第三方厂商的消息推送服务向该用户的设备推送消息通知。因此,用户不会收到消息推送通知。当用户再次上线时,会收到离线期间的所有消息。发送静默消息和免打扰模式下均为不推送消息,区别在于发送静默消息为发送方设置不推送消息,而免打扰模式为接收方设置在指定时间段内不接收推送通知。

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
msgString消息内容。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

发送给群组内所有成员,不论这些成员是否在线:

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

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "txt",
    "body": {
        "msg": "testmessages"
    },
    "ext": {
       "em_ignore_notification": true
    }
}'

仅发送给在线用户,即 routetype 设置为 ROUTE_ONLINE

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

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' 
-H 'Content-Type: application/json' 
-H 'Accept: application/json' 
-H 'Authorization: Bearer <YourAppToken>' 
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "txt",
    "body": {
        "msg": "testmessages"
    },
    "ext": {
       "em_ignore_notification": true
    },
    "routetype":"ROUTE_ONLINE"
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送图片消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

关于通用请求体,详见发送文本消息

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
filenameString图片名称。建议传入该参数,否则客户端收到图片消息时无法显示图片名称。
secretString图片的访问密钥,即成功上传图片后,从 文件上传 的响应 body 中获取的 share-secret。如果图片文件上传时设置了文件访问限制(restrict-access),则该字段为必填。
sizeJSON图片尺寸,单位为像素,包含以下字段:
- height:图片高度;
- width:图片宽度。
urlString图片 URL 地址:https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}。其中 file_uuid 为文件 ID,成功上传图片文件后,从 文件上传 的响应 body 中获取。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

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

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "img",
    "body": {
        "filename":"testimg.jpg",
        "secret":"VfXXXXNb_",
        "url":"https://XXXX/XXXX/XXXX/chatfiles/55f12940-XXXX-XXXX-8a5b-ff2336f03252",
        "size":{
            "width":480,
            "height":720
        }
    }
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送语音消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

关于通用请求体,详见发送文本消息

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
filenameString语音文件的名称。建议传入该参数,否则客户端收到语音消息时无法显示语音文件名称。
secretString语音文件访问密钥,即成功上传语音文件后,从 文件上传 的响应 body 中获取的 share-secret。 如果语音文件上传时设置了文件访问限制(restrict-access),则该字段为必填。
LengthInt语音时长,单位为秒。
urlString语音文件 URL 地址:https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}file_uuid 为文件 ID,成功上传语音文件后,从 文件上传 的响应 body 中获取。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

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

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' \
-H 'Content-Type: application/json' -H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "audio",
    "body": {
        "url": "https://XXXX/XXXX/XXXX/chatfiles/1dfc7f50-XXXX-XXXX-8a07-7d75b8fb3d42",
        "filename": "testaudio.amr",
        "length": 10,
        "secret": "HfXXXXCjM"
    }
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送视频消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

关于通用请求体,详见发送文本消息

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
filenameString视频文件名称。建议传入该参数,否则客户端收到视频消息时无法显示视频文件名称。
thumbString视频缩略图 URL 地址:https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}file_uuid 为视频缩略图唯一标识,成功上传缩略图文件后,从 文件上传 的响应 body 中获取。
lengthInt视频时长,单位为秒。
secretString视频文件访问密钥,即成功上传视频文件后,从 文件上传 的响应 body 中获取的 share-secret。如果视频文件上传时设置了文件访问限制(restrict-access),则该字段为必填。
file_lengthLong视频文件大小,单位为字节。
thumb_secretString视频缩略图访问密钥,即成功上传视频文件后,从 文件上传 的响应 body 中获取的 share-secret。如果缩略图文件上传时设置了文件访问限制(restrict-access),则该字段为必填。
urlString视频文件 URL 地址:https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}。其中 file_uuid 为文件 ID,成功上传视频文件后,从 文件上传 的响应 body 中获取。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

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

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d  '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "video",
    "body": {
        "filename" : "test.avi"
        "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"
    }
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送文件消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

关于通用请求体,详见发送文本消息

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
filenameString文件名称。 建议传入该参数,否则客户端收到文件消息时无法显示文件名称。
secretString文件访问密钥,即成功上传文件后,从 文件上传 的响应 body 中获取的 share-secret。如果文件上传时设置了文件访问限制(restrict-access),则该字段为必填。
urlString文件 URL 地址:https://{host}/{org_name}/{app_name}/chatfiles/{file_uuid}。其中 file_uuid 为文件 ID,成功上传视频文件后,从 文件上传 的响应 body 中获取。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

# 将 <YourAppToken> 替换为你在服务端生成的 App Token
curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "file",
    "body": {
        "filename":"test.txt",
        "secret":"1-g0XXXXua",
        "url":"https://XXXX/XXXX/XXXX/chatfiles/d7eXXXX7444"
    }
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送位置消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

关于通用请求体,详见发送文本消息

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
latString位置的纬度,单位为度。
lngString位置的经度,单位为度。
addrString位置的文字描述。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

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

curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatgroups"  \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "loc",
    "body":{
        "lat": "39.966",
        "lng":"116.322",
        "addr":"中国北京市海淀区中关村"
    }
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送透传消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

关于通用请求体,详见发送文本消息

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
actionString命令内容。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

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

curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatgroups" \
 -H 'Content-Type: application/json' \
 -H 'Accept: application/json' \ 
 -H "Authorization:Bearer <YourAppToken>" \
 -d '{
  "from": "user1",
  "to": ["184524748161025"],
  "type": "cmd",
  "body":{
    "action":"action1"
  }
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送自定义消息

HTTP 请求

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

路径参数

参数及说明详见 公共参数

请求 header

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

请求 body

关于通用请求体,详见发送文本消息

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
customEventString用户自定义的事件类型。该参数的值必须满足正则表达式 [a-zA-Z0-9-_/\.]{1,32},长度为 1-32 个字符。
customExtsJSON用户自定义的事件属性,类型必须是 Map<String,String>,最多可以包含 16 个元素。customExts 是可选的,不需要可以不传。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

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

curl -X POST -i "https://XXXX/XXXX/XXXX/messages/chatgroups" \
-H 'Content-Type: application/json' \
-H 'Accept: application/json'  \
-H "Authorization:Bearer <YourAppToken>" \
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "custom",
    "body": {
        "customEvent": "custom_event"
        "customExts":{
          "ext_key1":"ext_value1"
      }
    }
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}

发送定向消息

你可以向群组中指定的一个或多个成员发送消息,但单次仅支持指定一个群组。对于定向消息,只有作为接收方的指定成员才能看到消息,其他群成员则看不到该消息。

提示

  1. 定向消息不写入会话列表,不计入群组会话的未读消息数。
  2. 定向消息不支持消息漫游功能,因此从服务器拉取漫游消息时,不包含定向消息。
  3. 群组中发送的定向消息均同步给发送方。

发送频率:100 次/秒/App Key

以下以文本消息为例介绍如何在群组中发送定向消息。

HTTP 请求

POST https://{host}/{org_name}/{app_name}/messages/chatgroups/users

路径参数

参数及说明详见 公共参数

请求 header

参数类型是否必需描述
Content-TypeString内容类型。填入 application/json
AcceptString内容类型。填入 application/json
AuthorizationStringApp 管理员的鉴权 token,格式为 Bearer YourAppToken,其中 Bearer 为固定字符,后面为英文空格和获取到的 app token。

请求 body

下表为发送各类消息的通用请求体,为 JSON 对象,是所有消息的外层结构。

参数类型是否必需描述
fromString消息发送方的用户 ID。若不传入该字段,服务器默认设置为管理员,即 “admin”;若传入字段但值为空字符串 (“”),请求失败。
toArray消息接收方所属的群组 ID。每次只能传 1 个群组。
typeString消息类型:
- txt:文本消息;
- img:图片消息;
- audio:语音消息;
- video:视频消息;
- file:文件消息;
- loc:位置消息;
- cmd:透传消息;
- custom:自定义消息。
bodyJSON消息内容。body 包含的字段见下表说明。
extJSON消息支持扩展字段,可添加自定义信息。不能对该参数传入 null。同时,推送通知也支持自定义扩展字段,详见 APNs 自定义显示Android 推送字段说明
ext.em_ignore_notificationBool是否发送静默消息:
- true:是;
- (默认)false:否。
发送静默消息指用户离线时,环信即时通讯 IM 服务不会通过第三方厂商的消息推送服务向该用户的设备推送消息通知。因此,用户不会收到消息推送通知。当用户再次上线时,会收到离线期间的所有消息。发送静默消息和免打扰模式下均为不推送消息,区别在于发送静默消息为发送方设置不推送消息,而免打扰模式为接收方设置在指定时间段内不接收推送通知。
usersArray接收消息的群成员的用户 ID 数组。每次最多可传 20 个用户 ID。

请求体中的 body 字段说明详见下表。

参数类型是否必需描述
msgString消息内容。

对于其他类型的消息,body 字段的说明详见发送各类型的普通群聊消息的请求体中的 body 字段说明。

HTTP 响应

响应 body

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

参数类型描述
dataJSON返回数据详情。该字段的值为包含群组 ID 和 发送的消息的 ID 的键值对。
例如 "184524748161025": "1029544257947437432",表示在 ID 为 184524748161025 的群组中发送了消息 ID 为 1029544257947437432 的消息。

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

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

示例

请求示例

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

curl -X POST -i 'https://XXXX/XXXX/XXXX/messages/chatgroups/users' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <YourAppToken>' \
-d '{
    "from": "user1",
    "to": ["184524748161025"],
    "type": "txt",
    "body": {
        "msg": "testmessages"
    },
    "ext": {
       "em_ignore_notification": true
    },
    "users": ["user2", "user3"]
}'

响应示例

{
  "path": "/messages/chatgroups",
  "uri": "https://XXXX/XXXX/XXXX/messages/chatgroups",
  "timestamp": 1657254052191,
  "organization": "XXXX",
  "application": "e82bcc5f-XXXX-XXXX-a7c1-92de917ea2b0",
  "action": "post",
  "data": {
    "184524748161025": "1029544257947437432"
  },
  "duration": 0,
  "applicationName": "XXXX"
}