logo
即时通讯
机器人
ZIM Audio
当前页

发送单聊消息

POST

https://zim-api.zego.im/

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

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

说明
开通内容审核功能后,默认情况下服务端发送的消息会进行审核。如果服务端发送的消息不需要审核,请联系 ZEGO 技术支持进行配置。
iOSAndroidmacOSWindows
peerMessageReceivedonPeerMessageReceivedpeerMessageReceivedonPeerMessageReceived
Web小程序FlutterReact Native
peerMessageReceivedpeerMessageReceivedonPeerMessageReceivedpeerMessageReceived
Unity3Duni-app | uni-app xHarmonyOS
OnReceivePeerMessagepeerMessageReceivedpeerMessageReceived
说明
参数 FromUserIdToUserId 对应的用户已在客户端调用 login 方法登录 ZIM 服务,或开发者已调用 服务端 API 注册相关的 userID。
说明

参数 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 版本,则无法收到自定义消息,也不会收到未知消息。

说明
调用频率限制:20 次/秒。

Request

Query Parameters

    Action string必填

    可选值: [SendPeerMessage]

    接口原型参数

    https://zim-api.zego.im/?Action=SendPeerMessage

    AppId uint32必填

    💡公共参数。应用 Id,由 ZEGO 分配的用户唯一凭证。可从 ZEGO 控制台 获取。

    SignatureNonce string必填

    💡公共参数。16 位 16 进制随机字符串(8 字节随机数的 hex 编码)。生成算法可参考 签名示例

    Timestamp int64必填

    💡公共参数。当前 Unix 时间戳,单位为秒。生成算法可参考 签名示例,最多允许 10 分钟的误差。

    SignatureVersion string必填

    可选值: [2.0]

    默认值: 2.0

    💡公共参数。签名版本号。

    Signature string必填

    💡公共参数。签名,用于验证请求的合法性。请参考签名机制生成。

Body

required
    FromUserId string必填

    可选值: <= 32 characters

    发送方用户 ID。

    ToUserId string[]必填

    可选值: <= 100

    接收方的用户 ID 列表,最大支持 100 个用户 ID。

    说明

    列表中不能包含与 FromUserId 相同的 userID,即发送方不可以给自己发消息。

    MessageType number必填

    消息类型,单聊会话的适用类型请参考 MessageBody 说明。

    Priority int32必填

    可选值: [1, 2, 3]

    消息优先级(详情请参考 基本概念介绍 - 消息优先级),取值如下:

    • 1:低。
    • 2:中。
    • 3:高。
    MessageBody object必填

    消息内容,具体参数格式请参考 MessageBody 说明。

    SubMsgType number

    具体的自定义类型。值由您定义,取值范围为 [0,200]。当 MessageType 为自定义消息时,才需赋值此参数

    SearchedContent string

    自定义消息的检索字段。当 MessageType 为自定义消息时,才可填写此字段,长度上限默认为 64 字节。此字段作用于客户端,除非填写了此字段,否则无法通过客户端搜索到关联的自定义消息。

    SenderUnaware number

    通过本服务端接口发送消息,请求参数中的 FromUserId 所对应的客户端是否能感知此次发送:

    • 0:(默认)可以感知。
    • 1:无感知。
    SendMsgOptions object
    可选配置项。
    NoUnread boolean

    此消息是否会增加接收方的消息未读数。

    • false: (默认值)会。
    • true:不会。

Responses

OK
Schema
    Code number

    返回码。

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

    说明

    当您发起请求同时向多个用户发送消息时:

    • 如果只需成功向 1 个或以上的用户发送消息,Code 都会返回 0,表示成功。此时请参考 ErrorList 中的具体信息,确认操作结果,了解是否向部分用户发送消息失败。
    • 如果向所有用户发送消息都失败,Code 会返回相关返回码,具体请参考 全局返回码
    Code / SubCode说明处理建议
    660000011用户个数超过限制,输入的用户列表过大。请检查输入的用户列表。
    660000025MessageBody 中 IsBase64 传入 1 后,发送经 base64 编码的信令消息失败。 请确认:
    • 请确认 IsBase64 是否需要为 1,即是否需要发送二进制类型信令消息。
    • 请确认消息内容是否经 base64 编码。
    660400001输入的消息大小超出限制。请检查输入的消息大小。
    Message string

    返回信息。

    RequestId string

    请求 ID。

    ErrorList object[]
    失败列表。
    • Code 为 0:
    • ErrorList 为空,全部单聊消息发送成功。
    • ErrorList 不为空,表示部分单聊消息发送失败,请参考 SubCode 处理。
    • Code 不为 0:
    • ErrorList 为空,表示参数错误、接口频率限制、系统错误。
    • ErrorList 不为空,表示全部单聊消息发送失败。
  • Array[
  • UserId string

    发送消息失败的目标 UserID。

    SubCode number

    发送消息失败的具体返回码,完整返回码请参考 Code 说明或者 全局返回码

  • ]
  • SuccList object[]
    消息接受成功的用户列表。
  • Array[
  • UserId string

    用户 ID。

    MsgId string

    消息 ID。全局唯一。

    MsgSeq number

    消息 Seq。当消息类型为信令消息时,此字段为空。可用于 撤回单聊消息

  • ]
  • AuditInfos object[]
    审核结构数组,当数组不为空时,说明存在审核失败的消息,可以通过该结构查看审核失败原因。
  • Array[
  • Index number

    此参数可能出现以下几种情况:

    当您已启用 ZIM 内容审核服务,且未通过 发送消息前回调 拒绝该消息时:

    • 对于组合消息,此参数表示未通过审核的 Item 在组合消息中的索引,从 0 开始。
    • 对于其他类型消息,则此参数始终为 0。

    当您收到发送消息前回调后拒绝了此消息,则不论消息类型,此参数始终为 0。

    Reason string

    拒绝原因。

  • ]

上一篇

MessageBody 说明

下一篇

发送群组消息

当前页

返回到顶部