文档中心
即时通讯
服务端 API
消息相关
发送单聊消息

发送单聊消息

更新时间：2024-09-19 15:57

描述

发送 1v1 单聊消息，支持向单个用户、或批量向多个用户发送消息。

目标客户端将通过 ZIM SDK 的回调接口，接收单聊消息的通知。

iOS	Android	macOS	Windows	Web
receivePeerMessage	onReceivePeerMessage	receivePeerMessage	onReceivePeerMessage	receivePeerMessage
小程序	Flutter	Unity3D	uni-app	React Native
receivePeerMessage	onReceivePeerMessage	OnReceivePeerMessage	receivePeerMessage	receivePeerMessage

接口原型

请求方法：POST
请求地址：https://zim-api.zego.im/?Action=SendPeerMessage
传输协议：HTTPS
调用频率限制：20 次/秒。

请求参数

以下请求参数列表仅列出了接口请求参数和部分公共参数，完整公共参数列表请参考调用方式 - 公共请求参数。

参数	类型	是否必选	描述
FromUserId	String	是	发送方的用户 ID。
ToUserId	Array of String	是	接收方的用户 ID 列表，最大支持 100 个用户 ID。
MessageType	Number	是	消息类型，单聊会话的适用类型请参考 MessageBody 说明。
Priority	Number	是	消息优先级，取值如下： 1：低。 2：中。 3：高。
MessageBody	Object	是	消息内容，具体参数格式请参考 MessageBody 说明。
SubMsgType	Number	当 MessageType 为自定义消息时，才需赋值此参数	具体的自定义类型。值由您定义，取值范围为 [0,200]。
SearchedContent	String	否	自定义消息的检索字段。当 MessageType 为自定义消息时，才可填写此字段，长度上限默认为 64 字节。此字段作用于客户端，除非填写了此字段，否则无法通过客户端搜索到关联的自定义消息。
SenderUnaware	Number	否	通过本服务端接口发送消息，请求参数中的 FromUserId 所对应的客户端是否能感知此次发送： 0：（默认）可以感知。 1：无感知。

FromUserId、ToUserId 仅支持数字，英文字符和 '!'，'#'，'$'，'%'，'&'，'('，')'，'+'，'-'，':'，';'，'<'，'='，'.'，'>'，'?'，'@'，'['，']'，'^'，'_'，' '，'{'，'}'，'|'，'~'。
如果发送方使用的 SDK 版本（版本说明请参考发布日志）低于 2.0.0，ZIM 服务端对应的仅支持 MessageType 为 2 的 Command 类型消息，不支持其它类型。
为了给开发者带来更好的体验，ZEGO 推荐开发者使用最新版本的 SDK。
如果发送方请求发送 MessageType 为 1 的文本消息，则发送方对应的客户端（SDK 版本需为 2.7.0 或以上）也会收到该消息。
对于发送和接收 MessageType 为 200 的自定义消息，发送方和接收放对应的客户端的 SDK 版本需为 2.8.0 或以上。
如果接收端的 SDK 版本介乎 [2.0.0, 2.8.0) 区间，可以收到自定义消息时，但会显示此消息类型为未知，且无法获取信息内容。如需获取此条消息，请将 SDK 升级为 2.8.0 或以上版本。
如果接收端的 SDK 版本为 1.x.x 版本，则无法收到自定义消息，也不会收到未知消息。

请求示例

请求地址 URL：

https://zim-api.zego.im/?Action=SendPeerMessage
&<公共请求参数>

请求消息体：

{
    "FromUserId": "u1",
    "ToUserId":[
        "u2",
        "u3"
    ],
    "MessageType": 1,
    "Priority": 1,
    "MessageBody": {
        "Message":"hello world",
        "ExtendedData":"s",
        "OfflinePush" :{
            "Enable":0,
            "Title":"Title",
            "Content":"Content",
            "Payload":"data"
        }
    }
}

响应参数

参数	类型	描述
Code	Number	返回码。当您发起请求同时向多个用户发送消息时：如果只需成功向 1 个或以上的用户发送消息，Code 都会返回 0，表示成功。此时请参考 ErrorList 中的具体信息，确认操作结果，了解是否向部分用户发送消息失败。如果向所有用户发送消息都失败，Code 会返回相关返回码，具体请参考全局返回码。
Message	String	请求结果的说明信息。
RequestId	String	请求 ID。
ErrorList	Array of String	失败列表。 Code 为 0： ErrorList 为空，全部单聊消息发送成功。 ErrorList 不为空，表示部分单聊消息发送失败，请参考 SubCode 处理。 Code 不为 0： ErrorList 为空，表示参数错误、接口频率限制、系统错误。 ErrorList 不为空，表示全部单聊消息发送失败。
UserID	String	发送消息失败的目标 UserID。
SubCode	Number	发送消息失败的具体返回码。
SuccList	Array of Object	消息接受成功的用户列表。
UserId	String	用户 ID。
MsgId	String	消息 ID。全局唯一。
MsgSeq	Number	消息 Seq。当消息类型为信令消息时，此字段为空。可用于撤回单聊消息。

响应示例

{
    "Code":0,
    "Message":"success",
    "RequestId":"343649807833778782",
    "ErrorList": [
        {
            "UserId": "u3",
            "SubCode": 1
        }
    ],
    "SuccList": [
        {
            "UserId": "id4",
            "MsgId": "6654861479614",
            "MsgSeq": 1
        }
    ] 
}

返回码

以下仅列出了接口业务逻辑相关的返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
660000011	用户个数超过限制，输入的用户列表过大。	请检查输入的用户列表。
660000025	`MessageBody` 中 `IsBase64` 传入 1 后，发送经 base64 编码的信令消息失败。	请确认：请确认 `IsBase64` 是否需要为 1，即是否需要发送二进制类型信令消息。请确认消息内容是否经 base64 编码。
660400001	输入的消息大小超出限制。	请检查输入的消息大小。