公众服务

    简介

    融云公众服务包括:应用公众服务和公众服务平台,它为应用开发者和公众账号运营者提供连接服务。

    公众服务平台: 在 App 开发者和公众帐号运营者之间建立对接平台。App 开发者可以通过平台引入公众服务资源,帮助 App 快速覆盖用户需求。公众帐号持有者通过平台有机会向所有集成融云 SDK 的 App 提供服务,进而获得更加精准、丰富的受众渠道。

    应用公众服务: 为 App 开发者提供 App 内建公众服务能力。

    公众服务平台开发指南

    注册公众服务

    接入融云公众服务,开发者需要前往融云公众服务注册开发者创建公众号,注册时需提供真实身份信息。融云对提交信息审核成功后,公众号创建成功,即可进行消息推送、回复、粉丝管理等操作。

    请注意,如开发者想通过自已的 URL 地址接收用户信息,需要在开发者中心开启开发者模式后,按以下方式进行接入。

    接入前准备

    获取 RC-PSKey / Secret

    创建公众号后会为每个开发者分配对应的 RC-PSKey / Secret , 登录融云公众服务官网后,打开融云公众服务 - 开发者中心页面,获取 RC-PSKey/Secret。

    RC-PSKey 公众号 Key 唯一标识,是用于验证 API 接入合法性的。

    Secret API 接口密钥,在调用 API 接口生成数据签名时需要用到,可重置重新获取,重置后原密钥失效,需使用新密钥重新生成签名调用 API 接口,建议谨慎操作刷新密钥功能。

    image
    获取 RC-PSKey / Secret 位置

    配置消息接收地址

    接入融云公众服务前,开发者需要完成消息接收 URL 配置,公众号接收用户发送的消息以及开发者需要的事件推送,融云会将消息数据包 POST 到开发者设置的消息接收 URL 上。

    image
    消息接收 URL 位置
    消息接收 URL 必须以 http:// 开头,目前只支持 80 端口。

    API 接口签名规则

    API 调用签名规则

    本文档中所有请求融云服务端 API 接口的请求均使用此规则校验,以下不再重复说明。

    每次请求 API 接口时,均需要提供 4 个 HTTP Request Header,具体如下:

    名称 类型 说明
    RC-PSKey String 融云公众服务分配的 Key。
    RC-Nonce String 随机数,无长度限制。
    RC-Timestamp String 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到当前时间(北京时间)的毫秒数。(请严格参照此执行,服务器端会校验此信息)
    RC-Signature String 数据签名。

    RC-Signature (数据签名)计算方法:

    1. 将系统分配的 secret、以及 RC-Nonce、RC-Timestamp 三个参数进行字典序排序
    2. 将三个参数字符串拼接成一个字符串进行 SHA1 加密

    API 接收签名规则

    融云服务器向公众帐号服务器推送数据时会添加 3 个 GET 请求参数(在 URL 上添加的参数),具体如下:

    名称 类型 说明
    rc-nonce String 随机数,无长度限制。
    rc-timestamp String 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到当前时间(北京时间)的毫秒数。
    rc-signature String 数据签名。

    rc-signature (数据签名)计算方法:

    1. 将系统分配的 secret、以及 rc-nonce、rc-timestamp 三个参数进行字典序排序
    2. 将三个参数字符串拼接成一个字符串进行 SHA1 加密

    接收消息

    当 App 内用户向公众帐号发消息时,融云服务器将 POST 消息数据包(XML格式)到开发者配置的消息接收 URL 上。

    • 融云服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。
    • 关于重试的消息排重,推荐使用 MsgID 排重。
    • 假如开发者服务器无法保证在五秒内处理并回复,可以直接回复空字符串,融云服务器不会对此作任何处理,且不会发起重试。

    http 请求方式:POST

    请求接收方式:参见 API 接收签名规则

    文本消息格式

    XML 格式

    <xml>
     <ToUserName><![CDATA[toUserName]]></ToUserName>
     <FromUserName><![CDATA[fromUserName]]></FromUserName>
     <CreateTime>134223445860</CreateTime>
     <MsgType><![CDATA[text]]></MsgType>
     <Content><![CDATA[content]]></Content>
     <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 text
    Content 文本消息内容
    MsgId 消息 Id

    图片消息格式

    XML 格式

    <xml>
     <ToUserName><![CDATA[toUserName]]></ToUserName>
     <FromUserName><![CDATA[fromUserName]]></FromUserName>
     <CreateTime>134223445860</CreateTime>
     <MsgType><![CDATA[image]]></MsgType>
     <PicUrl><![CDATA[this is a url]]></PicUrl>
     <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 image
    PicUrl 图片链接
    MsgId 消息 Id

    语音消息格式

    XML 格式

    <xml>
     <ToUserName><![CDATA[toUserName]]></ToUserName>
     <FromUserName><![CDATA[fromUserName]]></FromUserName>
     <CreateTime>134223445860</CreateTime>
     <MsgType><![CDATA[voice]]></MsgType>
     <VoiceUrl><![CDATA[this is url]]></VoiceUrl>
     <Format><![CDATA[AMR]]></Format>
     <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 voice
    VoiceUrl 语音链接
    Format 语音格式,目前支持 AMR 格式
    MsgId 消息 Id

    位置消息格式

    XML 格式

    <xml>
     <ToUserName><![CDATA[toUserName]]></ToUserName>
     <FromUserName><![CDATA[fromUserName]]></FromUserName>
     <CreateTime>134223445860</CreateTime>
     <MsgType><![CDATA[location]]></MsgType>
     <Location_X>15.501</Location_X>
     <Location_Y>142.324</Location_Y>
     <Label><![CDATA[POI信息]]></Label>
     <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 location
    Location_X 纬度
    Location_Y 经度
    Label 地理位置信息
    MsgId 消息 Id

    图文消息格式

    XML 格式

     <xml>
      <ToUserName><![CDATA[toUserName]]></ToUserName>
      <FromUserName><![CDATA[fromUserName]]></FromUserName>
      <CreateTime>134223445860</CreateTime>
      <MsgType><![CDATA[imgtxt]]></MsgType>
      <Title><![CDATA[title]]></Title>
      <Description><![CDATA[description]]></Description>
      <PicUrl><![CDATA[picUrl]]></PicUrl>
      <Url><![CDATA[url]]></Url>
      <MsgId>msgId</MsgID>
     </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 imgtxt
    Title 消息的标题
    Description 消息文本内容
    PicUrl 图片地址
    Url 跳转的地址
    MsgId 消息 Id

    事件推送

    关注事件

    用户在关注公众号时,会把这个事件消息推送到开发者设置的消息接收 URL 上。方便开发者给用户下发消息或做帐号的解绑操作。

    • 融云服务器在 五 秒内收不到响应会断掉连接,并且重新发起请求,总共重试 三 次。
    • 假如开发者服务器无法保证在 五 秒内处理并回复,可以直接回复空字符串,融云服务器不会对此作任何处理,且不会发起重试。

    XML 消息格式

    <xml>
     <ToUserName><![CDATA[toUserName]]></ToUserName>
     <FromUserName><![CDATA[fromUserName]]></FromUserName>
     <CreateTime>134223445860</CreateTime>
     <MsgType><![CDATA[event]]></MsgType>
     <Event><![CDATA[subscribe]]></Event>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此务为event
    Event 事件信息,此处为subscribe

    取消关注事件

    用户在关注/取消关注公众号时,会把这个事件消息推送到开发者设置的消息接收 URL 上。方便开发者给用户下发消息或做帐号的解绑操作。

    • 融云服务器在 五 秒内收不到响应会断掉连接,并且重新发起请求,总共重试 三 次。
    • 假如开发者服务器无法保证在 五 秒内处理并回复,可以直接回复空字符串,融云服务器不会对此作任何处理,且不会发起重试。

    XML 消息格式

    <xml>
     <ToUserName><![CDATA[toUserName]]></ToUserName>
     <FromUserName><![CDATA[fromUserName]]></FromUserName>
     <CreateTime>134223445860</CreateTime>
     <MsgType><![CDATA[event]]></MsgType>
     <Event><![CDATA[unsubscribe]]></Event>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此务为event
    Event 事件信息,此处为unsubscribe

    发送消息

    用户向公众号发送消息后,公众号会向用户发送回复消息,目前融云公众服务 API 支持文本、图片、语音、图文等消息类型。

    请注意,在发送多媒体(图片、语音)消息时需要预先上传多媒体文件到融云服务器。

    方法名:/message/send.json

    调用方式:参见 API 调用签名规则

    URL:https://api.ps.ronghub.com/message/send.json

    请注意:发送请求时 HTTP Request Header 中的 Content-Type 类型必须为 application/json

    文本消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdl21
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
        "touser":"321@qwdqdwdw",
        "msgtype":"text",
        "text":
        {
             "content":"Hello"
        }
     }
    

    表单参数:

    名称 是否必须 说明
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:sdfxl@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 text。
    content 消息内容,最大长度为 2000 个字节。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    图片消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdl21
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
        "touser":"321@qwdqdwdw",
        "msgtype":"image",
        "image":
        {
             "media_id":"123434343443"
        }
     }
    

    表单参数:

    名称 是否必须 说明
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:sdfxl@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 image。
    media_id 图片 Id,调用多媒体上传接口上传图片后获得。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    语音消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdl21
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
        "touser":"321@qwdqdwdw",
        "msgtype":"voice",
        "voice":
        {
             "media_id":"123434343443"
        }
    }
    

    表单参数:

    名称 是否必须 说明
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:sdfxl@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 voice。
    media_id 语音 Id,调用多媒体上传接口上传语音后获得。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    图文消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdl21
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
        "touser":"321@qwdqdwdw",
        "msgtype":"news",
        "news":
        {
            "articles": [
             {
                 "title":"haha ",
                 "description":" hahahaahhaha",
                 "url":"URL",
                 "picurl":"PIC_URL"
             },
             {
                 "title":"lala",
                 "description":" lalalalala",
                 "url":"URL",
                 "picurl":"PIC_URL"
             }
             ]
        }
    }
    

    表单参数:

    名称 是否必须 说明
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:sdfxl@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 news。
    articles 图文消息,一个图文消息最少为 1 条,最多为 10 条图文。
    title 图文消息的标题。
    description 图文消息的描述,描述内容不超过 1000 个汉字( 1 个汉字等于 2 个字符)。
    url 图文消息被点击后跳转的链接。
    picurl 图文消息的图片链接,支持JPG。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    群发消息

    公众号需要向全部关注用户发送消息时,融云公众服务为公众号提供了每天 一 条的群发权限,按自然天计算,暂时只支持向全部关注用户发送消息。

    请注意,在群发多媒体消息时需要预先上传多媒体文件到融云服务器。

    方法名:/message/sendall.json

    调用方式:参见 API 调用签名规则

    URL:https://api.ps.ronghub.com/message/sendall.json

    请注意:发送请求时 HTTP Request Header 中的 Content-Type 类型必须为 application/json

    群发文本消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdl21
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "filter":{
          "is_to_all": true
       },
       "text":{
          "content":"CONTENT"
       },
       "msgtype":"text"
    }
    

    表单参数:

    名称 是否必须 说明
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持 true,默认为 true。
    content 消息内容,最大长度为 2000 个字节。
    msgtype 消息类型,图文消息为 mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 text。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    群发图文消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdlx1
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "filter":{
          "is_to_all":true
       },
       "mpnews":{
          "media_id":"123dsdajkasd231jhksad"
       },
       "msgtype":"mpnews"
    }
    

    表单参数:

    名称 是否必须 说明
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持 true,默认为 true。
    msgtype 消息类型,图文消息为mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 mpnews。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    注意图文消息的 media_id 需要通过上传图文消息素材方法来得到。

    群发语音消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdlx2
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "filter":{
          "is_to_all": true
       },
       "voice":{
          "media_id":"123dsdajkasd231jhksad"
       },
       "msgtype":"voice"
    }
    

    表单参数:

    名称 是否必须 说明
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持true,默认为 true。
    media_id 用于群发的消息的 media_id。
    msgtype 消息类型,图文消息为 mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 voice。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    注意此处 media_id 需通过上传多媒体文件方法来得到。

    群发图片消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-PSKey: uwd1c0sxdl21
    RC-Timestamp: 1408706337
    RC-Nonce: 14314
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "filter":{
          "is_to_all": true
       },
       "image":{
          "media_id":"123dsdajkasd231jhksad"
       },
       "msgtype":"image"
    }
    

    表单参数:

    名称 是否必须 说明
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持 true,默认为 true。
    media_id 用于群发的消息的 media_id。
    msgtype 消息类型,图文消息为 mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 image。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    注意此处 media_id 需通过上传多媒体文件方法来得到。

    素材管理

    公众号在发送消息时经常用到一些媒体素材,需要开发者在上传多媒体文件后,通过返回的 media_id 进行发送。

    上传多媒体文件

    http 请求方式: POST

    调用方式:参见 API 调用签名规则,不同点是将放进 http header 中的参数放到 URL 后面,如下:

    http://api.ps.ronghub.com/media/upload?type=TYPE&RC-PSKey=xxx&RC-Nonce=adbc134sdf&RC-Timestamp=1234556566&RC-Signature=123421dsfsvc03u4asdflvjdsdfsdf
    

    表单参数:

    名称 是否必须 说明
    type 媒体文件类型,有图片(image)、语音(voice)、缩略图(thumb)。

    上传的多媒体文件以表单文件方式上传,格式和大小限制如下:

    • 图片(image): 2 M,支持 JPG、PNG 格式。
    • 缩略图(thumb) : 20 K,支持JPG、PNG格式。
    • 语音(voice):60 k,播放长度不超过 60s,目前支持 AMR 格式。

    Java 代码示例:

    String urlStr = "http://api.ps.ronghub.com/media/upload?type=image&RC-PSKey=xxx&RC-Nonce=adbc134sdf&RC-Timestamp=1234556566&RC-Signature=123421dsfsvc03u4asdflvjdsdfsdf";
    
            //
            HttpClient httpclient = new DefaultHttpClient();
            // 请求处理页面
             HttpPost httppost = new HttpPost(urlStr);
    
            // 创建待处理的文件
            FileBody file = new FileBody(new File(filepath));
    
            // 对请求的表单域进行填充
            MultipartEntity reqEntity = new MultipartEntity();
            reqEntity.addPart("file", file);
    
            // 设置请求
            httppost.setEntity(reqEntity);
            // 执行
            HttpResponse response = httpclient.execute(httppost);
    
            HttpEntity httpEntity = response.getEntity();
            BufferedReader br = new BufferedReader(new InputStreamReader(httpEntity.getContent(), "UTF-8"));
            StringBuffer backData = new StringBuffer();
            String line = null;
            while ((line = br.readLine()) != null) {
                backData.append(line);
            }
            System.out.println(backData.toString());
    

    返回值

    正常示例:

    {
       "type":"image",
       "media_id":"12344343252",
       "created_at":123456789
    }
    

    错误示例:

    {"errcode":1003,"errmsg":"invalid type "}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    上传图文消息素材

    http 请求方式: POST

    调用方式:参见 API 调用签名规则,不同点是将放进 http header 中的参数放到 URL 后面,如下:

    http://api.ps.ronghub.com/media/uploadnews?RC-PSKey=xxx&RC-Nonce=adbc134sdf&RC-Timestamp=1234556566&RC-Signature=123421dsfsvc03u4asdflvjdsdfsdf
    

    POST 数据示例:

    {
       "articles": [
             {
            "thumb_media_id":"sdflsdfjxcl324324sdfsdlfsd",
            "author":"yyuy",
                  "title":"Happy ",
                  "content_source_url":"www.rongcloud.com",
                  "content":"content",
                  "digest":"digest",
            "show_cover_pic":"1"
             },
             {
            "thumb_media_id":" sdflsdfjxcl324324sdfsdlfsdasdfsdf",
            "author":"yy",
                  "title":"Happy",
                  "content_source_url":"www.rongcloud.com",
                  "content":"content",
                  "digest":"digest",
            "show_cover_pic":"0"
             }
       ]
    }
    

    表单参数:

    名称 是否必须 说明
    articles 图文消息,一个图文消息支持 1 到 10 条图文。
    thumb_media_id 图文消息缩略图的 media_id,可以在基础支持-上传多媒体文件接口中获得。
    author 图文消息的作者。
    title 图文消息的标题。
    content_source_url 在图文消息页面点击“阅读原文”后链接的页面。
    content 图文消息页面的内容,支持 HTML 标签。
    digest 图文消息的描述。
    show_cover_pic 是否显示封面,1 为显示,0 为不显示。

    返回值

    {
       "type":"news",
       "media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ",
       "created_at":1391857799
    }
    

    表单参数:

    名称 说明
    type 媒体文件类型, news,即图文消息。
    media_id 媒体文件/图文消息上传后获取的唯一标识。
    created_at 媒体文件上传时间。

    应用公众服务开发指南

    创建应用公众服务

    接入融云公众服务,开发者需前往 融云官方网站 注册创建融云开发者帐号。在开发者后台的公众服务-应用公众服务中创建应用公众号。

    开发前准备

    获取 App-Key / Secret

    您创建完应用后,最需要了解的就是 App-Key / Secret,它们是融云 SDK 连接服务器所必须的标识,每一个 App 对应一套 App Key / Secret。针对开发者的生产环境和开发环境,我们提供两套 App Key / Secret,您在应用最终上线前,使用开发环境即可,两套环境的功能完全一致。

    Secret API 接口密钥,在调用 API 接口生成数据签名时需要用到,可重置重新获取,重置后原密钥失效,需使用新密钥重新生成签名调用 API 接口,建议谨慎操作刷新密钥功能。

    image
    App Key / Secret 位置

    配置消息接收地址

    接入融云应用公众服务前,开发者需要完成消息路由配置,公众号接收用户发送的消息以及开发者需要的事件推送,融云会将消息数据包 POST 到开发者设置的消息接收 URL 上。

    消息接收 URL 必须以 http:// 开头,目前只支持 80 端口。

    接口签名规则

    API 调用签名规则

    本文档中所有请求融云服务端 API 接口的请求均使用此规则校验,以下不再重复说明。

    每次请求 API 接口时,均需要提供 4 个 HTTP Request Header,具体如下:

    名称 类型 说明
    RC-App-Key String 开发者平台分配的 App Key。
    RC-Nonce String 随机数,无长度限制。
    RC-Timestamp String 时间戳,从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到当前时间(北京时间)的毫秒数。(请严格参照此执行,服务器端会校验此信息)
    RC-Signature String 数据签名。

    RC-Signature (数据签名)计算方法:将系统分配的 App Secret、RC-Nonce (随机数)、RC-Timestamp (时间戳)三个字符串按先后顺序拼接成一个字符串并进行 SHA1 哈希计算。如果调用的数据签名验证失败,接口调用会返回 HTTP 状态码 401。其他状态码请参见状态码表

    签名生成代码示例

    PHP 语言的代码示例:

    // 重置随机数种子。
    srand((double)microtime()*1000000);
    
    $appSecret = 'Y1W2MeFwwwRxa0'; // 开发者平台分配的 App Secret。
    $nonce = rand(); // 获取随机数。
    $timestamp = time(); // 获取时间戳。
    
    $signature = sha1($appSecret.$nonce.$timestamp);
    

    HTTP 请求示例:

    POST /user/getToken.json HTTP/1.1
    Host: api.cn.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/x-www-form-urlencoded
    Content-Length: 78
    
    userId=jlk456j5&name=Ironman&portraitUri=http%3A%2F%2Fabc.com%2Fmyportrait.jpg
    

    API 接收签名规则

    融云服务器向应用服务器推送数据(调用应用服务器接口)时会添加 3 个 GET 请求参数(在 URL 上添加的参数),具体如下:

    名称 类型 说明
    rc-nonce String 随机数,无长度限制。
    rc-timestamp String 时间戳,从1970年1月1日0点0分0秒开始到现在的秒数。
    rc-signature String 数据签名。

    RC-Signature (数据签名)计算方法:将系统分配的 App Secret、RC-Nonce (随机数)、RC-Timestamp (时间戳)三个字符串按先后顺序拼接成一个字符串并进行 SHA1 哈希计算。

    签名校验代码示例

    PHP 语言的代码示例:

    $appSecret = 'Y1W2MeFwwwRxa0'; // 开发者平台分配的 App Secret。
    $nonce = $_GET['rc-nonce']; // 获取随机数。
    $timestamp = $_GET['rc-timestamp']; // 获取时间戳。
    $signature = $_GET['rc-signature']; // 获取数据签名。
    $local_signature = sha1($appSecret.$nonce.$timestamp); // 生成本地签名。
    if(strcmp($signature, $local_signature)===0){
        // TODO: 此处添加业务逻辑。
        echo 'OK';
    } else {
        echo 'Error';
    }
    

    消息接收

    当 App 内用户向应用公众帐号发消息时,融云服务器将 POST 消息数据包(XML格式)到开发者配置的消息接收 URL 上。

    • 融云服务器在五秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次。
    • 关于重试的消息排重,推荐使用 MsgID 排重。
    • 假如开发者服务器无法保证在五秒内处理并回复,可以直接回复空字符串,融云服务器不会对此作任何处理,且不会发起重试。

    http 请求方式:POST

    请求接收方式:参见 API 接收签名规则

    文本消息格式

    XML 格式

    <xml>
    <ToUserName><![CDATA[toUserId]]></ToUserName>
    <FromUserName><![CDATA[fromUserName]]></FromUserName>
    <CreateTime>134223445860</CreateTime>
    <MsgType><![CDATA[text]]></MsgType>
    <Content><![CDATA[content]]></Content>
    <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 公众号 Id
    FromUserName 发送方用户 Id
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 text
    Content 文本消息内容
    MsgId 消息 Id

    图片消息格式

    XML 格式

    <xml>
    <ToUserName><![CDATA[toUserName]]></ToUserName>
    <FromUserName><![CDATA[fromUserName]]></FromUserName>
    <CreateTime>134223445860</CreateTime>
    <MsgType><![CDATA[image]]></MsgType>
    <PicUrl><![CDATA[this is a url]]></PicUrl>
    <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 公众号 Id
    FromUserName 发送方用户 Id
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 image
    PicUrl 图片链接
    MsgId 消息 Id

    语音消息格式

    XML 格式

    <xml>
    <ToUserName><![CDATA[toUserName]]></ToUserName>
    <FromUserName><![CDATA[fromUserName]]></FromUserName>
    <CreateTime>134223445860</CreateTime>
    <MsgType><![CDATA[voice]]></MsgType>
    <VoiceUrl><![CDATA[this is url]]></VoiceUrl>
    <Format><![CDATA[AMR]]></Format>
    <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 公众号 Id
    FromUserName 发送方用户 Id
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 voice
    VoiceUrl 语音链接
    Format 语音格式,目前支持 AMR 格式
    MsgId 消息 Id

    位置消息格式

    XML 格式

    <xml>
    <ToUserName><![CDATA[toUserName]]></ToUserName>
    <FromUserName><![CDATA[fromUserName]]></FromUserName>
    <CreateTime>134223445860</CreateTime>
    <MsgType><![CDATA[location]]></MsgType>
    <Location_X>15.501</Location_X>
    <Location_Y>142.324</Location_Y>
    <Label><![CDATA[POI信息]]></Label>
    <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 公众号 Id
    FromUserName 发送方用户 Id
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 location
    Location_X 纬度
    Location_Y 经度
    Label 地理位置信息
    MsgId 消息 Id

    图文消息格式

    XML 格式

    <xml>
     <ToUserName><![CDATA[toUserName]]></ToUserName>
     <FromUserName><![CDATA[fromUserName]]></FromUserName>
     <CreateTime>134223445860</CreateTime>
     <MsgType><![CDATA[imgtxt]]></MsgType>
     <Title><![CDATA[title]]></Title>
     <Description><![CDATA[description]]></Description>
     <PicUrl><![CDATA[picUrl]]></PicUrl>
     <Url><![CDATA[url]]></Url>
     <MsgId>msgId</MsgID>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 开发者帐号
    FromUserName 发送方帐号
    CreateTime 消息创建时间
    MsgType 消息类型,此处为 imgtxt
    Title 消息的标题
    Description 消息文本内容
    PicUrl 图片地址
    Url 跳转的地址
    MsgId 消息 Id

    关注、取消事件推送

    关注事件

    用户在关注公众号时,会把这个事件消息推送到开发者置设的消息接收 URL 上。方便开发者给用户下发消息或做帐号的解绑操作。

    • 融云服务器在 五 秒内收不到响应会断掉连接,并且重新发起请求,总共重试 三 次。
    • 假如开发者服务器无法保证在 五 秒内处理并回复,可以直接回复空字符串,融云服务器不会对此作任何处理,且不会发起重试。

    XML 消息格式

    <xml>
    <ToUserName><![CDATA[toUserName]]></ToUserName>
    <FromUserName><![CDATA[fromUserName]]></FromUserName>
    <CreateTime>134223445860</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[subscribe]]></Event>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 公众号 Id
    FromUserName 发送方用户 Id
    CreateTime 消息创建时间
    MsgType 消息类型,此务为event
    Event 事件信息,此处为subscribe

    取消关注事件

    用户在关注/取消关注公众号时,会把这个事件消息推送到开发者置设的消息接收 URL 上。方便开发者给用户下发消息或做帐号的解绑操作。

    • 融云服务器在 五 秒内收不到响应会断掉连接,并且重新发起请求,总共重试 三 次。
    • 假如开发者服务器无法保证在 五 秒内处理并回复,可以直接回复空字符串,融云服务器不会对此作任何处理,且不会发起重试。

    XML 消息格式

    <xml>
    <ToUserName><![CDATA[toUserName]]></ToUserName>
    <FromUserName><![CDATA[fromUserName]]></FromUserName>
    <CreateTime>134223445860</CreateTime>
    <MsgType><![CDATA[event]]></MsgType>
    <Event><![CDATA[unsubscribe]]></Event>
    </xml>
    

    参数说明

    名称 说明
    ToUserName 公众号 Id
    FromUserName 发送方用户 Id
    CreateTime 消息创建时间
    MsgType 消息类型,此务为event
    Event 事件信息,此处为unsubscribe

    消息发送

    用户向公众号发送消息后,公众号会向用户发送回复消息,目前融云公众服务 API 支持文本、图片、语音、图文等消息类型。

    请注意,在发送多媒体(图片、语音)消息时需要预先上传多媒体文件到融云服务器。

    方法名:/message/send.json

    调用方式:参见 API 调用签名规则

    URL:https://api.ps.ronghub.com/message/send.json

    请注意:发送请求时 HTTP Request Header 中的 Content-Type 类型必须为 application/json

    文本消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "fromuser":"app.public.server112@uwd1c0sxdlx2",
       "touser":"sdfxl@uwd1c0sxdlx2",
       "msgtype":"text",
       "text":
       {
            "content":"Hello"
       },
       "userinfo":
       {
               "id":"1",
               "name":"xiaomei",
               "headimgurl":"http://aa.com/a.jpg"
       }
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:sdfxl@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 text。
    content 消息内容,最大长度为 2000 个字节。
    userinfo 用户收到消息时显示的发送用户信息,如不传时显示应用公众号的基本信息。
    id 客户端显示的用户 Id。
    name 客户端显示的用户昵称。
    headimgurl 客户端显示的用户头像。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    图片消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-imestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "fromuser":"app.public.server112@uwd1c0sxdlx2",
       "touser":"123@uwd1c0sxdlx2",
       "msgtype":"image",
       "image":
       {
             "media_id":"123434343443"
       } ,
       "userinfo":
       {
             "id":"1",
             "name":"xiaomei",
             "headimgurl":"http://aa.com/a.jpg"
       }
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:123@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 image。
    media_id 图片 Id,调用多媒体上传接口上传图片后获得。
    userinfo 用户收到消息时显示的发送用户信息,如不传时显示应用公众号的基本信息。
    id 客户端显示的用户 Id。
    name 客户端显示的用户昵称。
    headimgurl 客户端显示的用户头像。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    语音消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "fromuser":"app.public.server112@uwd1c0sxdlx2",
       "touser":"123@uwd1c0sxdlx2",
       "msgtype":"voice",
       "voice":
       {
             "media_id":"123434343443"
       } ,
       "userinfo":
       {
             "id":"1",
             "name":"xiaomei",
             "headimgurl":"http://aa.com/a.jpg"
       }
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:123@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 voice。
    media_id 语音 Id,调用多媒体上传接口上传语音后获得。
    userinfo 用户收到消息时显示的发送用户信息,如不传时显示应用公众号的基本信息。
    id 客户端显示的用户 Id。
    name 客户端显示的用户昵称。
    headimgurl 客户端显示的用户头像。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    图文消息

    示例

    Request:

    POST /message/send.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
       "fromuser":"app.public.server112@uwd1c0sxdlx2",
       "touser":"123@uwd1c0sxdlx2",
       "msgtype":"news",
       "news":
       {
           "articles": [
            {
                "title":"haha ",
                "description":" hahahaahhaha",
                "url":"URL",
                "picurl":"PIC_URL"
            },
            {
                "title":"lala",
                "description":" lalalalala",
                "url":"URL",
                "picurl":"PIC_URL"
            }
            ]
       },
       "userinfo":
       {
               "id":"1",
            "name":"xiaomei",
            "headimgurl":"http://aa.com/a.jpg"
       }
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    touser 接收用户标识,格式:用户 Id + @ + App key 例如:123@uwd1c0sxdlx2
    msgtype 消息类型,文本为 text,图片为 image,语音为 voice,图文消息为 news,此处为 news。
    articles 图文消息,一个图文消息最少为 1 条,最多为 10 条图文。
    title 图文消息的标题。
    description 图文消息的描述,描述内容不超过 1000 个汉字( 1 个汉字等于 2 个字符)。
    url 图文消息被点击后跳转的链接。
    picurl 图文消息的图片链接,支持JPG。
    userinfo 用户收到消息时显示的发送用户信息,如不传时显示应用公众号的基本信息。
    id 客户端显示的用户 Id。
    name 客户端显示的用户昵称。
    headimgurl 客户端显示的用户头像。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"invalid media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    消息群发

    公众号需要向全部关注用户发送消息时,融云公众服务为公众号提供了每天 一 条的群发权限,按自然天计算,暂时只支持向全部关注用户发送消息。

    请注意,在群发多媒体消息时需要预先上传多媒体文件到融云服务器。

    方法名:/message/sendall.json

    调用方式:参见 API 调用签名规则

    URL:https://api.ps.ronghub.com/message/sendall.json

    请注意:发送请求时 HTTP Request Header 中的 Content-Type 类型必须为 application/json

    群发文本消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
      "fromuser":"app.public.server112@uwd1c0sxdlx2",
      "filter":{
         "is_to_all": true
      },
      "text":{
         "content":"CONTENT"
      },
      "msgtype":"text"
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持 true,默认为 true。
    content 消息内容,最大长度为 2000 个字节。
    msgtype 消息类型,图文消息为 mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 text。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    群发图文消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
      "fromuser":"app.public.server112@uwd1c0sxdlx2",
      "filter":{
         "is_to_all":true
      },
      "mpnews":{
         "media_id":"123dsdajkasd231jhksad"
      },
      "msgtype":"mpnews"
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持 true,默认为 true。
    msgtype 消息类型,图文消息为mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 mpnews。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    注意图文消息的 media_id 需要通过上传图文消息素材方法来得到。

    群发语音消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
      "fromuser":"app.public.server112@uwd1c0sxdlx2",
      "filter":{
         "is_to_all": true
      },
      "voice":{
         "media_id":"123dsdajkasd231jhksad"
      },
      "msgtype":"voice"
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持true,默认为 true。
    media_id 用于群发的消息的 media_id。
    msgtype 消息类型,图文消息为 mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 voice。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    注意此处 media_id 需通过上传多媒体文件方法来得到。

    群发图片消息

    示例

    Request:

    POST /message/sendall.json HTTP/1.1
    Host: api.ps.ronghub.com
    RC-App-Key: uwd1c0sxdlx2
    RC-Nonce: 14314
    RC-Timestamp: 1408706337
    RC-Signature: 890b422b75c1c5cb706e4f7921df1d94e69c17f4
    Content-Type: application/json
    
    {
      "fromuser":"app.public.server112@uwd1c0sxdlx2",
      "filter":{
         "is_to_all": true
      },
      "image":{
         "media_id":"123dsdajkasd231jhksad"
      },
      "msgtype":"image"
    }
    

    表单参数:

    名称 是否必须 说明
    fromuser 发送用户标识,格式:公众号 Id + @ + App key 例如:app.public.server112@uwd1c0sxdlx2
    filter 用于设定图文消息的接收者。
    is_to_all 用于设定是否向全部用户发送,值为 true 或 false,目前暂只支持 true,默认为 true。
    media_id 用于群发的消息的 media_id。
    msgtype 消息类型,图文消息为 mpnews,文本消息为 text,语音为 voice,图片为 image,此处为 image。

    Response:

    正常示例:

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

    错误示例:

    {"errcode":1002,"errmsg":"media_id"}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    注意此处 media_id 需通过上传多媒体文件方法来得到。

    上传素材

    公众号在发送消息时经常用到一些媒体素材,需要开发者在上传多媒体文件后,通过返回的 media_id 进行发送。

    上传多媒体文件

    http 请求方式: POST

    调用方式:参见 API 调用签名规则,不同点是将放进 http header 中的参数放到 URL 后面,如下:

    http://api.ps.ronghub.com/media/upload?type=TYPE&RC-App-Key=xxx&RC-Nonce=adbc134sdf&RC-Timestamp=1234556566&RC-Signature=123421dsfsvc03u4asdflvjdsdfsdf
    

    表单参数:

    名称 是否必须 说明
    type 媒体文件类型,有图片(image)、语音(voice)、缩略图(thumb)。

    上传的多媒体文件以表单文件方式上传,格式和大小限制如下:

    • 图片(image): 2 M,支持 JPG、PNG 格式。
    • 缩略图(thumb) : 20 K,支持JPG、PNG格式。
    • 语音(voice):60 k,播放长度不超过 60s,目前支持 AMR 格式。

    Java 代码示例:

    String urlStr = "http://api.ps.ronghub.com/media/upload?type=image&RC-App-Key=xxx&RC-Nonce=adbc134sdf&RC-Timestamp=1234556566&RC-Signature=123421dsfsvc03u4asdflvjdsdfsdf";
    
            //
            HttpClient httpclient = new DefaultHttpClient();
            // 请求处理页面
             HttpPost httppost = new HttpPost(urlStr);
    
            // 创建待处理的文件
            FileBody file = new FileBody(new File(filepath));
    
            // 对请求的表单域进行填充
            MultipartEntity reqEntity = new MultipartEntity();
            reqEntity.addPart("file", file);
    
            // 设置请求
            httppost.setEntity(reqEntity);
            // 执行
            HttpResponse response = httpclient.execute(httppost);
    
            HttpEntity httpEntity = response.getEntity();
            BufferedReader br = new BufferedReader(new InputStreamReader(httpEntity.getContent(), "UTF-8"));
            StringBuffer backData = new StringBuffer();
            String line = null;
            while ((line = br.readLine()) != null) {
                backData.append(line);
            }
            System.out.println(backData.toString());
    

    返回值

    正常示例:

    {
      "type":"image",
      "media_id":"12344343252",
      "created_at":123456789
    }
    

    错误示例:

    {"errcode":1003,"errmsg":"invalid type "}
    

    可根据返回错误码,在 API 返回状态码说明 中查看错误明细。

    上传图文消息素材

    http 请求方式: POST

    调用方式:参见 API 调用签名规则,不同点是将放进 http header 中的参数放到 URL 后面,如下:

    http://api.ps.ronghub.com/media/uploadnews?RC-App-Key=xxx&RC-Nonce=adbc134sdf&RC-Timestamp=1234556566&RC-Signature=123421dsfsvc03u4asdflvjdsdfsdf
    

    POST 数据示例:

    {
      "articles": [
             {
           "thumb_media_id":"sdflsdfjxcl324324sdfsdlfsd",
           "author":"yyuy",
                  "title":"Happy ",
                  "content_source_url":"www.rongcloud.com",
                  "content":"content",
                  "digest":"digest",
           "show_cover_pic":"1"
             },
             {
           "thumb_media_id":" sdflsdfjxcl324324sdfsdlfsdasdfsdf",
           "author":"yy",
                  "title":"Happy",
                  "content_source_url":"www.rongcloud.com",
                  "content":"content",
                  "digest":"digest",
           "show_cover_pic":"0"
             }
      ]
    }
    

    表单参数:

    名称 是否必须 说明
    articles 图文消息,一个图文消息支持 1 到 10 条图文。
    thumb_media_id 图文消息缩略图的 media_id,可以在基础支持-上传多媒体文件接口中获得。
    author 图文消息的作者。
    title 图文消息的标题。
    content_source_url 在图文消息页面点击“阅读原文”后链接的页面。
    content 图文消息页面的内容,支持 HTML 标签。
    digest 图文消息的描述。
    show_cover_pic 是否显示封面,1 为显示,0 为不显示。

    返回值

    {
      "type":"news",
      "media_id":"CsEf3ldqkAYJAU6EJeIkStVDSvffUJ54vqbThMgplD-VJXXof6ctX5fI6-aYyUiQ",
      "created_at":1391857799
    }
    

    表单参数:

    名称 说明
    type 媒体文件类型, news,即图文消息。
    media_id 媒体文件/图文消息上传后获取的唯一标识。
    created_at 媒体文件上传时间。

    第三方客服接入指南

    爱客服接入

    接入条件
    • 1、集成融云 2.0 及以上版本的 SDK 的 App 可通过应用公众服务接入客服功能。
    • 2、在爱客服注册客服帐号,注册爱客服
    接入流程

    1、进入融云开发者后台进入应用详情页面点击应用公众服务 > 爱客服进入

    image
    爱客服

    2、进入公众服务页面,如果应用未申请上线,则在开发环境点击“创建公众号”;生产环境内的创建公众号在应用申请上线通过后才能使用。

    image
    创建公众号

    3、完善公众号信息后,点击“保存”。

    image
    保存公众号信息

    4、提示操作成功后页面上会出现登录爱客服

    image
    登录爱客服

    5、登录爱客服后,在系统管理 > 授权融云中点击“去融云授权”

    image
    授权融云
    image
    授权融云

    7、返回到融云界面点击“确认绑定”再跳转到爱客服界面则授权成功。

    image
    确认绑定

    至此爱客服绑定授权操作完成,集成 SDK 中代码后即可使用客服功能。

    image
    iOS 接入代码

    开发者需要自已创建视图控制器,调起客服聊天界面,代码示例如下:

    /**
     * 参数说明
     *
     * conversationType 会话类型,此处应该传 RCConversationType.ConversationType_APPSERVICE
     * targetId 公众号 Id
     * userName 客服名称
     * title 客服会话界面 Title
     */
     RCPublicServiceChatViewController *conversationVC = [[RCPublicServiceChatViewController alloc] init];
    conversationVC.conversationType = conversationType;
    conversationVC.targetId = targetId;
    conversationVC.userName = conversationTitle;
    conversationVC.title = conversationTitle;
    [self.navigationController pushViewController:conversationVC animated:YES];
    
    Android 接入代码

    通过 startConversation 方法,调起客服聊天界面,代码示例如下:

    /**
     *
     * @param context 应用上下文。
     * @param conversationType 会话类型。
     * @param targetId 客服 Id。
     * @param title 聊天的标题,如果传入空值,则默认显示会话的名称。
     */
    RongIM.getInstance().startConversation(getActivity(),Conversation.ConversationType.APP_PUBLIC_SERVICE, targetId, "在线客服")。
    

    API 返回状态码说明

    业务返回码

    code 描述 详细解释
    1000 服务内部错误 服务器端内部逻辑错误,请稍后重试
    1002 参数错误 参数错误,详细的描述信息会说明
    1004 验证签名错误 验证签名错误
    1007 被限制调用 该方法被限制调用,详细的描述信息会说明
    1008 调用频率超限 调用频率超限,详细的描述信息会说明