OpenIMSDK文档

输入至少两个字符来搜索标题和路径。

简中

语言

ENEnglishEnglish docs简中简体中文中文文档
浏览 平台 API
服务端 API

消息内容类型

复制

发送消息时，contentType 决定 content 的 JSON 结构。contentType 与 content 必须匹配，否则客户端可能无法解析或渲染消息。

图片、语音、视频和文件消息只在消息体中保存资源地址和元数据。调用发送消息接口前，应先把文件上传到对象存储或业务文件服务，再将可访问的 URL 写入对应字段。

contentType 对照

contentType消息类型content 结构
101文本消息TextElem
102图片消息PictureElem
103语音消息SoundElem
104视频消息VideoElem
105文件消息FileElem
106@ 消息AtTextElem
107合并消息MergeElem
108名片消息CardElem
109位置消息LocationElem
110自定义消息CustomElem
114引用消息QuoteElem
115表情消息FaceElem
117高级文本消息AdvancedTextElem

文本消息

{
  "contentType": 101,
  "content": {
    "content": "hello"
  }
}
字段必填类型说明
content是string文本消息内容。

图片消息

{
  "contentType": 102,
  "content": {
    "sourcePath": "",
    "sourcePicture": {
      "uuid": "image_001",
      "type": "png",
      "size": 204800,
      "width": 1280,
      "height": 720,
      "url": "https://example.com/images/source.png"
    },
    "bigPicture": {
      "uuid": "image_001_big",
      "type": "png",
      "size": 102400,
      "width": 640,
      "height": 360,
      "url": "https://example.com/images/big.png"
    },
    "snapshotPicture": {
      "uuid": "image_001_snapshot",
      "type": "png",
      "size": 20480,
      "width": 160,
      "height": 90,
      "url": "https://example.com/images/snapshot.png"
    }
  }
}
字段必填类型说明
sourcePath否string图片本地路径。服务端发送时通常为空。
sourcePicture是object原图信息，结构为 PictureBaseInfo。
bigPicture是object大图信息，结构为 PictureBaseInfo。
snapshotPicture是object缩略图信息，结构为 PictureBaseInfo。

PictureBaseInfo

字段必填类型说明
uuid否string图片文件唯一 ID。
type是string图片文件类型，例如 png、jpg。
size否int64图片文件大小，单位为字节。
width是int图片宽度，单位为像素。
height是int图片高度，单位为像素。
url是string图片文件的可访问地址。

语音消息

{
  "contentType": 103,
  "content": {
    "uuid": "audio_001",
    "soundPath": "",
    "sourceUrl": "https://example.com/audio/voice.m4a",
    "dataSize": 24576,
    "duration": 12,
    "soundType": "m4a"
  }
}
字段必填类型说明
uuid否string语音文件唯一 ID。
soundPath否string语音文件本地路径。服务端发送时通常为空。
sourceUrl是string语音文件的可访问地址。
dataSize否int64语音文件大小，单位为字节。
duration是int64语音时长，单位应与客户端 SDK 约定保持一致。
soundType否string语音文件类型，例如 m4a。

视频消息

{
  "contentType": 104,
  "content": {
    "videoPath": "",
    "videoUUID": "video_001",
    "videoUrl": "https://example.com/video/demo.mp4",
    "videoType": "mp4",
    "videoSize": 5242880,
    "duration": 30,
    "snapshotPath": "",
    "snapshotUUID": "snapshot_001",
    "snapshotSize": 65536,
    "snapshotUrl": "https://example.com/video/demo-cover.jpg",
    "snapshotWidth": 640,
    "snapshotHeight": 360
  }
}
字段必填类型说明
videoPath否string视频本地路径。服务端发送时通常为空。
videoUUID否string视频文件唯一 ID。
videoUrl是string视频文件的可访问地址。
videoType是string视频文件类型，例如 mp4。
videoSize是int64视频文件大小，单位为字节。
duration是int64视频时长，单位应与客户端 SDK 约定保持一致。
snapshotPath否string视频封面图本地路径。服务端发送时通常为空。
snapshotUUID否string视频封面图唯一 ID。
snapshotSize否int64视频封面图大小，单位为字节。
snapshotUrl是string视频封面图的可访问地址。
snapshotWidth是int视频封面图宽度，单位为像素。
snapshotHeight是int视频封面图高度，单位为像素。

