微信公眾平臺技術文件：客服訊息

一、介面說明

當用戶和公眾號產生特定動作的互動時（具體動作列表請見下方說明），微信將會把訊息資料推送給開發者，開發者可以在一段時間內（目前修改為48小時）呼叫客服介面，通過POST一個JSON資料包來發送訊息給普通使用者。此介面主要用於客服等有人工訊息處理環節的功能，方便開發者為使用者提供更加優質的服務。

目前允許的動作列表如下（公眾平臺會根據運營情況更新該列表，不同動作觸發後，允許的客服介面下發訊息條數不同，下發條數達到上限後，會遇到錯誤返回碼，具體請見返回碼說明頁）：

1、使用者傳送資訊
2、點選自定義選單（僅有點選推事件、掃碼推事件、掃碼推事件且彈出“訊息接收中”提示框這3種菜單型別是會觸發客服介面的）
3、關注公眾號
4、掃描二維碼
5、支付成功
6、使用者維權
 

二、客服介面-發訊息

1 介面呼叫請求說明

http請求方式: POST

https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

2 傳送客服訊息

各訊息型別所需的JSON資料包如下：

（1）傳送文字訊息

{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":"Hello World"
    }
}

（2）傳送圖片訊息

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

（3）傳送語音訊息

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

（4）傳送視訊訊息

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

（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" 
    }
}

（6）傳送圖文訊息（點選跳轉到外鏈） 圖文訊息條數限制在8條以內，注意，如果圖文數超過8，則將會無響應。

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

（7）傳送圖文訊息（點選跳轉到圖文訊息頁面） 圖文訊息條數限制在8條以內，注意，如果圖文數超過8，則將會無響應。

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

（8）傳送卡券

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

特別注意客服訊息介面投放卡券僅支援非自定義Code碼和匯入code模式的卡券的卡券，詳情請見：是否自定義code碼。

請注意，如果需要以某個客服帳號來發訊息（在微信6.0.2及以上版本中顯示自定義頭像），則需在JSON資料包的後半部分加入customservice引數，例如傳送文字訊息則改為：

{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":"Hello World"
    },
    "customservice":
    {
         "kf_account": "[email protected]"
    }
}

3 請求引數說明

4 java介面開發

（1）Message客服介面訊息封裝物件

public class Message {

    private String touser;
    private String msgtype;
    private TextContent text;
    private MediaContent image;
    private MediaContent voice;
    private MediaContent video;
    private MusicContent music;
    private Articles news;

    public String getTouser() {
        return touser;
    }
    public void setTouser(String touser) {
        this.touser = touser;
    }
    public String getMsgtype() {
        return msgtype;
    }
    public void setMsgtype(String msgtype) {
        this.msgtype = msgtype;
    }
    public TextContent getText() {
        return text;
    }
    public void setText(TextContent text) {
        this.text = text;
    }
    public MediaContent getImage() {
        return image;
    }
    public void setImage(MediaContent image) {
        this.image = image;
    }
    public MediaContent getVoice() {
        return voice;
    }
    public void setVoice(MediaContent voice) {
        this.voice = voice;
    }
    public MediaContent getVideo() {
        return video;
    }
    public void setVideo(MediaContent video) {
        this.video = video;
    }
    public MusicContent getMusic() {
        return music;
    }
    public void setMusic(MusicContent music) {
        this.music = music;
    }
    public Articles getNews() {
        return news;
    }
    public void setNews(Articles news) {
        this.news = news;
    }
    @Override
    public String toString() {
        return "Message [touser=" + touser + ", msgtype=" + msgtype + ", text="
                + text + ", image=" + image + ", voice=" + voice + ", video="
                + video + ", music=" + music + ", news=" + news + "]";
    }
}

（2）TextContent文字訊息內容封裝物件

public class TextContent {

    private String content;

    public String getContent() {
        return content;
    }

    public void setContent(String content) {
        this.content = content;
    }
}

（3）MediaContent媒體ID封裝物件

public class MediaContent {

    private String media_id;

    public String getMedia_id() {
        return media_id;
    }
    public void setMedia_id(String media_id) {
        this.media_id = media_id;
    }
}

（4）MusicContent音樂訊息封裝物件

public class MusicContent {

    private String title;
    private String description;
    private String musicurl;
    private String hqmusicurl;
    private String thumb_media_id;

    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }
    public String getMusicurl() {
        return musicurl;
    }
    public void setMusicurl(String musicurl) {
        this.musicurl = musicurl;
    }
    public String getHqmusicurl() {
        return hqmusicurl;
    }
    public void setHqmusicurl(String hqmusicurl) {
        this.hqmusicurl = hqmusicurl;
    }
    public String getThumb_media_id() {
        return thumb_media_id;
    }
    public void setThumb_media_id(String thumb_media_id) {
        this.thumb_media_id = thumb_media_id;
    }
}

（5）Articles圖文集合封裝物件

public class Articles {

    private Article[] articles;

    public Article[] getArticles() {
        return articles;
    }
    public void setArticles(Article[] articles) {
        this.articles = articles;
    }
}

（6）Article圖文訊息封裝物件

public class Article {
    private String title;
    private String description;
    private String url;
    private String picurl;
    private String thumb_media_id;
    private String author;  
    private String content_source_url;  
    private String content; 
    private String digest;  
    private Integer show_cover_pic;

