公众服务平台开发文档


注册融云公众服务

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

请注意,如开发者想通过自已的 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 媒体文件上传时间。

API 返回状态码说明

业务返回码

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

© 2016 RongCloud. All Rights Reserved. Version 2.8.5