logo文档中心
登录/注册控制台
文档
ZIM 客户端 API
ZPNs 客户端 API
ZIM Audio 客户端 API
服务端 API
即时通讯
API 概览
发布日志
调用方式
在线调试服务端 API
使用AI Codinglink
用户
房间
群组
消息
呼叫邀请
会话
社群
机器人
ZIM Audio
回调说明
全局返回码
服务端 API 调测指南
当前页

MessageBody 说明

2026-05-06

ZIM 服务端支持开发者通过服务端 API 向会话发送不同类型的消息，支持类型如下表所示：

消息类型MessageType 值适用会话类型是否支持全员推送
文本消息1
  • 单聊
  • 群聊
  • 房间
✔️
信令消息2✖
组合消息10✖
图片消息11✔️
文件消息12✔️
音频消息13✔️
视频消息14✔️
自定义消息200✔️
弹幕消息20房间✖

开发者在调用 ZIM 服务端接口发送消息时，需要通过参数 MessageBody 传入消息内容。MessageBody 的格式消息类型而不同，本文将介绍各类型消息的对应参数。

OfflinePush 字段说明

大部分 MessageBody 中包含 OfflinePush 字段，说明如下（房间消息不支持此字段）：

参数类型是否必选描述
EnableNumber否是否推送：
  • 0：（默认）否。
  • 1：是。
TitleString否离线推送展示的标题。
ContentString否离线推送展示的内容。
PayloadString否扩展字段，开发者可以自定义收到离线推送消息后的行为。
PushStrategyIdString否自定义推送策略，配置方式请参考 resourcesID 说明。
注意
PushImageInfoObject否图片推送信息。
注意
└ApnsObject否苹果推送额外信息。
    └ImageString否该字段用于标识 APNs 携带的图片地址，当客户端拿到该字段时，可以通过下载图片资源的方式将图片展示在弹窗上。
└AndroidObject否安卓推送额外信息。
    └HuaWeiObject否华为推送通道相关配置。
        └ImageString否图片文件须小于 512 KB，规格建议为 40dp x 40dp，弧角大小为 8dp。超出建议规格的图片会存在图片压缩或图片显示不全的情况。图片格式建议使用JPG/JPEG/PNG。必须是https协议的链接。
        └IconString否图标文件必须存放在应用的 /res/raw 路径下。例如，"icon" 的值为"res/raw/ic_launcher"，标识您应用本地的小图标路径为"/res/raw/ic_launcher.jpg"。
    └FCMObject否谷歌推送通道相关配置。
        └ImageString否图片地址，大小限制 1M 以内。
        └IconString否图标地址。
EnableBadgeBoolean否系统推送是否携带角标信息。
  • true：是。
  • false：否。
BadgeIncrementNumber否指定用户接收离线推送时，App 图标角标应增加的数量。默认为 0。取值范围 [0, 99]，超过 99 按 99 处理。
PrivateMessageTemplateObject否OPPO 推送私信模版，默认值为空。如果您使用 OPPO 推送，可以通过该结构来应用 OPPO 私信模版。
└TemplateIdString否OPPO 私信模板id。下发对应私信模板时必须携带，不支持自拟。详细请参考 OPUSH 私信模板校验。
└TitleParametersString否OPPO 标题模板填充参数。例：私信模板 id 标题模板为：欢迎来到$ {city} $ ，$ {city} $ 欢迎您。此参数内容为：{“city”:“北京”}
└ContentParametersString否OPPO 内容模板填充参数。例：私信模板 id 对应的内容模板为：欢迎$ {userName} $ 来到$ {city} $ 。此参数内容为：{“userName”:“汤姆”，“city”:“深圳市”}
ThreadIdString否APNs 消息分组 Id

文本消息、自定义消息和弹幕消息

MessageBody 结构

文本消息、自定义消息和弹幕消息的 MessageBody 结构相同，说明如下：

参数类型是否必选描述
MessageString是消息内容，默认为 2 KB，不可为空。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
ExtendedDataString否扩展字段，长度上限为 1 KB，如需上调，请联系 ZEGO 技术支持。
OfflinePushObject否离线推送配置，详情请参考 OfflinePush 说明。
注意
导入消息时，此参数无意义。
HasReceiptNumber否消息是否附带回执：
  • 0：不是。
  • 1：是。
注意
  • 弹幕消息不支持附带回执。
  • 导入消息时，此参数无意义。

MessageBody 示例

{
  "MessageBody": {
      "Message":"hello world",
      "ExtendedData":"extendedData",
      "OfflinePush" :{
          "Enable":0,
          "Title":"Title",
          "Content":"Content",
          "Payload":"data"
      },
      "HasReceipt": 1
  }
}

信令消息

MessageBody 结构

参数类型是否必选描述
MessageString是信令消息内容，默认为 2 KB，不可为空。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
注意

若消息为经 base64 编码后的内容，则此处的长度限制指的是在 base64 编码前的原消息长度。

