消息协议

概述

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. }

相关文档