公众服务

简介

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

公众服务平台： 在 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 接口，建议谨慎操作刷新密钥功能。

获取 RC-PSKey / Secret 位置

配置消息接收地址

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

消息接收 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 (数据签名)计算方法：

将系统分配的 secret、以及 RC-Nonce、RC-Timestamp 三个参数进行字典序排序

将三个参数字符串拼接成一个字符串进行 SHA1 加密

API 接收签名规则

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

名称

类型

说明

rc-nonce

String

随机数，无长度限制。

rc-timestamp

String

时间戳，从 1970 年 1 月 1 日 0 点 0 分 0 秒开始到当前时间(北京时间)的毫秒数。

rc-signature

String

数据签名。

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

将系统分配的 secret、以及 rc-nonce、rc-timestamp 三个参数进行字典序排序

将三个参数字符串拼接成一个字符串进行 SHA1 加密

接收消息

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

融云服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次。

关于重试的消息排重，推荐使用 MsgID 排重。

假如开发者服务器无法保证在五秒内处理并回复，可以直接回复空字符串，融云服务器不会对此作任何处理，且不会发起重试。

http 请求方式：POST

文本消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此处为 text

Content

文本消息内容

MsgId

消息 Id

图片消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此处为 image

PicUrl

图片链接

MsgId

消息 Id

语音消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此处为 voice

VoiceUrl

语音链接

Format

语音格式，目前支持 AMR 格式

MsgId

消息 Id

位置消息格式

XML 格式

134223445860

15.501

142.324

msgId

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此处为 location

Location_X

纬度

Location_Y

经度

Label

地理位置信息

MsgId

消息 Id

图文消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此处为 imgtxt

Title

消息的标题

Description

消息文本内容

PicUrl

图片地址

Url

跳转的地址

MsgId

消息 Id

事件推送

关注事件

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

融云服务器在 五 秒内收不到响应会断掉连接，并且重新发起请求，总共重试 三 次。

假如开发者服务器无法保证在 五 秒内处理并回复，可以直接回复空字符串，融云服务器不会对此作任何处理，且不会发起重试。

XML 消息格式

134223445860

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此务为event

Event

事件信息，此处为subscribe

取消关注事件

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

融云服务器在 五 秒内收不到响应会断掉连接，并且重新发起请求，总共重试 三 次。

假如开发者服务器无法保证在 五 秒内处理并回复，可以直接回复空字符串，融云服务器不会对此作任何处理，且不会发起重试。

XML 消息格式

134223445860

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此务为event

Event

事件信息，此处为unsubscribe

发送消息

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

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

方法名：/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: 1408710653491

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: 1408710653491

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: 1408710653491

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: 1408710653491

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

请注意：发送请求时 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: 1408710653491

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: 1408710653491

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: 1408710653491

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: 1408710653491

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 接口，建议谨慎操作刷新密钥功能。

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()*1000; // 获取时间戳(毫秒)。

$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: 1408710653491

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

文本消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

公众号 Id

FromUserName

发送方用户 Id

CreateTime

消息创建时间

MsgType

消息类型，此处为 text

Content

文本消息内容

MsgId

消息 Id

图片消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

公众号 Id

FromUserName

发送方用户 Id

CreateTime

消息创建时间

MsgType

消息类型，此处为 image

PicUrl

图片链接

MsgId

消息 Id

语音消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

公众号 Id

FromUserName

发送方用户 Id

CreateTime

消息创建时间

MsgType

消息类型，此处为 voice

VoiceUrl

语音链接

Format

语音格式，目前支持 AMR 格式

MsgId

消息 Id

位置消息格式

XML 格式

134223445860

15.501

142.324

msgId

参数说明

名称

说明

ToUserName

公众号 Id

FromUserName

发送方用户 Id

CreateTime

消息创建时间

MsgType

消息类型，此处为 location

Location_X

纬度

Location_Y

经度

Label

地理位置信息

MsgId

消息 Id

图文消息格式

XML 格式

134223445860

msgId

参数说明

名称

说明

ToUserName

开发者帐号

FromUserName

发送方帐号

CreateTime

消息创建时间

MsgType

消息类型，此处为 imgtxt

Title

消息的标题

Description

消息文本内容

PicUrl

图片地址

Url

跳转的地址

MsgId

消息 Id

关注、取消事件推送

关注事件

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

融云服务器在 五 秒内收不到响应会断掉连接，并且重新发起请求，总共重试 三 次。

假如开发者服务器无法保证在 五 秒内处理并回复，可以直接回复空字符串，融云服务器不会对此作任何处理，且不会发起重试。

XML 消息格式

134223445860

参数说明

名称

说明

ToUserName

公众号 Id

FromUserName

发送方用户 Id

CreateTime

消息创建时间

MsgType

消息类型，此务为event

Event

事件信息，此处为subscribe

取消关注事件

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

融云服务器在 五 秒内收不到响应会断掉连接，并且重新发起请求，总共重试 三 次。

假如开发者服务器无法保证在 五 秒内处理并回复，可以直接回复空字符串，融云服务器不会对此作任何处理，且不会发起重试。

XML 消息格式

134223445860

参数说明

名称

说明

ToUserName

公众号 Id

FromUserName

发送方用户 Id

CreateTime

消息创建时间

MsgType

消息类型，此务为event

Event

事件信息，此处为unsubscribe

消息发送

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

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

方法名：/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: 1408710653491

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: 1408710653491

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: 1408710653491

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

请注意：发送请求时 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: 1408710653491

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: 1408710653491

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: 1408710653491

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: 1408710653491

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、进入融云开发者后台应用详情页面点击爱客服进入。

爱客服

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

创建公众号

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

保存公众号信息

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

登录爱客服

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

授权融云

授权融云

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

确认绑定

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

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

调用频率超限

调用频率超限，详细的描述信息会说明