服务端
API 参考
圈组

发送消息

更新时间: 2024/06/11 14:58:05

网易云信服务端支持发送单聊消息和群聊消息,消息类型包括文本消息、图片消息、语音消息、视频消息、地理位置消息、文件消息、提示消息和自定义消息。各类消息及相关功能的更多介绍,请参考 消息概述

本文介绍如何使用服务端 API 发送一条单聊/群聊消息,以及不同类型消息的格式示例。

功能描述

向某个用户或者某个群组发送一条消息。

API 使用限制

单个应用默认最高调用频率:100 次/秒。如超限,将被屏蔽 10 秒。

请求 URL

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

请求 Body 参数

  • POST 请求中 Headers 的设置请参考 API 调用方式

  • POST 请求中 Body 的设置如下:

参数类型必填说明
from String 发送者的网易云信 IM 账号(accid),最大 32 字符,
必须保证一个应用内唯一
ope int 仅可传入 0 或 1,0:单聊消息,1:群消息(高级群),传入其他值都将报错(状态码:414)
to String 消息的接收方,ope 为 0 时需填入接收消息用户的的网易云信 IM 账号(accid),ope 为 1 时需填入接收消息的群的 ID(即 tid),最大 32 字符
type int
  • 0:文本消息
  • 1:图片消息
  • 2:语音消息
  • 3:视频消息
  • 4:地理位置消息
  • 6:文件消息
  • 10:提示消息
  • 100:自定义消息, 对于未开通 安全通(即易盾反垃圾)功能的应用,自定义消息不会过内容审核。
