消息功能

发送普通消息

请求说明

POST https://api.netease.im/nimserver/msg/sendMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

给用户或者高级群发送普通消息,包括文本,图片,语音,视频和地理位置,具体消息参考下面描述

参数说明

参数类型必须说明
fromString 发送者accid,用户帐号,最大32字符,
必须保证一个APP内唯一
opeint 0:点对点个人消息,1:群消息(高级群),其他返回414
toString ope==0是表示accid即用户id,ope==1表示tid即群id
typeint 0 表示文本消息,
1 表示图片,
2 表示语音,
3 表示视频,
4 表示地理位置信息,
6 表示文件,
100 自定义消息类型(特别注意,对于未对接易盾反垃圾功能的应用,该类型的消息不会提交反垃圾系统检测)
bodyString 请参考下方消息示例说明中对应消息的body字段,
最大长度5000字符,为一个JSON串
antispam String 对于对接了易盾反垃圾功能的应用,本消息是否需要指定经由易盾检测的内容(antispamCustom)。
true或false, 默认false。
只对消息类型为:100 自定义消息类型 的消息生效。
antispamCustom String 在antispam参数为true时生效。
自定义的反垃圾检测内容, JSON格式,长度限制同body字段,不能超过5000字符,要求antispamCustom格式如下:

{"type":1,"data":"custom content"}

字段说明:
1. type: 1:文本,2:图片。
2. data: 文本内容or图片地址。
option String 发消息时特殊指定的行为选项,JSON格式,可用于指定消息的漫游,存云端历史,发送方多端同步,推送,消息抄送等特殊行为;option中字段不填时表示默认值 ,option示例:

{"push":false,"roam":true,"history":false,"sendersync":true,"route":false,"badge":false,"needPushNick":true}

字段说明:
1. roam: 该消息是否需要漫游,默认true(需要app开通漫游消息功能);

2. history: 该消息是否存云端历史,默认true;

3. sendersync: 该消息是否需要发送方多端同步,默认true;

4. push: 该消息是否需要APNS推送或安卓系统通知栏推送,默认true;

5. route: 该消息是否需要抄送第三方;默认true (需要app开通消息抄送功能);

6. badge:该消息是否需要计入到未读计数中,默认true;
7. needPushNick: 推送文案是否需要带上昵称,不设置该参数时默认true;
8. persistent: 是否需要存离线消息,不设置该参数时默认true。
pushcontent String ios推送内容,不超过150字符,option选项中允许推送(push=true),此字段可以指定推送内容
payload String ios 推送对应的payload,必须是JSON,不能超过2k字符
ext String 开发者扩展字段,长度限制1024字符
forcepushlist String 发送群消息时的强推(@操作)用户列表,格式为JSONArray,如["accid1","accid2"]。若forcepushall为true,则forcepushlist为除发送者外的所有有效群成员
forcepushcontent String 发送群消息时,针对强推(@操作)列表forcepushlist中的用户,强制推送的内容
forcepushall String 发送群消息时,强推(@操作)列表是否为群里除发送者外的所有有效成员,true或false,默认为false
bid String 可选,反垃圾业务ID,实现“单条消息配置对应反垃圾”,若不填则使用原来的反垃圾配置
useYidun int 可选,单条消息是否使用易盾反垃圾,可选值为0。
0:(在开通易盾的情况下)不使用易盾反垃圾而是使用通用反垃圾,包括自定义消息。

若不填此字段,即在默认情况下,若应用开通了易盾反垃圾功能,则使用易盾反垃圾来进行垃圾消息的判断
markRead int 可选,群消息是否需要已读业务(仅对群消息有效),0:不需要,1:需要

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&ope=0&to=lisi&type=0&body={"msg":"hello"}' 'https://api.netease.im/nimserver/msg/sendMsg.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "data":{
        "msgid":1200510468189,
        "antispam":false
     }
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表


批量发送点对点普通消息

请求说明

POST https://api.netease.im/nimserver/msg/sendBatchMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

1.给用户发送点对点普通消息,包括文本,图片,语音,视频,地理位置和自定义消息。
2.最大限500人,只能针对个人,如果批量提供的帐号中有未注册的帐号,会提示并返回给用户。
3.此接口受频率控制,一个应用一分钟最多调用120次,超过会返回416状态码,并且被屏蔽一段时间;
具体消息参考下面描述。

参数说明

