即时通讯
  • iOS : Objective-C
  • Android
  • macOS
  • Windows
  • Web
  • 小程序
  • Flutter
  • Unity3D
  • uni-app
  • React Native
  • 产品简介
  • 下载
  • 快速开始
    • 跑通示例源码
    • 实现基本消息收发
  • 用户相关
  • 房间相关
  • 群组相关
  • 消息相关
  • 呼叫邀请
  • 会话管理
  • 离线推送
  • 常见错误码
  • 服务端 API
  • 客户端 API
  • 常见问题

发送单聊消息

更新时间:2023-03-07 22:37

1 描述

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

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

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

平台 接口
iOS/macOS
zim:receivePeerMessage:fromUserID:
Android
onReceivePeerMessage
Windows
onReceivePeerMessage
Web/小程序
receivePeerMessage

2 接口原型

  • 请求方法:POST
  • 请求地址:https://zim-api.zego.im/?Action=SendPeerMessage
  • 传输协议:HTTPS

3 请求参数

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

参数 类型 是否必选 描述
FromUserId
String
发送方的用户 ID。
ToUserId
Array of String
接收方的用户 ID 列表,最大支持 100 个用户 ID。
MessageType
Number
消息类型,取值如下:

  • 1:文本消息。
  • 2:Command 消息,即信令消息(Command 消息不存储,不保证可靠)。
Priority
Number
消息优先级,取值如下:

  • 1:低。
  • 2:中。
  • 3:高。
MessageBody
Object
消息内容,具体参数格式请参考 MessageBody

FromUserId、ToUserId 仅支持数字,英文字符和 '!','#','$','%','&','(',')','+','-',':',';','<','=','.','>','?','@','[',']','^','_',' ','{','}','|','~'。

根据 MessageType 的取值不同,MessageBody 的格式不同,请参考下表:

MessageType MessageBody
参数格式
类型 是否必选 描述
1(文本消息)
Message
String
文本消息内容,默认为 2 KB;最大为 32 KB,如有需要请联系 ZEGO 技术支持配置。
ExtendedData
String
扩展字段。
OfflinePush
Object
离线推送。
└ Enable
Int32
是否开启离线推送:

  • 0:不推送(默认值)。
  • 1:推送。
└ Title
String
是(仅当填写了 OfflinePush 时)
离线推送展示的标题,最大 20 个字符。
└ Content
String
是(仅当填写了 OfflinePush 时)
离线推送展示的内容,最大 50 个字符。
└ Payload
String
扩展字段,开发者可以自定义收到离线推送消息后的行为。
2(Command 消息)
Message
String
Command 消息内容,默认为 2 KB;最大为 32 KB,如有需要请联系 ZEGO 技术支持配置。
ExtendedData
String
扩展字段。

如果您使用的 SDK 版本(版本说明请参考 发布日志)低于 2.0.0,ZIM 服务端对应的仅支持 MessageType2 的 Command 类型消息,不支持其它类型。

为了给开发者带来更好的体验,ZEGO 推荐开发者使用最新版本的 SDK。

  • 如果发送方使用的 SDK 版本(版本说明请参考 发布日志)低于 2.0.0,ZIM 服务端对应的仅支持 MessageType2 的 Command 类型消息,不支持其它类型。
    为了给开发者带来更好的体验,ZEGO 推荐开发者使用最新版本的 SDK。
  • 如果发送方请求发送 MessageType 为 1 的文本消息,则发送方对应的客户端(SDK 版本需为 2.7.0 或以上)也会收到该消息。

4 请求示例

  • 请求地址 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"
            }
        }
    }

5 响应参数

参数 类型 描述
Code
Number
返回码。
Message
String
请求结果的说明信息。
RequestId
String
请求 ID。
ErrorList
Array of String
失败列表。如果请求失败,失败信息将通过此字段返回。

6 响应示例

{
    "Code":0,
    "Message":"success",
    "RequestId":"343649807833778782",
    "ErrorList": [
        {
            "UserId": "id4",
            "SubCode": 1
        }
    ] 
}

7 返回码

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

返回码 说明 处理建议
660000011
用户个数超过限制,输入的用户列表过大。
请检查输入的用户列表。
660400001
输入的消息大小超出限制。
请检查输入的消息大小。