body String 消息内容,最大长度 5000 字符,JSON 格式,具体请参考 消息格式示例
msgDesc String 消息描述文本,对文本消息和提示消息以外的消息类型有效,最大长度 500 字符。该描述信息可用于云端历史消息关键词检索
antispam boolean 已开通 安全通 的前提下,是否对自定义消息的指定内容(antispamCustom)进行反垃圾检测,默认 false
该参数只对自定义消息(消息类型为:100)生效。
antispamCustom String 在 antispam 参数为 true 时生效
自定义的需要过反垃圾检测的内容, JSON 格式,长度限制同 body 字段,不能超过 5000 字符,要求 antispamCustom 格式如下:

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

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

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

    字段说明:
    • roam:该消息是否需要漫游,默认 true(需要已为应用开通漫游消息功能)
    • history:该消息是否存云端历史,默认 true
    • sendersync:该消息是否需要发送方多端同步,默认 true。如果发送方多端同时登录在线,则该消息发送后会同步到在线的其他端
    • push:该消息是否需要 APNs 推送或 Android 系统通知栏推送,默认 true
    • route:该消息是否需要抄送至指定的应用服务器。默认 true (需要已为应用 开通消息抄送功能);
    • badge:该消息是否需要计入到未读计数中,默认 true;
    • needPushNick:推送文案是否需要带上昵称,不设置该参数时默认 true
    • persistent:是否需要存离线消息,不设置该参数时默认 true。离线消息指不在线时其他人发来的消息。如果存离线,在用户下次登录时,IM 服务端会自动将离线期间暂存的离线消息自动下发到客户端 SDK。单聊场景下发最近 30 天内的最新的 5000 条离线消息,且每个会话最多 100 条最新的离线消息。群聊场景下发最近 30 天内的离线消息,且每个群聊会话最多下发 100 条最新的离线消息。
    • sessionUpdate:是否将本消息更新到服务端会话列表中本会话的最后一条消息(lastmsg),默认 true。
    pushcontent String 推送文案,最长 500 字符。option 选项中允许推送(push=true)后才能配置推送文案。pushcontent 如果不填,则使用默认文案。推送文案的显示规则如下:
    • pushcontent 不为空且 needPushNick=true,最终推送文案为:推送者昵称+pushcontent
    • pushcontent 不为空且 needPushNick=false,最终推送文案为:pushcontent
    • pushcontent 为空且 needPushNick=true,最终推送文案为:推送者昵称+默认文案
    • pushcontent 为空且 needPushNick=false,最终推送文案为:默认文案
    其中,根据消息类型,默认文案分为以下几种:
    • 文本消息默认文案:发来了一条消息
    • 地理位置默认文案:发来了一个地理位置
    • 语音消息默认文案:发来了一段语音
    • 视频消息默认文案:发来了一段视频
    • 文件消息默认文案:发来了一个文件
    • 图片消息默认文案:发来了一张图片
    • 语音聊天邀请消息默认文案:发来了语音聊天邀请
    • 视频聊天邀请消息默认文案:发来了视频聊天邀请
    payload String 推送对应的 payload,必须是 JSON 格式,不能超过 2048 字符。更多说明请参考 推送 payload 配置
    ext String 开发者扩展字段,必须是 JSON 格式,长度限制 1024 字符
    forcepushall boolean 发送群消息时,强推(@操作)列表是否为群里除发送者外的所有有效成员,默认为 false
    forcepushlist String 发送群消息时的强推(@操作)用户列表,格式为 JSONArray,如["accid1", "accid2"]。若 forcepushall 为 true,则 forcepushlist 为除发送者外的所有有效群成员 最多可强推 100 个用户,如果超过将报错(状态码:811)。
    forcepushcontent String 发送群消息时,针对强推列表 forcepushlist 中的用户,强制推送的内容,最大 500 字符
    useYidun int 单条消息(包括自定义消息)是否使用 安全通(即易盾反垃圾),只能传 0,传其他值相当于不传
    0:(在已开通安全通的情况下)本条消息不使用安全通检测
    若不填此字段,即在默认情况下,若应用开通了安全通,则使用安全通来进行反垃圾检测
    bid String 安全通业务 ID,可以指定当前消息过安全通某个检测策略。
    默认情况下网易云信控制后台会生成默认业务,开通安全通后,客户端不需要配置业务 ID 就能默认走该策略,若需要自定义检测策略,请 [提交工单](https://app.yunxin.163.com/global/service/ticket/create) 联系网易云信技术支持工程师进行配置,配置好后传入对应的安全通业务 ID,表示当前消息过安全通的指定检测策略。
    yidunAntiCheating String 透传给易盾的反作弊检测参数,格式为 JSON,长度限制 1024 字符(具体请参考 易盾的反垃圾防刷版专属字段
  • 反作弊相关的 email、phone、token、extension,抄送到 yidunAntiCheating。其他用户增值信息,抄送到 yidunAntiSpamExt。
  • yidunAntiSpamExt 传入的值默认覆盖 extension。
  • yidunAntiSpamExt String 透传给易盾的反垃含圈组版的检测参数,格式为 JSON,长度限制 1024 字符(具体请参考 易盾的反垃圾含圈组版用户可扩展字段反作弊相关的 email、phone、token、extension,抄送到 yidunAntiCheating。其他用户增值信息,抄送到 yidunAntiSpamExt。
    markRead int 群消息是否需要已读业务(仅对群消息有效),0:不需要,1:需要
    async boolean 是否异步,默认 false
    checkFriend boolean 是否为好友关系才能发送消息,默认为 false
    如需设置为好友关系才能发送消息,需先在 网易云信控制台 完成如下配置。
    单击展开查看具体配置
    1. 选择应用,进入应用详情界面。
    2. 在应用详情界面的IM 即时通讯区域,选择功能配置 > 基础功能 >单聊消息配置,将非好友关系是否允许发送消息设置为不允许
    subType int 自定义消息子类型,大于 0
    msgSenderNoSense int 发送方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息发送者无该消息的多端、漫游、历史记录等 可设置是否在历史记录查询结果中包含无感知消息,具体参考 单聊云端历史消息查询群聊云端历史消息查询
    msgReceiverNoSense int 接受方是否无感知。0-有感知,1-无感知。默认 0,若无感知,则消息接收者者无该消息的多端、漫游、历史记录等 可设置是否在历史记录查询结果中包含无感知消息,具体参考 单聊云端历史消息查询群聊云端历史消息查询
    env String 当前消息需要抄送到的环境的名称,对应您在 网易云信控制台 中配置的自定义抄送的环境名称(如下图),最大 32 个字符,

    robotAccount String 机器人账号,对应控制台提前设置好的机器人
    仅在群聊中有效,点对点聊天室中该字段会被忽略
    robotTopic String 机器人消息话题
    robotFunction String 机器人具体功能
    robotCustomContent String 机器人自定义内容

    若需要使用机器人消息功能,需要提前在 网易云信控制台 开通并设置机器人。

    返回参数

    参数 类型 说明
    data JSON 消息数据,具体见下表

    data 的成员参数说明如下:

    参数 类型 说明
    msgid Long 消息 ID 若配置了请求参数 optionpersistent 参数为 false(表示不需要保存离线消息),由于不保存数据库,所以会返回 "msgid":0。这并不影响 SDK 正常接收该消息。
    antispam boolean 消息是否被反垃圾(内容审核)拦截,如未被拦截则值为 false
    timetag Long 消息发送的时间戳

    示例

    cURL 请求示例

    cURLcurl -X POST -H "AppKey: go9dnk4**0803mgq3" -H "Nonce: 4tggge** 23t23t" -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'
    

    请求成功返回示例

    JSON"Content-Type": "application/json; charset=utf-8"
    {
      "code": 200,
      "data": {
        "msgid": 1200510468189,
        "timetag": 1545635366312, //消息发送的时间戳
        "antispam": false
      }
    }
    

    请求失败返回示例

    JSON"Content-Type": "application/json; charset=utf-8"
    {
        "code":414
        "desc":"check ope" // ope 参数不是 0 或 1
    }
    
    JSON"Content-Type": "application/json; charset=utf-8"
    {
        "code":423
        "desc":"account 'mute'." // 发送方账号被禁言
    }
    

    状态码

    该接口在 HTTPS Body 中返回请求的状态码,以下仅列出与接口业务相关的状态码。完整状态码请参考 状态码

    状态码 说明 处理建议
    200 请求成功 -
    811 强推(@功能)forcePushList 列表的用户数超过上限 100 减少强推列表中的用户数
    416 接口调用过于频繁 减少调用频率
    414 参数错误 根据提示信息,检查传入参数的格式和限制条件
    423 发送方账号被禁言 检查接收方的禁言名单里是否包含发送方
    422 发送方账号被禁用 检查账户是否可用
    403 导致请求失败的原因可能为:
    • 应用专属集群检查不通过
    • 应用不可用
    • 应用没有发送普通消息的权限
    • 发送方和接收方不是朋友关系
    -
    431 接口请求重复 -
    500 服务出错 -

    消息格式示例

    文本消息(type = 0)

    JSON{
      "msg": "哈哈哈"//消息内容
    }
    

    图片消息(type = 1)

    JSON{
      "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    //图片文件大小,单位为字节(Byte)
    }
    

    语音消息(type = 2)

    JSON{
      "dur":4551,        //语音持续时长 ms
      "md5":"87b94a090dec5c58f242b7132a530a01",    //语音文件的 md5 值,按照字节流加密
      "url":"http://nimtest.nos.netease.com/a2583322-413d-4653-9a70-9cabdfc7f5f9",    //生成的 url
      "ext":"aac",        //语音消息格式
      "size":16420        //语音文件大小,单位为字节(Byte)
    }
    

    视频消息(type = 3)

    JSON{
      "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    //视频文件大小,单位为字节(Byte)
    }
    

    地理位置消息(type = 4)

    JSON{
      "title":"中国 浙江省 杭州市 网商路 599 号",    //地理位置 title
      "lng":120.1908686708565,        // 经度
      "lat":30.18704515647036            // 纬度
    }
    

    文件消息(type = 6)

    JSON{
      "name":"BlizzardReg.ttf",    //文件名
      "md5":"79d62a35fa3d34c367b20c66afc2a500", //文件 MD5,按照字节流加密
      "url":"http://nimtest.nos.netease.com/08c9859d-183f-4daa-9904-d6cacb51c95b", //文件 URL
      "ext":"ttf",    //文件后缀类型
      "size":91680    //大小,单位为字节(Byte)
    }
    

    提示消息(type = 10)

    JSON{
      "msg": "您收到一份礼物"
    }
    

    自定义消息(type = 100)

    JSON//开发者自定义的 body,JSON 格式
    {
      "myKey":myValue
    }
    
    此文档是否对你有帮助?
    有帮助
    去反馈
    • 功能描述
    • API 使用限制
    • 请求 URL
    • 请求 Body 参数
    • 返回参数
    • 示例
    • cURL 请求示例
    • 请求成功返回示例
    • 请求失败返回示例
    • 状态码
    • 消息格式示例
    • 文本消息(type = 0)
    • 图片消息(type = 1)
    • 语音消息(type = 2)
    • 视频消息(type = 3)
    • 地理位置消息(type = 4)
    • 文件消息(type = 6)
    • 提示消息(type = 10)
    • 自定义消息(type = 100)