ExtendedDataString否扩展字段，长度上限为 1 KB，如需上调，请联系 ZEGO 技术支持。
IsBase64Number否是否为 base64 编码后的消息。
  • 0：否（默认）。
  • 1：是。ZIM 服务端收到此消息后，会进行 base64 解码，获取实际消息内容，再发送给 ZIM SDK。

MessageBody 示例

{
    "MessageBody": {
        "Message":"hello world",
        "ExtendedData":"extendedData",
        "IsBase64":0
    }
}

组合消息

MessageBody 结构

参数类型是否必选描述
MessageString是组合消息内容，为按照组合消息类型的 Message 结构生成的 JSON 字节串，默认为 5 KB，不可为空。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
ExtendedDataString否扩展字段，长度上限为 1 KB，如需上调，请联系 ZEGO 技术支持。
OfflinePushObject否离线推送配置，详情请参考 OfflinePush 说明。
注意
导入消息时，此参数无意义。
HasReceiptNumber否消息是否附带回执：
  • 0：不是。
  • 1：是。
注意
导入消息时，此参数无意义。

MessageBody 示例

{
    "MessageBody": {
        "Message":"", // 组合消息内容，为按组合消息类型的 Message 结构生成的 JSON 字节串
        "ExtendedData":"extendedData",
        "OfflinePush" :{
            "Enable":0,
            "Title":"Title",
            "Content":"Content",
            "Payload":"data"
        },
        "HasReceipt": 1
    }
}

Message 结构

参数类型是否必选描述
MultiMsgArray of Object是组合消息 Item 数组，长度上限为 20。
└MsgTypeNumber是Item 类型，目前支持 1（文本）、11（图片）、12（文本）、13（音频）、14（视频）和 200（自定义消息）。
└SubMsgTypeNumber否仅当 MsgType 为 200 时需填入。
└MsgString是Item 内容。
  • 当 Item 类型为 1 或 200 时，此处可直接传入消息内容。
  • 当 Item 类型为 11、12、13 或 14 时，请参考本文档对相应类型消息的 Message 结构生成 JSON 字符串并传入此处。
└SearchedContentString否搜索内容，仅当 MsgType 为 200 时，可选。

Message 示例

{
    "MultiMsg": [
        {
            "MsgType": 1,
            "Msg": "11111"
        },
        {
            "MsgType": 11,
            "Msg": "xxxx" // 参考本文档对相应类型消息的 Message 结构生成 JSON 字符串并传入此处
        }
    ]
}

图片消息

MessageBody 结构

参数类型是否必选描述
MessageString是图片消息内容，为按照图片消息的 Message 结构 生成的 JSON 字节串，默认为 2 KB，不可为空。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
ExtendedDataString否扩展字段，长度上限为 1 KB，如需上调，请联系 ZEGO 技术支持。
OfflinePushObject否离线推送配置，详情请参考 OfflinePush 说明。
注意
导入消息时，此参数无意义。
HasReceiptNumber否消息是否附带回执：
  • 0：不是。
  • 1：是。
注意
导入消息时，此参数无意义。

MessageBody 示例

{
    "MessageBody": {
        "Message":"", // 图片消息内容，为按图片消息的 Message 结构生成的 JSON 字节串
        "ExtendedData":"extendedData",
        "OfflinePush" :{
            "Enable":0,
            "Title":"Title",
            "Content":"Content",
            "Payload":"data"
        },
        "HasReceipt": 1
    }
}

Message 结构

参数类型是否必选描述
UidString是图片的唯一 ID。由开发者自行生成。
OriginObject是原图。
└UrlString是原图的 URL 地址，长度上限为 500 字节。
└WidthNumber是原图宽度，单位为像素（px）。
└HeightNumber是原图高度，单位为像素（px）。
LargeImageObject否大图。
└UrlString否大图的 URL 地址，长度上限为 500 字节。
└WidthNumber否大图宽度，单位为像素（px）。
└HeightNumber否大图高度，单位为像素（px）。
ThumbnailObject否缩略图。
└UrlString否缩略图的 URL 地址，长度上限为 500 字节。
└WidthNumber否缩略图宽度，单位为像素（px）。
└HeightNumber否缩略图高度，单位为像素（px）。
FileNameString是文件名称，格式建议为 "xxx.文件扩展名"，长度上限为 150 字节。
SizeNumber否图片数据大小，单位为字节。

Message 示例

{
    "Uid":"343649807833778782", 
    "Origin": {
        "Url":"https:xxx", 
        "Width":100,
        "Height":200
    },
    "FileName":"FileName.jpg", 
    "Size":1024
}

文件消息

MessageBody 结构

