公众号
取消
中文
中文
EN
取消
  • 服务端 API

    • # 发送客服消息

    调试工具

    接口应在服务器端调用，不可在前端（小程序、网页、APP等）直接调用，具体可参考接口调用指南

    接口英文名：sendCustomMessage

    本接口用于发送多种类型的客服消息，主要应用在有人工消息处理环节的场景。

    当用户和应用产生特定动作的交互时，微信将会把消息数据推送给开发者，开发者可以在一段时间内（目前为48小时）调用客服接口，通过POST一个JSON数据包来发送消息给普通用户。

    目前允许的动作列表如下（公众平台会根据运营情况更新该列表，不同动作触发后，允许的客服接口

    1. 用户发送信息
    2. 点击自定义菜单（仅有点击推事件、扫码推事件、扫码推事件且弹出“消息接收中”提示框这3种菜单类型是会触发客服接口的）
    3. 关注公众号
    4. 扫描二维码

    各场景的客服消息下发规则：

    场景 下发额度 额度有效期
    用户发送消息 5条 48小时
    点击自定义菜单 3条 1分钟
    关注公众号 3条 1分钟
    扫描二维码 3条 1分钟

    # 1. 调用方式

    # HTTPS 调用

    POST https://api.weixin.qq.com/cgi-bin/message/custom/send

    # 云调用

    • 本接口不支持云调用

    # 第三方调用

    • 本接口不支持第三方平台调用。

    # 2. 请求参数

    # 查询参数 Query String parameters

    无

    # 请求体 Request Payload

    参数名类型必填说明
    touserstring是用户的 OpenID
    msgtypestring是消息类型。text表示文本消息；image表示图片消息；link表示图文链接；miniprogrampage表示小程序卡片。
    textobject否文本消息，msgtype="text" 时必填
    imageobject否图片消息，msgtype="image" 时必填
    voiceobject否语音消息，msgtype="voice" 时必填
    videoobject否视频消息，msgtype="video" 时必填
    musicobject否音乐消息，msgtype="music" 时必填
    newsobject否图文消息（点击跳转到外链），msgtype="news" 时必填
    mpnewsobject否图文消息（点击跳转到图文消息页面），msgtype="mpnews" 时必填，图文消息条数限制在1条以内，注意，如果图文数超过1，则将会返回错误码45008。（草稿灰度完成后，此类型不再支持）
    mpnewsarticleobject否图文消息（点击跳转到图文消息页面），msgtype="mpnewsarticle" 时必填，使用通过 “发布” 系列接口得到的 article_id
    msgmenuobject否菜单消息，msgtype="msgmenu" 时必填
    wxcardobject否卡券信息，msgtype="wxcard"时必填
    miniprogrampageobject否小程序消息，msgtype="miniprogrampage"时必填
    customserviceobject否以某个客服账号来发消息

    # Body.text Object Payload

    文本消息，msgtype="text" 时必填

    参数名类型必填说明
    contentstring是文本内容，支持插入跳小程序的文字链，

    例如「文本内容点击跳小程序」

    说明： 1.data-miniprogram-appid 项，填写小程序appid，则表示该链接跳小程序； 2.data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数； 3.对于不支持data-miniprogram-appid 项的客户端版本，如果有herf项，则仍然保持跳href中的网页链接； 4.data-miniprogram-appid对应的小程序必须与公众号有绑定关系。

    # Body.image Object Payload

    图片消息，msgtype="image" 时必填

    参数名类型必填说明
    media_idstring是媒体ID，通过素材上传接口获得。

    # Body.voice Object Payload

    语音消息，msgtype="voice" 时必填

    参数名类型必填说明
    media_idstring是媒体ID，通过素材上传接口获得。

    # Body.video Object Payload

    视频消息，msgtype="video" 时必填

    参数名类型必填说明
    media_idstring是媒体ID，通过素材上传接口获得。
    thumb_media_idstring是缩略图媒体ID，通过素材上传接口获得。
    titlestring否视频标题
    descriptionstring否视频描述

    # Body.music Object Payload

    音乐消息，msgtype="music" 时必填

    参数名类型必填说明
    titlestring是音乐标题
    descriptionstring是音乐描述
    musicurlstring是音乐链接
    hqmusicurlstring否高质量音乐链接
    thumb_media_idstring是缩略图媒体ID

    # Body.news Object Payload

    图文消息（点击跳转到外链），msgtype="news" 时必填

    参数名类型必填说明
    articlesobjarray是图文消息条数限制在1条以内

    # Body.mpnews Object Payload

    图文消息（点击跳转到图文消息页面），msgtype="mpnews" 时必填，图文消息条数限制在1条以内，注意，如果图文数超过1，则将会返回错误码45008。（草稿灰度完成后，此类型不再支持）

    参数名类型必填说明
    media_idstring是素材ID，通过素材上传接口获得。

    # Body.mpnewsarticle Object Payload

    图文消息（点击跳转到图文消息页面），msgtype="mpnewsarticle" 时必填，使用通过 “发布” 系列接口得到的 article_id

    参数名类型必填说明
    article_idstring是发布文章ID

    # Body.msgmenu Object Payload

    菜单消息，msgtype="msgmenu" 时必填

    参数名类型必填说明
    head_contentstring否菜单描述
    listobjarray是菜单内容
    tail_contentstring否菜单结尾

    # Body.wxcard Object Payload

    卡券信息，msgtype="wxcard"时必填

    参数名类型必填说明
    card_idstring是卡券ID

    # Body.miniprogrampage Object Payload

    小程序消息，msgtype="miniprogrampage"时必填

    参数名类型必填说明
    titlestring是小程序卡片标题
    appidstring是小程序APPID
    pagepathstring是小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar
    thumb_media_idstring是小程序消息卡片的封面， image 类型的 media_id，通过素材上传图片文件获得，建议大小为 520*416

    # Body.customservice Object Payload

    以某个客服账号来发消息

    参数名类型必填说明
    kf_accountstring是客服账号

    # Body.news.articles(Array) Object Payload

    图文消息条数限制在1条以内

    参数名类型必填说明
    titlestring是消息标题
    descriptionstring是消息描述
    picurlstring是封面图片url
    urlstring是跳转url

    # Body.msgmenu.list(Array) Object Payload

    菜单内容

    参数名类型必填说明
    idstring是菜单值
    contentstring是菜单项

    # 3. 返回参数

    # 返回体 Response Payload

    参数名类型说明
    errcodenumber错误码
    errmsgstring错误描述

    # 4. 注意事项

    • 发送文本消息时，支持添加可跳转小程序的文字连接.
    • data-miniprogram-appid 项，填写小程序appid，则表示该链接跳转小程序
    • data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数；
    • 对于不支持 data-miniprogram-appid 项的客户端版本（6.5.16 以下），如果有 herf 项，则仍然保持跳 href 中的链接；
    • 小程序发带小程序文字链的文本消息，data-miniprogram-appid必须是该小程序的appid

    # 5. 代码示例

    # 5.1 发送文本消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":`文本内容<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>`
    },
    "customservice":{
         "kf_account": "test1@kftest"
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.2 发送图片消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"image",
    "image":
    {
      "media_id":"MEDIA_ID"
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.3 发送语音消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"voice",
    "voice":
    {
      "media_id":"MEDIA_ID"
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.4 发送视频消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"video",
    "video":
    {
      "media_id":"MEDIA_ID",
      "thumb_media_id":"MEDIA_ID",
      "title":"TITLE",
      "description":"DESCRIPTION"
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.5 发送音乐消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"music",
    "music":
    {
      "title":"MUSIC_TITLE",
      "description":"MUSIC_DESCRIPTION",
      "musicurl":"MUSIC_URL",
      "hqmusicurl":"HQ_MUSIC_URL",
      "thumb_media_id":"THUMB_MEDIA_ID" 
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.6 发送外链图文消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"news",
    "news":{
        "articles": [
         {
             "title":"Happy Day",
             "description":"Is Really A Happy Day",
             "url":"URL",
             "picurl":"PIC_URL"
         }
         ]
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.7 发送公众号图文消息（废弃）

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"mpnews",
    "mpnews":
    {
         "media_id":"MEDIA_ID"
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.8 发送公众号图文消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"mpnewsarticle",
    "mpnewsarticle": {
         "article_id":"ARTICLE_ID"
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.9 发送菜单消息

    请求示例

    {
  "touser": "OPENID",
  "msgtype": "msgmenu",
  "msgmenu": {
    "head_content": "您对本次服务是否满意呢? ",
    "list": [
      {
        "id": "101",
        "content": "满意"
      },
      {
        "id": "102",
        "content": "不满意"
      }
    ],
    "tail_content": "欢迎再次光临"
  }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.10 发送卡券消息

    请求示例

    {
  "touser":"OPENID", 
  "msgtype":"wxcard",
  "wxcard":
  {              
   "card_id":"123dsdajkasd231jhksad"        
   }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 5.11 发送小程序消息

    请求示例

    {
    "touser":"OPENID",
    "msgtype":"miniprogrampage",
    "miniprogrampage":
    {
        "title":"title",
        "appid":"appid",
        "pagepath":"pagepath",
        "thumb_media_id":"thumb_media_id"
    }
}

    返回示例

    {
  "errcode": 0,
  "errmsg": "ok"
}

    # 6. 错误码

    以下是本接口的错误码列表，其他错误码可参考 通用错误码

    错误码错误描述解决方案
    -1system error系统繁忙，此时请开发者稍候再试
    40001invalid credential  access_token isinvalid or not latest获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的公众号调用接口
    40013invalid appid不合法的 AppID ，请开发者检查 AppID 的正确性，避免异常字符，注意大小写
    70000为保护未成年人权益，该条消息发送失败

    # 7. 适用范围

    本接口在不同账号类型下的可调用情况：
    小程序公众号服务号小游戏
    ✔ 仅认证 仅认证 ✔
    • ✔：该账号可调用此接口
    • 仅认证：表示仅允许企业主体已认证账号调用，未认证或不支持认证的账号无法调用
    • 其他未明确声明的账号类型，如无特殊说明，均不可调用此接口；