    public String getTitle() {
        return title;
    }
    public void setTitle(String title) {
        this.title = title;
    }
    public String getDescription() {
        return description;
    }
    public void setDescription(String description) {
        this.description = description;
    }
    public String getUrl() {
        return url;
    }
    public void setUrl(String url) {
        this.url = url;
    }
    public String getPicurl() {
        return picurl;
    }
    public void setPicurl(String picurl) {
        this.picurl = picurl;
    }
    public String getThumb_media_id() {
        return thumb_media_id;
    }
    public void setThumb_media_id(String thumb_media_id) {
        this.thumb_media_id = thumb_media_id;
    }
    public String getAuthor() {
        return author;
    }
    public void setAuthor(String author) {
        this.author = author;
    }
    public String getContent_source_url() {
        return content_source_url;
    }
    public void setContent_source_url(String content_source_url) {
        this.content_source_url = content_source_url;
    }
    public String getContent() {
        return content;
    }
    public void setContent(String content) {
        this.content = content;
    }
    public String getDigest() {
        return digest;
    }
    public void setDigest(String digest) {
        this.digest = digest;
    }
    public Integer getShow_cover_pic() {
        return show_cover_pic;
    }
    public void setShow_cover_pic(Integer show_cover_pic) {
        this.show_cover_pic = show_cover_pic;
    }
}

（7）客服訊息請求介面

public class CrmSendMessageService{

    private RestTemplate restTemplate ; 

    private String serviceHost = "https://api.weixin.qq.com";

    public CrmSendMessageServiceImpl() {
        restTemplate = RestTemplateFactory.makeRestTemplate();
    }

    @Override
    public WeixinResponse sendMessage(String accessToken, Message message) {
        WeixinResponse weixinResponse = null;
        String url = new StringBuffer(serviceHost).append("/cgi-bin/message/custom/send?access_token=")
                .append(accessToken).toString();
        weixinResponse =  restTemplate.postForObject(url, message, WeixinResponse.class);
        return weixinResponse;
    }

}

（8）WeixinResponse客服訊息介面返回物件

public class WeixinResponse {
    private String msgid;
    private String code;
    private int errcode;
    private String errmsg;

    public String getMsgid() {
        return msgid;
    }
    public void setMsgid(String msgid) {
        this.msgid = msgid;
    }
    public int getErrcode() {
        return errcode;
    }
    public void setErrcode(int errcode) {
        this.errcode = errcode;
    }
    public String getErrmsg() {
        return errmsg;
    }
    public void setErrmsg(String errmsg) {
        this.errmsg = errmsg;
    }
    public String getCode() {
        return code;
    }
    public void setCode(String code) {
        this.code = code;
    }   
}

5 介面例項開發

/**
 * 傳送客服訊息
 * @param openId 要發給的使用者
 * @param accessToken 微信公眾號token
 * @param weixinAppId 微信公眾號APPID
 */
private void sendCustomMessage(String openId,String accessToken,String weixinAppId){
        try {
            RestTemplate rest = new RestTemplate();
            String postUrl = "https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=" + accessToken;
            //推送圖文訊息
            Message message = new Message();
            message.setTouser(openId);//普通使用者openid
            message.setMsgtype("news");//圖文訊息（點選跳轉到外鏈）為news
            Articles news = new Articles();
            Article article = new Article();
            article.setDescription("客服訊息圖文描述");//圖文訊息/視訊訊息/音樂訊息的描述
                                       article.setPicurl("http://mmbiz.qpic.cn/mmbiz_jpg/CDW6Ticice130g6RcXCkNNDWic4dEaAHQDia2OG5atHBqSvsPuCfuqoyeeLWENia4ciaKt3KHWQ9t2LRPDpUo5AkOyyA/0");//圖文訊息的圖片連結，支援JPG、PNG格式，較好的效果為大圖640*320，小圖80*80
            article.setTitle("客服訊息圖文標題");//圖文訊息/視訊訊息/音樂訊息的標題
            //圖文推送連結
            String url="https://www.baidu.com";
            article.setUrl(url);//圖文訊息被點選後跳轉的連結
            Article[] articles = {article};
            news.setArticles(articles);
            message.setNews(news);
            int i=1;
            while(i<=3){//迴圈傳送3次
                WeixinResponse response = rest.postForObject(postUrl, message, WeixinResponse.class, new HashMap<String,String>());
                LOG.info("傳送客服訊息返回資訊:"+response.toString());
                if(response.getErrcode()==0){//傳送成功-退出迴圈傳送
                    i=4;
                    break;
                }else{
                    i++;//傳送失敗-繼續迴圈傳送
                }
            }
        } catch (Exception e) {
            LOG.error("傳送客服訊息失敗,openId="+openId,e);
        }
    }

6 客服介面圖文推送上傳圖片

在傳送圖文訊息時，我們需要新增圖片的地址，介紹一個好方法。
（1）進入微信公眾平臺介面除錯工具
https://mp.weixin.qq.com/debug
（2）選擇型別和列表
介面型別：基礎支援
介面列表：上傳logo介面/media/uploadimg

新增access_token，選擇型別是image，最後選擇檔案
注：新增視訊、音樂是一樣的
（3）最後就會生成圖片的url

（4）在瀏覽器訪問url即可看見生成的圖片