参数类型必须说明
fromAccid String 发送者accid,用户帐号,最大32字符,
必须保证一个APP内唯一
toAccids String ["aaa","bbb"](JSONArray对应的accid,如果解析出错,会报414错误),限500人
typeint 0 表示文本消息,
1 表示图片,
2 表示语音,
3 表示视频,
4 表示地理位置信息,
6 表示文件,
100 自定义消息类型
bodyString 请参考下方消息示例说明中对应消息的body字段,
最大长度5000字符,为一个json串
option String 发消息时特殊指定的行为选项,Json格式,可用于指定消息的漫游,存云端历史,发送方多端同步,推送,消息抄送等特殊行为;option中字段不填时表示默认值 option示例:

{"push":false,"roam":true,"history":false,"sendersync":true,"route":false,"badge":false,"needPushNick":true}

字段说明:
1. roam: 该消息是否需要漫游,默认true(需要app开通漫游消息功能);

2. history: 该消息是否存云端历史,默认true;

3. sendersync: 该消息是否需要发送方多端同步,默认true;

4. push: 该消息是否需要APNS推送或安卓系统通知栏推送,默认true;

5. route: 该消息是否需要抄送第三方;默认true (需要app开通消息抄送功能);

6. badge:该消息是否需要计入到未读计数中,默认true;
7. needPushNick: 推送文案是否需要带上昵称,不设置该参数时默认true;
8. persistent: 是否需要存离线消息,不设置该参数时默认true。
pushcontent String ios推送内容,不超过150字符,option选项中允许推送(push=true),此字段可以指定推送内容
payload String ios 推送对应的payload,必须是JSON,不能超过2k字符
ext String 开发者扩展字段,长度限制1024字符
bid String 可选,反垃圾业务ID,实现“单条消息配置对应反垃圾”,若不填则使用原来的反垃圾配置
useYidun int 可选,单条消息是否使用易盾反垃圾,可选值为0。
0:(在开通易盾的情况下)不使用易盾反垃圾而是使用通用反垃圾,包括自定义消息。

若不填此字段,即在默认情况下,若应用开通了易盾反垃圾功能,则使用易盾反垃圾来进行垃圾消息的判断

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'fromAccid=zhangsan&toAccids=["aaa","bbb"]&type=0&body={"msg":"hello"}' 'https://api.netease.im/nimserver/msg/sendBatchMsg.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "unregister":"["a","b"...]" //未注册的帐号
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表

消息格式示例:
1.文本消息

{
    "from":"test1",
    "ope":0,
    "to":"test2",
    "type":0,//文本消息类型
    "body":{
        "msg":"哈哈哈"//消息内容
    }
}

2 图片消息

{
    "from":"test1",
    "ope":0,
    "to":"test2",
    "type":1    //图片类型消息
    "body":{
        "name":"图片发送于2015-05-07 13:59",   //图片name
        "md5":"9894907e4ad9de4678091277509361f7",    //图片文件md5
        "url":"http://nimtest.nos.netease.com/cbc500e8-e19c-4b0f-834b-c32d4dc1075e",    //生成的url
                "ext":"jpg",    //图片后缀
        "w":6814,    //宽
        "h":2332,    //高
        "size":388245    //图片大小
    }
}

3 语音消息

{
    "from":"test1",
    "ope":0,
    "to":"test2",
    "type":2    //语音类型消息
    "body":{
        "dur":4551,        //语音持续时长ms
        "md5":"87b94a090dec5c58f242b7132a530a01",    //语音文件的md5值
        "url":"http://nimtest.nos.netease.com/a2583322-413d-4653-9a70-9cabdfc7f5f9",    //生成的url
        "ext":"aac",        //语音消息格式,只能是aac格式
        "size":16420        //语音文件大小
    }
}

4 视频消息

{
    "from":"test1",
    "ope":0,
    "to":"test2",
    "type":3    //视频类型消息
    "body":{
        "dur":8003,        //视频持续时长ms
        "md5":"da2cef3e5663ee9c3547ef5d127f7e3e",    //视频文件的md5值
        "url":"http://nimtest.nos.netease.com/21f34447-e9ac-4871-91ad-d9f03af20412",    //生成的url
        "w":360,    //宽
        "h":480,    //高
        "ext":"mp4",    //视频格式
        "size":16420    //视频文件大小
    }
}

5 发送地理位置消息