文件消息

{
  "contentType": 105,
  "content": {
    "filePath": "",
    "uuid": "file_001",
    "sourceUrl": "https://example.com/files/report.pdf",
    "fileName": "report.pdf",
    "fileSize": 1048576,
    "fileType": "pdf"
  }
}
字段必填类型说明
filePath否string文件本地路径。服务端发送时通常为空。
uuid否string文件唯一 ID。
sourceUrl是string文件的可访问地址。
fileName是string文件名称。
fileSize是int64文件大小，单位为字节。
fileType否string文件类型，例如 pdf。

@ 消息

{
  "contentType": 106,
  "content": {
    "text": "@Tom 请查看",
    "atUserList": ["user_002"],
    "isAtSelf": false
  }
}
字段必填类型说明
text否string消息文本内容。
atUserList是string[]被提及用户的 ID 列表。使用 AtAllTag 时表示提及全部成员。
isAtSelf否boolean当前消息是否提及消息接收方自身，通常由客户端使用。
quoteMessage否object@ 消息附带的引用消息。没有引用内容时可不传。

合并消息

{
  "contentType": 107,
  "content": {
    "title": "聊天记录",
    "abstractList": ["Tom: hello", "Jerry: received"],
    "multiMessage": []
  }
}
字段必填类型说明
title是string合并消息标题。
abstractList是string[]合并消息摘要列表，用于会话界面预览。
multiMessage是object[]被合并的消息列表。元素为完整消息对象，字段应与当前 OpenIM 消息结构保持一致。

名片消息

{
  "contentType": 108,
  "content": {
    "userID": "user_002",
    "nickname": "Tom",
    "faceURL": "https://example.com/avatar/tom.png",
    "ex": ""
  }
}
字段必填类型说明
userID是string名片对应的 OpenIM 用户 ID。
nickname是string名片展示名称。
faceURL是string名片头像地址。
ex否string业务扩展字段。

位置消息

{
  "contentType": 109,
  "content": {
    "description": "OpenIM office",
    "longitude": 113.93041,
    "latitude": 22.53332
  }
}
字段必填类型说明
description否string位置描述。
longitude是double经度。
latitude是double纬度。

自定义消息

{
  "contentType": 110,
  "content": {
    "data": "{\"type\":\"order_paid\",\"orderID\":\"order_001\"}",
    "description": "Order paid",
    "extension": "{\"source\":\"backend\"}"
  }
}
字段必填类型说明
data是string业务自定义消息内容。通常使用 JSON 字符串，并由业务客户端解析。
description否string自定义消息的描述信息。
extension否string自定义扩展字段。

引用消息

{
  "contentType": 114,
  "content": {
    "text": "收到",
    "quoteMessage": {
      "clientMsgID": "client_msg_001",
      "serverMsgID": "server_msg_001",
      "sendID": "user_001",
      "contentType": 101,
      "content": "{\"content\":\"hello\"}"
    }
  }
}
字段必填类型说明
text是string回复文本。
quoteMessage是object被引用的完整消息对象。示例只展示常用字段，实际结构应与当前 OpenIM 消息对象保持一致。

表情消息

{
  "contentType": 115,
  "content": {
    "index": 1,
    "data": "{\"name\":\"smile\"}"
  }
}
字段必填类型说明
index是int表情索引。
data否string表情自定义数据，通常为 JSON 字符串。

高级文本消息

{
  "contentType": 117,
  "content": {
    "text": "请查看附件",
    "messageEntityList": []
  }
}
字段必填类型说明
text是string高级文本消息正文。
messageEntityList是object[]正文中的实体列表，例如文件、图片或其他业务片段。实体结构由当前客户端 SDK 定义。

使用建议

  • contentType 和 content 必须严格匹配。不要只修改类型编号而复用其他类型的内容结构。
  • 媒体类消息应先上传资源，再把资源 URL 和元数据写入 content。Platform API 不直接接收媒体二进制内容。
  • sourcePath、soundPath、videoPath、snapshotPath 和 filePath 是客户端本地路径，服务端发送时通常留空。
  • 自定义消息需要在客户端和业务服务端之间约定 data、description 和 extension 的业务协议。
  • 导入历史消息时，应保留原始 contentType、content 和 sendTime，并确认旧系统消息结构能够被当前客户端识别。

相关页面