差别

这里会显示出您选择的修订版和当前版本之间的差别。

到此差别页面的链接

cs:300visitoraccess:wechat-callback [2017/09/22 07:12] (当前版本)
行 1: 行 1:
 +====== 微信回调模式集成(旧版) ======
 +
 +该集成方式主要针对有开发者的公众号集成,需要涉及到服务端程序的集成,因此需要首先将公众号设置为开发者模式,微信会将粉丝发送的信息及事件推送到设定的服务器地址上。
 +
 +注意:使用微信回调模式集成需要先开通环信即时通讯云的“实时消息回调”功能。
 +
 +回调模式集成包含如下步骤:
 +
 +  * [[cs:​300visitoraccess:​30wechat#​第_1_步_关联im系统和客服系统|第 1 步:关联IM系统和客服系统]]
 +  * [[cs:​300visitoraccess:​30wechat#​第_2_步_关联im系统和第三方服务器|第 2 步:关联IM系统和第三方服务器]]
 +  * [[cs:​300visitoraccess:​30wechat#​第_3_步_设置消息投递到环信|第 3 步:设置消息投递到环信]]
 +  * [[cs:​300visitoraccess:​30wechat#​第_4_步_设置客服回复消息给微信粉丝|第 4 步:设置客服回复消息给微信粉丝]]
 +  * [[cs:​300visitoraccess:​30wechat#​第_5_步_设置第三方服务器返回响应消息|第 5 步:设置第三方服务器返回响应消息]]
 +
 +==== 第 1 步:关联IM系统和客服系统 ====
 +
 +环信即时通讯云(IM)系统为移动客服系统与第三方服务器对接提供消息通道。采用回调模式集成时,需要先将IM系统与客服系统关联,具体方式为:在IM系统创建应用,将该应用绑定到客服系统中,形成一个APP关联。在移动客服系统,您可以快速创建一个这样的关联,并登录到IM后台管理该关联对应的应用。
 +
 +步骤如下:
 +
 +1. 打开[[http://​kefu.easemob.com/​mo/​login|环信移动客服]],进入“管理员模式 > 渠道管理 > 手机APP”。
 +
 +{{:​cs:​start-app5.png?​nolink|手机APP渠道}}
 +
 +2. 点击“添加APP关联”按钮,创建APP关联。支持两种方式:快速创建、关联IM账号。
 +
 +  * 快速创建:如果您还没有环信即时通讯云的账号,可以直接点击“快速创建”,系统会为您自动创建一个APP关联;
 +  * 关联IM账号:如果您已有环信即时通讯云的账号,并创建了应用,可以点击“去关联IM账号”,填写关联名称、AppKey、ClientId、ClientSecret、IM服务号、IM Password,手动将您的APP绑定到环信移动客服。
 +
 +{{:​cs:​releasenote:​admin-channel-app2.png?​nolink|添加APP关联}}
 +
 +创建APP关联后,可以查看关联的APP信息,包括关联名称、AppKey、ClientId、ClientSecret等。对于快速创建的关联,您还可以点击“直接登录IM关联后台”,查看更多相关信息。
 +
 +  * 关联名称:该关联在移动客服系统中的名称,可修改。
 +  * AppKey:应用的唯一标识,与“IM服务号”共同构成手机APP与移动客服之间的消息通道,不可修改。
 +  * ClientId和ClientSecret:自动生成,用于获取管理员token,不可修改。其中,管理员token用于使用REST API进行环信即时通讯云的服务端集成。
 +  * IM服务号:该应用下,IM用户的用户名,与“AppKey”共同构成手机APP与移动客服之间的消息通道,可以修改为其他IM用户的用户名(及对应的密码)。
 +
 +{{:​cs:​admin-channel-app3.png?​nolink|查看APP关联}}
 +
 +3. 点击“直接登录IM关联后台”,点击刚创建的应用,选择“IM用户→注册IM用户”,注册两个IM用户。例如:kefu001、kefu001_callback。
 +
 +{{:​cs:​300visitoraccess:​start-app9.png?​nolink|注册IM用户}}
 +
 +4. 返回移动客服系统,修改该“快速创建的关联”的基本信息,例如,将关联名称改为“微信公众号”,将IM服务号(及对应密码)改为“kefu001”及其密码,并保存。
 +
 +{{:​cs:​300visitoraccess:​start-app8.png?​nolink|修改关联的基本信息}}
 +==== 第 2 步:关联IM系统和第三方服务器 ====
 +
 +1. 使用APP的ClientId和ClientSecret获取APP管理员Token,并记录下来。
 +
 +详情请参考:[[http://​docs.easemob.com/​im/​100serverintegration/​20users#​获取_app_管理员_token|获取APP管理员token]]。
 +
 +2. 联系环信技术支持,开通实时消息回调。
 +
 +需要向环信提供如下配置信息:
 +
 +  * 回调地址URL:客户自己指定的第三方服务器地址,环信会把消息推送到该地址上。
 +  * AppKey:客户为微信公众号创建的APP的AppKey。
 +  * 回调ID:客户创建的第二个IM用户的用户名,如:上文中kefu001_callback。
 +  * token:上一步中获取的APP管理员token。
 +  * (可选)签名密钥:APP可以提供自己的密钥用来替换默认的密钥(默认情况下,回调密钥为123456,APP响应的密钥为654321)。
 +
 +详情请参考:[[http://​docs.easemob.com/​im/​000quickstart/​70rtmsgcallback|实时消息回调]]。
 +
 +注:开通实时消息回调后,代表IM系统与第三方服务器成功关联起来。
 +
 +==== 第 3 步:设置消息投递到环信 ====
 +
 +在开发者中心设置的第三方服务器接收到微信推送过来的粉丝消息后,根据需要有选择的将消息发送给环信指定的API,环信会将该粉丝消息发送给客服人员,坐席回复后环信会将消息推送给第三方提供的API(符合环信格式),由第三方将客服人员回复消息发送给终端的粉丝用户。
 +
 +投递到环信的消息格式及API使用方式可以参见[[im:​100serverintegration:​50messages|发送消息]],需要额外注意的只有消息格式的变化,需要在消息的扩展信息中添加上至少如下信息:
 +
 +目前支持文本消息、图片消息、语音消息类型。
 +
 +文本消息:
 +
 +<code json>
 +  { "​target_type":"​users",​
 +    "​target":​["​kefu001"​],​ //​在环信移动客服中设置的关联IM账号
 +    "​msg":​{
 +        "​type":"​txt",​
 +        "​msg":"​这里是微信粉丝发送给公众号的文本信息" ​
 +        },
 +    "​from":"​kefu001_callback",​ //​用于开通实时消息回调功能的IM账号
 +     "​ext"​ : {
 +         "​weichat":​{
 +             "​visitor":​{ ​
 +                    "​source"​ : "​weixin",​ //​来源渠道微信,固定值
 +                    "​msgId"​ : "​0c9a31ed-430b-4edf-9aaf-6029f2674534",​ //消息id
 +                    "​openid":​ "​oAGnbt89fTgfzOlybTmAh_7s3Z_g",​
 +                    "​mp":"​gh_9856dc55a1ea",​ //​微信公众号ID
 +                    "​userNickname":"​微信粉丝昵称",​
 +             }
 +         }
 +     }
 +  }
 +</​code>​
 +
 +图片消息:
 +
 +<code json>
 +  { "​target_type":"​users",​
 +    "​target":​["​kefu001"​],​ //​在环信移动客服中设置的关联IM账号
 +    "​msg":​{
 +        "​type":"​img",​ //固定值
 +        "​filename":"​name.jpg",​ //​任意指定
 +        "​secret":"​secretsecretsecretsecret", ​ //​任意指定,具体作用可见官网API文档
 +        "​url":"​https://​pic1.ooopic.com/​uploadfilepic/​sheji.jpg" ​ //​微信粉丝发送的图片url
 +        },
 +    "​from":"​kefu001_callback",​ //​用于开通实时消息回调功能的IM账号
 +     "​ext"​ : {
 +         "​weichat":​{
 +             "​visitor":​{ ​
 +                    "​source"​ : "​weixin", ​ //固定值
 +                    "​msgId"​ : "​0c9a31ed-430b-4edf-9aaf-6029f2674534", ​ //​微信消息id
 +                    "​openid":​ "​oAGnbt89fTgfzOlybTmAh_7s3Z_g",​
 +                    "​mp":"​gh_9856dc55a1ea",​ //​公众号ID
 +                    "​userNickname":"​微信粉丝昵称",​ //​粉丝昵称
 +             }
 +         }
 +     }
 +  }
 +</​code>​
 +
 +语音消息:
 +
 +<code json>
 +  { "​target_type":"​users",​
 +    "​target":​["​kefu001"​],​ //​在环信移动客服中设置的关联IM账号
 +    "​msg":​{
 +        "​type":"​audio",​ //固定值
 +        "​filename":"​xsxuzhl20150810T182551.amr",​ //​任意指定
 +        "​secret":"​secretsecretsecretsecret", ​ //​根据需要指定,具体作用可见官网API文档
 +        "​url":"​https://​a1.easemob.com/​easemob-demo/​chatdemoui/​chatfiles/​yyueywueywhdsh" ​ //​微信粉丝发送的语音url,这里以把音频文件上传到环信服务器为例
 +        },
 +    "​from":"​kefu001_callback",​ //​用于开通实时消息回调功能的IM账号
 +     "​ext"​ : {
 +         "​weichat":​{
 +             "​visitor":​{ ​
 +                    "​source"​ : "​weixin", ​ //固定值
 +                    "​msgId"​ : "​0c9a31ed-430b-4edf-9aaf-6029f2674534", ​ //​微信消息id
 +                    "​openid":​ "​oAGnbt89fTgfzOlybTmAh_7s3Z_g",​
 +                    "​mp":"​gh_9856dc55a1ea",​ //​公众号ID
 +                    "​userNickname":"​微信粉丝昵称",​ //​粉丝昵称
 +             }
 +         }
 +     }
 +  }
 +</​code>​
 +
 +说明:
 +
 +目前环信移动客服系统只支持播放MP3格式的语音消息。使用回调模式投递语音消息到环信时,可以使用以下两种方式:
 +
 +  * 使用环信服务器上的语音文件URL地址:从微信服务器下载语音文件,调用REST接口将该语音文件上传到环信服务器,由环信服务器自动转成MP3格式后,调用上述接口发送给客服系统;
 +  * 使用第三方服务器上的语音文件URL地址:从微信服务器下载语音文件,将该语音文件转成MP3格式后,保存在自己指定的服务器上,然后调用上述接口发送给客服系统。
 +
 +==== 第 4 步:设置客服回复消息给微信粉丝 ====
 +
 +公众号开发者提供回调服务给环信,环信会将客服人员回复的消息发送给提供的服务上,回调的地址集成时可联系环信处理。
 +
 +目前仅支持文本消息和图片消息类型。
 +
 +环信回调到消息内容如下:
 +
 +文本消息:
 +
 +<code json>
 +  {
 +    "​timestamp":​ 1438837020808,​
 +    "​chat_type":​ "​chat",​
 +    "​from":​ "​kefu001",​ //​在环信移动客服中设置的关联IM账号
 +    "​to":​ "​kefu001_callback",​ //​用于开通实时消息回调功能的IM账号
 +    "​payload":​ {
 +        "​bodies":​ [
 +            {
 +                "​msg":​ "​座席回复的消息",​
 +                "​type":​ "​txt"​
 +            }
 +        ],
 +        "​ext":​ {
 +            "​weichat":​ {
 +                "​visitor":​ {
 +                    "​mp":​ "​gh_9898dc96a1ea",​
 +                    "​openid":​ "​oAGnbt89fTgfzOlybTmAh_7s3Z_g",​
 +                    "​userNickname":​ "​微信粉丝昵称",​
 +                    "​source":​ "​weixin"​
 +                }
 +            }
 +        }
 +    },
 +    "​msg_id":​ "​91363492593926564",​
 +    "​callId":​ "​easemob-demo#​app_91363492593926564",​
 +    "​eventType":​ "​chat",​
 +    "​security":​ "​1d9b3a27574989826a034f02ece89161" ​ //​回调签名,见环信回调签名认证方式
 +  }
 +</​code>​
 +
 +图片消息:
 +
 +<code json>
 +  {
 +    "​timestamp":​ 1438837366089,​
 +    "​chat_type":​ "​chat",​
 +    "​from":​ "​kefu001",​ //​在环信移动客服中设置的关联IM账号
 +    "​to":​ "​kefu001_callback",​ //​用于开通实时消息回调功能的IM账号
 +    "​payload":​ {
 +        "​bodies":​ [
 +            {
 +                "​filename":​ "​8899a801f289.jpg",​
 +                "​size":​ {
 +                    "​width":​ 750,
 +                    "​height":​ 500
 +                },
 +                "​secret":​ "",​
 +                "​type":​ "​img",​
 +                "​url":​ "​https://​a1.easemob.com/​easemob-demo/​xuzhengli/​chatfiles/​5bd56cb0-3bf8-11e5-b668-431280c88f48" ​ //​坐席回复的图片地址
 +            }
 +        ],
 +        "​ext":​ {
 +            "​weichat":​ {
 +                "​visitor":​ {
 +                    "​mp":​ "​gh_9898dc86a1ea",​
 +                    "​openid":​ "​oAGnbt89fTgfzOlybTmAh_7s3Z_g",​
 +                    "​userNickname":​ "​微信粉丝昵称",​
 +                    "​source":​ "​weixin"​
 +                }
 +            }
 +        }
 +    },
 +    "​msg_id":​ "​91364975632712188",​
 +    "​callId":​ "​easemob-demo#​xuzhengli_91364975632712188",​
 +    "​eventType":​ "​chat",​
 +    "​security":​ "​27db399e77d4f422e50f5b529820ef64"​
 +  }
 +</​code>​
 + 
 +==== 第 5 步:设置第三方服务器返回响应消息 ====
 +
 +第三方服务器收到回调消息后,需要给环信服务器发送响应消息。响应内容不能超过1000个字符。
 +
 +响应消息示例:
 +
 +<code json>
 +{
 +    "​callId":"",//​与环信推送的一致
 +    "​accept":"​true",//​表明接受了此推送
 +    "​reason":"",//​可选,accept为false时使用
 +    "​security":""//​签名。格式如下:​ MD5(callId+约定的key+"​true"​),约定key为654321
 +}
 +</​code>​
 +
 +**注意:**第三方服务器收到回调消息后的响应内容不能超过1000个字符,如果连续发送超长消息会导致回调接口被封禁。接收回调消息的第三方服务器需要保证回调接口高并发下的可用性,如果接收回调消息时出现504错误等,页面会因为响应消息过长而停止回调。