{
    "from":"test1",
    "ope":0,
    "to":"test2",
    "type":4    //地理位置类型消息
    "body":{
        "title":"中国 浙江省 杭州市 网商路 599号",    //地理位置title
        "lng":120.1908686708565,        // 经度
        "lat":30.18704515647036            // 纬度
    }
}

6 发送文件消息

{
    "from":"test1",
    "ope":0,
    "to":"test2",
    "type":6    //文件消息
    "body":{
        "name":"BlizzardReg.ttf",    //文件名
        "md5":"79d62a35fa3d34c367b20c66afc2a500", //文件MD5
        "url":"http://nimtest.nos.netease.com/08c9859d-183f-4daa-9904-d6cacb51c95b", //文件URL
        "ext":"ttf",    //文件后缀类型
        "size":91680    //大小
    }
}

7 发送第三方自定义消息

{
    "from":"test1",
    "ope":0,
    "to":"test2",
    "type":100    //第三方自定义消息
    //第三方定义的body体,json串
    "body":{
        "myKey":myValue    
    }
}

发送自定义系统通知

请求说明

POST https://api.netease.im/nimserver/msg/sendAttachMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

1.自定义系统通知区别于普通消息,方便开发者进行业务逻辑的通知;
2.目前支持两种类型:点对点类型和群类型(仅限高级群),根据msgType有所区别。

应用场景:如某个用户给另一个用户发送好友请求信息等,具体attach为请求消息体,第三方可以自行扩展,建议是json格式

参数说明


参数类型必须说明
fromString 发送者accid,用户帐号,最大32字符,APP内唯一
msgtypeint 0:点对点自定义通知,1:群消息自定义通知,其他返回414
toString msgtype==0是表示accid即用户id,msgtype==1表示tid即群id
attachString 自定义通知内容,第三方组装的字符串,建议是JSON串,最大长度4096字符
pushcontentString iOS推送内容,第三方自己组装的推送内容,不超过150字符
payloadString iOS推送对应的payload,必须是JSON,不能超过2k字符
soundString 如果有指定推送,此属性指定为客户端本地的声音文件名,长度不要超过30个字符,如果不指定,会使用默认声音
saveint 1表示只发在线,2表示会存离线,其他会报414错误。默认会存离线
option String 发消息时特殊指定的行为选项,Json格式,可用于指定消息计数等特殊行为;option中字段不填时表示默认值。
option示例:
{"badge":false,"needPushNick":false,"route":false}
字段说明:
1. badge:该消息是否需要计入到未读计数中,默认true;
2. needPushNick: 推送文案是否需要带上昵称,不设置该参数时默认false(ps:注意与sendMsg.action接口有别);
3. route: 该消息是否需要抄送第三方;默认true (需要app开通消息抄送功能)

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&msgtype=0&to=lisi&attach={"myattach":"test"}' 'https://api.netease.im/nimserver/msg/sendAttachMsg.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表


批量发送点对点自定义系统通知

请求说明

POST https://api.netease.im/nimserver/msg/sendBatchAttachMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

1.系统通知区别于普通消息,应用接收到直接交给上层处理,客户端可不做展示;
2.目前支持类型:点对点类型;
3.最大限500人,只能针对个人,如果批量提供的帐号中有未注册的帐号,会提示并返回给用户;
4.此接口受频率控制,一个应用一分钟最多调用120次,超过会返回416状态码,并且被屏蔽一段时间;

应用场景:如某个用户给另一个用户发送好友请求信息等,具体attach为请求消息体,第三方可以自行扩展,建议是json格式

参数说明


参数类型必须说明
fromAccid String 发送者accid,用户帐号,最大32字符,APP内唯一
toAccids String ["aaa","bbb"](JSONArray对应的accid,如果解析出错,会报414错误),最大限500人
attachString 自定义通知内容,第三方组装的字符串,建议是JSON串,最大长度4096字符
pushcontentString iOS推送内容,第三方自己组装的推送内容,不超过150字符
payloadString iOS推送对应的payload,必须是JSON,不能超过2k字符
soundString 如果有指定推送,此属性指定为客户端本地的声音文件名,长度不要超过30个字符,如果不指定,会使用默认声音
saveint 1表示只发在线,2表示会存离线,其他会报414错误。默认会存离线
option String 发消息时特殊指定的行为选项,Json格式,可用于指定消息计数等特殊行为;option中字段不填时表示默认值。
option示例:
{"badge":false,"needPushNick":false,"route":false}
字段说明:
1. badge:该消息是否需要计入到未读计数中,默认true;
2. needPushNick: 推送文案是否需要带上昵称,不设置该参数时默认false(ps:注意与sendBatchMsg.action接口有别)。
3. route: 该消息是否需要抄送第三方;默认true (需要app开通消息抄送功能)

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'fromAccid=zhangsan&toAccids=["aaa","bbb"]&attach={"myattach":"test"}' 'https://api.netease.im/nimserver/msg/sendBatchAttachMsg.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "unregister":"["a","b"...]" //未注册的帐号
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表


