• 消息协议
    • 概述
    • 协议定义
    • 消息体定义
      • 消息体子类型定义
    • 消息示例
    • 相关文档

    消息协议

    概述

    JMessage 对于不同的消息类型，有一个 JSON 格式的消息协议。这个业务级别的协议，由发送者编码，由接收者解码，并处理接收到的消息。

    面向开发者接口提供的发送消息接口，也需要遵循此文档定义来组装消息，以发往客户端。

    协议定义

    • version Number
      • 必须。
      • 协议版本号。第一版本：1，以此类推。
    • target_type String
      • 必须。
      • 接收者类型。
      • 选项：single, group
    • target_id String
      • 必须。
      • 接收者ID。
      • 可能值：${username}, ${gid}
      • 接收方可用此字段，校验消息是不是发给自己的。
    • target_name String
      • 可选。
      • 接收者的展示名。
    • from_type String
      • 必须。
      • 发送方来源。
      • 选项：user, robot, admin, …。可用于扩展特定消息来源。
      • 用户只允许发送 from_type = user 的消息。
    • from_id String
      • 必须。
      • 发送者 username
    • from_name String
      • 可选。
      • 发送方展示名。
    • create_time Number
      • 必须。
      • 消息发送时间。
      • 精确到秒。
    • msg_type String
      • 必须。
      • 选项：text, voice, image, file, video, location, custom
    • msg_body JsonObject
      • 必须。
      • 消息实体。
    • from_appkey String
      • 可选
      • 发送者所属应用appkey

    消息体定义

    根据 msg_type 的不同，msg_body 里会有以下字段信息。

    • extras

      • 可选。
      • JsonObject
      • 用于附加参数。所有的消息类型都可以带此字段。
        msg_type = text

    • text String

      • 必须。
      • 文本类型消息内容。
        msg_type = voice

    • media_id String

      • 必须。
      • 媒体文件上传到得到的KEY，用于生成下载URL。
    • media_crc32 Number
      • 必须。
      • 文件的 CRC32 校验码。
    • duration Number
      • 必须。
      • 语音时长（单位：秒）
    • format String
      • 必须。
      • 语音类型。

    • fsize Number

      • 必须
      • 文件大小（字节数）
        msg_type = image

    • media_id String

      • 必须。
      • 媒体文件上传到得到的KEY，用于生成下载URL。
    • media_crc32 Number
      • 必须。
      • 文件的 CRC32 校验码。
    • width Number
      • 必须。
      • 原图片宽度。
    • height Number
      • 必须。
      • 原图片调度。
    • format String
      • 可选。
      • 图片格式。

    • fsize Number

      • 必须
      • 文件大小（字节数）
        msg_type = file

    • media_id String

      • 必须。
      • 媒体文件上传到得到的KEY，用于生成下载URL。
    • media_crc32 Number
      • 必须。
      • 文件的 CRC32 校验码。
    • fsize Number
      • 必须
      • 文件大小（字节数）

    • fname String

      • 必须
      • 文件名
        msg_type = location

    • latitude Number

      • 必须。
      • 纬度
    • longitude Number
      • 必须。
      • 经度
    • scale Number
      • 必须
      • 缩放比例

    • lable String

      • 必须
      • 位置信息
        msg_type = video

    • video JsonObject

      • 必须
      • 视频文件信息， 使用FileObject消息体子类型,类型定义见下文
    • duration Number
      • 必须
      • 视频时长

    • thumb JsonObject

      • 可选
      • 缩略图文件信息， 使用ImageObject消息体子类型,类型定义见下文
        msg_type = custom

    • 开发者自定义字段。JsonObject。

    消息体子类型定义

    FileObject

    • media_id String
      • 必须
      • 媒体文件上传之后得到的key，用于生成下载的URL
    • media_crc32 Number
      • 必须
      • 文件的 CRC32 校验码。
    • fsize Number
      • 必须
      • 文件大小

    • fname String

      • 必须
      • 发送与接收到的文件名
        ImageObject

    • media_id String

      • 必须
      • 媒体文件上传之后得到的key，用于生成下载的URL
    • media_crc32 Number
      • 必须
      • 文件的 CRC32 校验码。
    • format String
      • 必须
      • 图片格式
    • width Number
      • 必须
      • 图宽度
    • height Number
      • 必须
      • 图高度
    • fsize Number
      • 必须
      • 文件大小

    消息示例

    1. 文字消息
    2. {
    3.     "version": 1, 
    4.     "target_type": "single",
    5.     "target_id": "javen",
    6.     "target_name": "Javen Fang",
    7.     "from_type": "user",
    8.     "from_id": "fang", 
    9.     "from_name": "Fang Javen", 
    10.     "create_time": 135432432187,
    11.     "msg_type": "text",
    12.     "msg_body": {
    13.         "text": "Hello, JPush IM!"  
    14.     }
    15. }
    17. 图片消息
    18. {
    19.     "version": 1, 
    20.     "target_type": "single",
    21.     "target_id": "javen",
    22.     "from_type": "admin",
    23.     "from_id": "fang", 
    24.     "msg_type": "image",
    25.     "msg_body": {
    26.         "media_id": "qiniu/image/CE0ACD035CBF71F8",
    27.         "media_crc32":2778919613,
    28.         "width":3840,
    29.         "height":2160,
    30.         "fsize":3328738,
    31.         "format":"jpg"
    32.     }
    33. }
    35. 语音消息
    36. {
    37.     "version": 1, 
    38.     "target_type": "single",
    39.     "target_id": "ppppp",
    40.     "from_type": "admin",
    41.     "from_id": "admin_caiyh", 
    42.     "msg_type": "voice",
    43.     "msg_body": {
    44.         "media_id": "qiniu/voice/j/A96B61EB3AF0E5CDE66D377DEA4F76B8",
    45.         "media_crc32":1882116055,
    46.         "hash":"FoYn15bAGRUM9gZCAkvf9dolVH7h",
    47.         "fsize" :12344,
    48.         "duration": 6
    49.     }
    50. }
    52. 位置消息
    53. {
    54.     "version":1,
    55.     "target_type":"single", 
    56.     "target_id":"oooo", 
    57.     "target_appkey":"4f7aef34fb361292c566a1cd",
    58.     "from_type":"admin",
    59.     "from_id":"oooo",
    60.     "msg_type":"location",
    61.     "msg_body":{
    62.         "latitude":111.2,
    63.         "longitude":22.3,
    64.         "scale":500,
    65.         "label":"xx省xx市xx区xx街道"
    66.     }
    67. }
    69. 视频消息
    70. {
    71.     "version":1,
    72.     "target_type":"single", 
    73.     "target_id":"oooo", 
    74.     "target_appkey":"4f7aef34fb361292c566a1cd",
    75.     "from_type":"admin",
    76.     "from_id":"oooo",
    77.     "msg_type":"video",
    78.     "msg_body":{
    79.         "duration":10,
    80.         "thumb":{
    81.             "fsize":20736,
    82.             "width":72,
    83.             "format":"png",
    84.             "media_crc32":2565087609,
    85.             "media_id":"qiniu/image/a/707F13B42CEDB275702938DD13ED76E8.png",
    86.             "height":72
    87.         },
    88.         "video":{
    89.             "fname":"testvideo",
    90.             "fsize":2900883,
    91.             "media_crc32":428957395,
    92.             "media_id":"qiniu/file/a/2745EACC984972A4F914C7614CEC1572"
    93.         }
    94.     }
    95. }
    97. 自定义消息
    98. {
    99.     "version": 1, 
    100.     "target_type": "single",
    101.     "target_id": "ppppp",
    102.     "from_type": "admin",
    103.     "from_id": "admin_caiyh", 
    104.     "msg_type": "voice",
    105.     "msg_body": {
    106.         json define yourself
    107.     }
    108. }

    相关文档

    • JMessage 产品简介
    • IM REST API
    • 资源下载