参数类型是否必选描述
MessageString是文件消息内容，为按照文件消息的 Message 结构 生成的 JSON 字节串，默认为 2 KB，不可为空。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
ExtendedDataString否扩展字段，长度上限为 1 KB，如需上调，请联系 ZEGO 技术支持。
OfflinePushObject否离线推送配置，详情请参考 OfflinePush 说明。
注意
导入消息时，此参数无意义。
HasReceiptNumber否消息是否附带回执：
  • 0：不是。
  • 1：是。
注意
导入消息时，此参数无意义。

MessageBody 示例

{
    "MessageBody": {
        "Message":"", // 文件消息内容，为按文件消息的 Message 结构生成的 JSON 字节串
        "ExtendedData":"extendedData",
        "OfflinePush" :{
            "Enable":0,
            "Title":"Title",
            "Content":"Content",
            "Payload":"data"
        },
        "HasReceipt": 1
    }
}

Message 结构

参数类型是否必选描述
UidString是文件的唯一 ID。由开发者自行生成。
UrlString是文件的 URL 地址，长度上限为 500 字节。
FileNameString是文件名称，格式建议为 “xxx.文件扩展名”，长度上限为 150 字节。
SizeNumber否文件数据大小，单位为字节。

Message 示例

{
  "Uid":"343649807833778782", 
  "Url":"https:xxx", 
  "FileName":"FileName.txt", 
  "Size":1024
}

音频消息

MessageBody 结构

参数类型是否必选描述
MessageString是视频消息内容，为按照音频消息的 Message 结构 生成的 JSON 字节串，默认为 2 KB，不可为空。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
ExtendedDataString否扩展字段，长度上限为 1 KB，如需上调，请联系 ZEGO 技术支持。
OfflinePushObject否离线推送配置，详情请参考 OfflinePush 说明。
HasReceiptNumber否消息是否附带回执：
  • 0：不是。
  • 1：是。
注意
导入消息时，此参数无意义。

MessageBody 示例

{
    "MessageBody": {
        "Message":"", // 音频消息内容，为按音频消息的 Message 结构生成的 JSON 字节串
        "ExtendedData":"extendedData",
        "OfflinePush" :{
            "Enable":0,
            "Title":"Title",
            "Content":"Content",
            "Payload":"data"
        },
        "HasReceipt": 1
    }
}

Message 结构

参数类型是否必选描述
UidString是音频的唯一 ID。由开发者自行生成。
UrlString是音频的 URL 地址，长度上限为 500 字节。
FileNameString是音频名称，格式建议为 “xxx.文件扩展名”，长度上限为 150 字节。
SizeNumber否音频数据大小，单位为字节。
MediaDurationNumber否音频时长，单位为秒。

Message 示例

{
    "Uid":"343649807833778782", 
    "Url":"https:xxx", 
    "FileName":"FileName.mp3", 
    "Size":1024,
    "MediaDuration":30
}

视频消息

MessageBody 结构

参数类型是否必选描述
MessageString是视频消息内容，为按照视频消息的 Message 结构 生成的 JSON 字节串，默认为 2 KB，不可为空。如有需要，请联系 ZEGO 技术支持配置，最大可达 32 KB。
ExtendedDataString否扩展字段，长度上限为 1 KB，如需上调，请联系 ZEGO 技术支持。
OfflinePushObject否离线推送配置，详情请参考 OfflinePush 说明。
注意
导入消息时，此参数无意义。
HasReceiptNumber否消息是否附带回执：
  • 0：不是。
  • 1：是。
注意
导入消息时，此参数无意义。

MessageBody 示例

{
    "MessageBody": {
        "Message":"", // 视频消息内容，为按音频消息的 Message 结构生成的 JSON 字节串
        "ExtendedData":"extendedData",
        "OfflinePush" :{
            "Enable":0,
            "Title":"Title",
            "Content":"Content",
            "Payload":"data"
        },
        "HasReceipt": 1
    }
}

Message 结构

参数类型是否必选描述
UidString是文件的唯一 ID。由开发者自行生成。
UrlString是视频的 URL 地址，长度上限为 500 字节。
FileNameString是视频名称，格式建议为 “xxx.文件扩展名”，长度上限为 150 字节。
SizeNumber否视频数据大小，单位为字节。
MediaDurationNumber否视频时长，单位为秒。
ThumbnailObject否视频首帧。
└UrlString是（仅当需要视频首帧时）缩略图的 URL 地址，长度上限为 500 字节。
└WidthNumber是（仅当需要视频首帧时）图片宽度，单位为像素（px）。如果设置了 Thumbnail 则该值不能为 0。
└HeightNumber是（仅当需要视频首帧时）图片高度，单位为像素（px）。如果设置了 Thumbnail 则该值不能为 0。

Message 示例

{
    "Uid":"343649807833778782", 
    "Url":"https:xxx", 
    "FileName":"FileName.mp4", 
    "Size":1024,
    "MediaDuration":300,
    "Thumbnail": {
        "Url":"https:xxx", 
        "Width":100,
        "Height":200
    }
}

上一篇

解散群组

下一篇

发送单聊消息

当前页

返回到顶部