文件上传

请求说明

POST https://api.netease.im/nimserver/msg/upload.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

文件上传,字符流需要base64编码,最大15M。

参数说明

参数类型必须说明
contentString 字符流base64串(Base64.encode(bytes)) ,最大15M的字符流
typeString 上传文件类型
ishttpsString 返回的url是否需要为https的url,true或false,默认false

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'content=gwettwgsgssgs323f' 'https://api.netease.im/nimserver/msg/upload.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "url":"xxx"
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表


文件上传(multipart方式)

请求说明

POST https://api.netease.im/nimserver/msg/fileUpload.action HTTP/1.1
Content-Type:multipart/form-data;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

文件上传,最大15M

参数说明

参数类型必须说明
contentMultipart 最大15M的字符流
typeString 上传文件类型
ishttpsString 返回的url是否需要为https的url,true或false,默认false

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: multipart/form-data" -d 'content=gwettwgsgssgs323f' 'https://api.netease.im/nimserver/msg/fileUpload.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200,
  "url":"xxx"
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表


消息撤回

请求说明

POST https://api.netease.im/nimserver/msg/recall.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

消息撤回接口,可以撤回一定时间内的点对点与群消息

参数说明

参数类型必须说明
deleteMsgid String 要撤回消息的msgid
timetag long 要撤回消息的创建时间
type int 7:表示点对点消息撤回,8:表示群消息撤回,其它为参数错误
from String 发消息的accid
to String 如果点对点消息,为接收消息的accid,如果群消息,为对应群的tid
msg String 可以带上对应的描述
ignoreTime String 1表示忽略撤回时间检测,其它为非法参数,如果需要撤回时间检测,不填即可

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'deleteMsgid=10386192&timetag=1481528155741&type=7&from=t1&to=t4&msg=这是一条撤回消息'  'https://api.netease.im/nimserver/msg/recall.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
  "code":200
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表


发送广播消息

请求说明

POST https://api.netease.im/nimserver/msg/broadcastMsg.action HTTP/1.1
Content-Type:application/x-www-form-urlencoded;charset=utf-8

请求中Headers的设置请参考接口概述

接口描述

1、广播消息,可以对应用内的所有用户发送广播消息,广播消息目前暂不支持第三方推送(APNS、小米、华为等);
2、广播消息支持离线存储,并可以自定义设置离线存储的有效期,最多保留最近100条离线广播消息;
3、此接口受频率控制,一个应用一分钟最多调用10次,一天最多调用1000次,超过会返回416状态码;
4、该功能目前需申请开通,详情可咨询您的客户经理。

参数说明

参数类型必须说明
body String 广播消息内容,最大4096字符
from String 发送者accid, 用户帐号,最大长度32字符,必须保证一个APP内唯一
isOffline String 是否存离线,true或false,默认false
ttl int 存离线状态下的有效期,单位小时,默认7天
targetOs String 目标客户端,默认所有客户端,jsonArray,格式:["ios","aos","pc","web","mac"]

curl请求示例

curl -X POST -H "AppKey: go9dnk49bkd9jd9vmel1kglw0803mgq3" -H "Nonce: 4tgggergigwow323t23t" -H "CurTime: 1443592222" -H "CheckSum: 9e9db3b6c9abb2e1962cf3e6f7316fcc55583f86" -H "Content-Type: application/x-www-form-urlencoded" -d 'from=zhangsan&body=abc' 'https://api.netease.im/nimserver/msg/broadcastMsg.action'

返回说明

http 响应:json

"Content-Type": "application/json; charset=utf-8"
{
    "code": 200,
    "msg": {
        "expireTime": 1505502793520,
        "body": "abc",
        "createTime": 1505466793520,
        "isOffline": true,
        "broadcastId": 48174937359009,
        "targetOs": [
            "ios",
            "pc",
            "aos"
        ]
    }
}

主要的返回码

200、403、414、416、431、500

具体请参考code状态表