1   新手接入

蓝信开放平台是提供给第三方应用为蓝信用户提供服务的平台,开放接口则是为第三方应用提供服务的基础。第三方应用开发者在蓝信平台申请公众号,获取接口权限后,可以通过阅读本接口文档来帮助开发。

蓝信开放平台接口提供第三方应用与用户进行信息交互、自定义菜单交互的能力。企业可以通过这些接口整合企业应用系统到蓝信,利用蓝信通讯录和即时消息基础功能,可以实现类似微信服务号/订阅号的应用。

蓝信开放平台提供自定义菜单接口,自定义菜单能够帮助公众号丰富界面,让用户更好更快地理解公众号的功能。公众号界面如图所示:

目前自定义菜单最多包括3个一级菜单,每个一级菜单最多包含5个二级菜单。一级菜单最多4个汉字,二级菜单最多7个汉字,多出来的部分将会以“...”代替。请注意,创建自定义菜单后,由于蓝信客户端缓存,需要24小时蓝信客户端才会展现出来。

说明:

由于客户端会缓存菜单,建议开发时,如果更新了菜单,可以手动删除消息会话列表中的公众号,然后重新推送客服消息,就可以看到更新后的菜单。android客户端也可以清除应用缓存更新客户端菜单显示。

 

第一步:申请蓝信公众号

联系蓝信平台组织管理员,开通一个蓝信公众号。

第二步:获取tokenappid和开发者密钥secret

token用作生成签名,第三方接收开放平台数据时会收到token的签名,通过和本地token比较,验证请求安全性。

appid指开放平台分配给第三方的开发者账号。

secret指开放平台分配给第三方的开发者密钥。

公众号开通后,通过蓝信或者Email将公众号、企业信息、接收消息url(开放平台会将发往开发者的蓝消息推送至该url)信息提交至蓝信开放平台,蓝信开放平台生成开发者需要的tokenappidsecret。同样通过蓝信或者Email发送至申请者。

第三步:成为开发者

拿到tokenappidsecret后,恭喜您已经成为蓝信开放平台开发者,蓝信开放平台提供了可视化测试工具,访问地址为http://ip:端口/debug,开发者动手开发前可以通过该测试工具体验获取access_token、上传/下载资源文件、发送客服消息、查询菜单等接口。同时,也能进一步理解各个接口的作用。

 

蓝信开放平台支持httphttps,开发者使用接口前,需要用appidsecret换取access_tokenaccess_token是蓝信开放平台的全局唯一凭据,调用各个接口时都需要使用access_token

access_token是动态的、且有时效性,有效时间为7200s

 

消息分为客服消息和被动响应消息。

客服消息:公众号主动向用户发送消息。

被动响应消息:用户向公众号发送消息或者菜单事件,公众号作出响应的消息。

1.   客服消息的消息体采用json格式,

l  参数说明:

参数

描述

touser

接收人

msgtype

消息类型

media_id

资源文件ID,附件消息使用

title

消息标题

url

消息中链接,图文和链接消息使用

l  示例数据:

{

    "touser": "OPENID",

    "msgtype": "attachment",

    "attachment": {

        "media_id": "MEDIA_ID"

    }

}

2.   被动响应消息的消息体采用xml格式

l  参数说明:

参数

描述

ToUserName

接收人

MsgType

消息类型

MediaId

资源文件ID,附件消息使用

Title

消息标题

Url

消息中链接,图文和链接消息使用

CreateTime

消息创建时间

l  示例数据:

<xml>

<ToUserName><![CDATA[接收者]]></ToUserName>

<FromUserName><![CDATA[发送者]]></FromUserName>

<CreateTime>12345678</CreateTime>

<MsgType><![CDATA[text]]></MsgType>

<Content><![CDATA[你好]]></Content>

</xml>

 

公众号每次调用接口时,可能获得正确或错误的返回码,开发者可以根据返回码信息调试接口,排查错误。

全局返回码说明如下:

返回码

说明

-1

系统繁忙

0

请求成功

1

数据请求失败

10015

不支持公号对公号发送

10101

菜单已存在,请勿重复创建

10102

没有找到对应菜单

10401

无权请求此组织数据

10502

找不到此消息对应的附件,请您检查后重新发送

10503

消息发送失败

40001

获取access_tokenAppSecret错误,或者access_token无效

40002

不合法的凭证类型

40006

不合法的文件大小

40007

不合法的媒体文件id

40008

不合法的消息类型

40013

不合法的APPID

40014

不合法的access_token

40015

不合法的菜单类型

40016

不合法的按钮个数

40017

不合法的按钮个数

40018

不合法的按钮名字长度

40019

不合法的按钮KEY长度

40020

不合法的按钮URL长度

40022

不合法的子菜单级数

40023

不合法的子菜单按钮个数

40024

不合法的子菜单按钮类型

40025

不合法的子菜单按钮名字长度

40026

不合法的子菜单按钮KEY长度

40027

不合法的子菜单按钮URL长度

40028

不合法的自定义菜单使用用户

40029

不合法的oauth_code

40030

不合法的refresh_token

40033

不合法的请求字符,不能包含\uxxxx格式的字符

40035

不合法的参数

40038

不合法的请求格式

40039

不合法的URL长度

41001

缺少access_token参数

41002

缺少appid参数

41003

缺少refresh_token参数

41004

缺少secret参数

41005

缺少多媒体文件数据

41006

缺少media_id参数

41007

缺少子菜单数据

41008

缺少oauth code

42001

access_token超时

42002

refresh_token超时

42003

oauth_code超时

43001

需要GET请求

43002

需要POST请求

43003

需要HTTPS请求

44001

多媒体文件为空

44002

POST的数据包为空

44003

图文消息内容为空

44004

文本消息内容为空

45002

消息内容超过限制

45003

标题字段超过限制

45004

描述字段超过限制

45005

链接字段超过限制

45006

图片链接字段超过限制

45008

图文消息超过限制

45010

创建菜单个数超过限制

45015

回复时间超过限制

46001

不存在媒体数据

46002

不存在的菜单版本

46003

不存在的菜单数据

46004

不存在的用户

47001

解析JSON/XML内容错误

48001

api功能未授权

50001

用户未授权该api

60001

auth_token无效

30014

用户认证,sso_token不能为空!

30015

sso_token错误,认证失败!

 

2   开发者需要处理

    第三方可从msgcontent获取开放平台推送的消息内容。

 

    开发者接收消息的时候,开放平台将发送POST请求到开发者填写的URL上,并且带了四个参数(singaturetimestampnonceechostr),开发者通过对签名(即singature)的校验,来判断消息的真实性。

    加密协议:

参数

描述

signature

蓝信加密签名,signature为开发者填写的token和请求中的timestampnonceechostr参数加密的结果

timestamp

时间戳

nonce

随机数

echostr

随机字符串

加密/校验流程如下:

1.   tokentimestampnonce三个参数进行字典序排序

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

3.   开发者获得加密后的字符串可与signature对比,结果一样表示该请求来源于蓝信。

 

    当蓝信用户向公众账号发消息时,开放平台将消息POST到开发者填写的URL上。关于重试的消息排重,推荐使用msgid排重,、

    注意:假如开发者服务器无法保证在五秒内处理并回复,可以直接回复空串,开放平台不会对此作出任何处理,并且不会发起重试。

    各消息类型协议和数据如下:

 

l  消息体对象:

参数

描述

ToUserName

开发者公号

FromUserName

发送方帐号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型text

Content

文本消息内容

MsgId

消息id

 

l  示例数据:

<xml>

<ToUserName><![CDATA[ToUserName]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>1348831860</CreateTime>

<MsgType><![CDATA[text]]></MsgType>

<Content><![CDATA[this is a test]]></Content>

<MsgId>1234567890123456</MsgId>

</xml>

 

l  消息体对象:

参数

描述

ToUserName

开发者公号

FromUserName

发送方帐号

CreateTime

消息创建时间 (长整型)

MsgType

attachment

MediaId

图片消息媒体id,可以调用多媒体文件下载接口拉取数据

MsgId

消息id

 

l  示例数据:

<xml>

<ToUserName><![CDATA[ToUserName]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>1348831860</CreateTime>

<MsgType><![CDATA[attachment]]></MsgType>

<MediaId><![CDATA[mediaId]]></MediaId>

<MsgId>1234567890123456</MsgId>

</xml>

 

l  消息体对象:

参数

描述

ToUserName

开发者公号

FromUserName

发送方帐号

CreateTime

消息创建时间 (长整型)

MsgType

link

Url

链接地址URL

MsgId

消息id

l  示例数据:

<xml>

<ToUserName><![CDATA[ToUserName]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>1351776360</CreateTime>

<MsgType><![CDATA[link]]></MsgType>

<Url><![CDATA[url]]></Url>

<MsgId>1234567890123456</MsgId>

</xml>

 

    菜单事件包括CLICKVIEWLOCATIONPROXYVIEW,其中CLICKLOCATION;类型事件会被转发到第三方,第三方可从msgContent获取消息内容,由第三方处理返回响应数据。

    开放平台在十秒内收不到响应会断掉连接,并且重新发起请求,总共重试三次 关于重试的消息排重,推荐使用FromUserName + CreateTime 排重。

    假如开发者服务器无法保证在十秒内处理并回复,可以直接回复空串,开放平台不会对此作任何处理,并且不会发起重试。

    用户点击自定义菜单后,如果菜单按钮设置为click类型,则会把此次点击事件推送给开发者,注意view类型菜单点击,是跳转到url,不会推送事件消息到公众号。

    各个事件消息协议和数据如下:

 

l  消息体对象:

参数

描述

ToUserName

开发者公号

FromUserName

发送方帐号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型:event表示事件消息类型

Event

事件类型:CLICK菜单事件,将菜单key发送只开发者

EventKey

菜单KEY,开发者可以通过KEY区分不同业务

MsgId

消息id

l  示例数据:

<xml>

<MsgId>-1111</MsgId>

<ToUserName><![CDATA[ToUserName]]></ToUserName>

<FromUserName><![CDATA[FromUser]]></FromUserName>

<CreateTime>123456789</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[CLICK]]></Event>

<EventKey><![CDATA[EVENTKEY]]></EventKey>

</xml>

 

创建菜单事件类型为location时,客户端会上报当前地理位置信息。

l  消息体对象:

参数

描述

MsgId

消息id

ToUserName

开发者公号

FromUserName

发送方帐号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型:event表示事件消息类型

Event

事件类型:CLICK

Location_X

地理位置纬度

Location_Y

地理位置经度

Scale

地图缩放大小

Label

地理位置信息

l  示例数据:

<xml>

<MsgId>-1111</MsgId>

<ToUserName><![CDATA[ToUserName]]></ToUserName>

<FromUserName><![CDATA[FromUser]]></FromUserName>

<CreateTime>123456789</CreateTime>

<MsgType><![CDATA[event]]></MsgType>

<Event><![CDATA[CLICK]]></Event>

<Location_X>23.134521</Location_X>

<Location_Y>113.358803</Location_Y>

<Scale>20</Scale>

<Label><![CDATA[位置信息]]></Label>

</xml>

 

    手机客户端通过公众平台向公号发送消息或者菜单事件,公众平台将消息或者菜单事件转发到第三方的redirect_url,第三方返回给公众平台响应消息(若无响应消息,返回空)。

   各消息类型协议和数据如下:

 

l  消息体对象

参数

描述

ToUserName

发送方账号

FromUserName

开发者公众号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型:text

Content

文本消息内容

l  示例数据

<xml>

<FromUserName>公号</FromUserName>

<ToUserName><![CDATA[手机号]]></ToUserName>

<CreateTime>时间戳</CreateTime>

<MsgType><![CDATA[text]]></MsgType>

<Content><![CDATA[你好]]></Content>

</xml>

 

l  消息体对象

参数

描述

ToUserName

发送方账号

FromUserName

开发者公众号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型:attachment

MediaId

附件资源ID,上传附件,由开放平台产生

 

l  示例数据

<xml>

<FromUserName>公号</FromUserName>

<ToUserName><![CDATA[手机号]]></ToUserName>

<CreateTime>12345678</CreateTime>

<MsgType><![CDATA[attachment]]></MsgType>

<MediaId><![CDATA[1]]></MediaId>

</xml>

 

l  消息体对象:

参数

描述

ToUserName

发送方账号

FromUserName

开发者公众号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型:link

Url

链接地址

l  示例数据:

<xml>

<FromUserName>公号</FromUserName>

<ToUserName><![CDATA[手机号]]></ToUserName>

<CreateTime>1351776360</CreateTime>

<MsgType><![CDATA[link]]></MsgType>

<Url><![CDATA[http://www.baidu.com]]></Url>

</xml>

 

l  消息体对象:

参数

描述

ToUserName

发送方账号

FromUserName

开发者公众号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型:news

Title

图文消息标题

ArticleCount

图文消息个数,限制为10条以内

Articles

多条图文消息信息,默认第一个item为大图,注意,如果图文数超过10,则将会无响应

Description

图文消息描述

PicUrl

图片链接,支持JPGPNG格式,较好的效果为大图360*200,小图200*200

Url

点击图文消息跳转链接

l  示例数据:

<xml>

<ToUserName><![CDATA[toUser]]></ToUserName>

<FromUserName><![CDATA[fromUser]]></FromUserName>

<CreateTime>12345678</CreateTime>

<MsgType><![CDATA[news]]></MsgType>

<ArticleCount>2</ArticleCount>

<Articles>

<item>

<Title><![CDATA[title1]]></Title>

<Description><![CDATA[description1]]></Description>

<PicUrl><![CDATA[picurl]]></PicUrl>

<Url><![CDATA[url]]></Url>

</item>

<item>

<Title><![CDATA[title]]></Title>

<Description><![CDATA[description]]></Description>

<PicUrl><![CDATA[picurl]]></PicUrl>

<Url><![CDATA[url]]></Url>

</item>

</Articles>

</xml>

 

l  消息体对象:

参数

描述

ToUserName

发送方账号

FromUserName

开发者公众号

CreateTime

消息创建时间 (长整型)

MsgType

消息类型:backGroundview

Url

客户端需要跳转的url

    说明:MsgType取值backGround客户端从后台请求Url,取值view则客户端通过webview打开。

l  示例数据:

<xml>

<FromUserName>公号</FromUserName>

<ToUserName><![CDATA[手机号]]></ToUserName>

<CreateTime>1351776360</CreateTime>

<MsgType><![CDATA[backGround/view]]></MsgType>

<Url><![CDATA[http://ip:端口/xxx]]></Url>

</xml>

 

 

3   蓝信提供接口

    使用接口时,采用POST方式传参

 

l  接口名:

http://ip:端口/cgi-bin/token?grant_type=client_credential&appid=APPID

&secret=APPSECRET

l  接口描述:

access_token是公众号的全局唯一凭据,公众号调用各接口时,都需要使用access_token

l  http请求方式:POST/GET

l  request参数对象:

参数

是否必须

描述

grant_type

获取access_token填写client_credential

appid

第三方用户唯一凭证

secret

开发者密钥

l  response参数对象:

参数

描述

errcode

请求状态

access_token

获取到的凭证

expires_in

凭证有效时间,单位:秒

l  返回数据示例:

a)   成功返回:

{

    "errcode": 0,

    "access_token": "ACCESS_TOKEN",

    "expires_in": 7200

}

b)   错误返回:

{

    "errcode": 40013,

    "errmsg": "不合法的APPID "

}

 

 

l  接口: 

http://ip:端口/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

l  接口描述

上传资源文件,文件类型包括:音/视频、图片、office文件等,用于发送附件消息、图文消息。

l  http请求方式:POST

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

type

媒体文件类型:分别有图片(image)、语音(voice)、视频(video)和缩略图(thumb

media

form-data中媒体文件标识,

filenamefilelengthcontent-type等信息

l  response参数对象:

参数

描述

errcode

请求状态码

filename

文件名

media_id

资源文件ID

 

 

l  返回数据示例:

a)  成功返回:

{

    "errcode": 0,

    "type": "TYPE",

    "media_id": "MEDIA_ID",

    "created_at": 123456789

}

b)  错误返回:

{

    "errcode": 40004,

    "errmsg": "不合法的媒体文件类型"

}

 

l  接口:

http://ip:端口/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

l  接口描述

下载文件。

l  http请求方式:POST/GET

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

media_id

媒体文件ID

l  response参数对象:

参数

描述

errcode

状态码,参照1.2.4中全局返回码说明

filename

文件名

l  返回数据示例:

a)  成功返回http头如下:

HTTP/1.1 200 OK

Connection: close

Content-Type: image/jpeg

Content-disposition: attachment; filename="MEDIA_ID.jpg"

Date: Sun, 06 Jan 2013 10:20:18 GMT

Cache-Control: no-cache, must-revalidate

Content-Length: 339721

curl -G "http://ip:端口/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

b)  错误返回:

{

    "errcode": 40007,

    "errmsg": "不合法的媒体文件id"

}

 

注意:此接口可以用于获取用户头像

 

l  接口名:

http://ip:端口/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

l  接口描述:

发送客服消息指公众号向手机客户端发送消息。支持发送文本、附件、链接、图文、邮件消息

l  http请求方式:POSTPOST一个JSON数据包来发送消息

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

4     response参数对象:

参数

描述

errcode

状态码,参照1.2.4中全局返回码说明

errmsg

返回信息描述

5     返回数据示例:

a)  成功返回:

{

    "errcode": 0,

    "errmsg": "请求成功"

}

b)  错误返回:

{

    "errcode": 40014,

    "errmsg": "不合法的access_token "

}

消息体说明如下:

 

6     消息体对象:

参数

描述

touser

接收方帐号

msgtype

消息类型:text

content

文本消息内容

7     示例数据

{

    "touser": "手机号",

    "msgtype": "text",

    "text": {

        "content": "Hello World"

    }

}

 

支持图片、音频、视频、office文件等附件消息。

8     消息体对象

参数

描述

touser

接收方帐号

msgtype

消息类型:attachment

title

标题

media_id

附件资源文件ID

9     示例数据

{

    "touser": "OPENID",

    "msgtype": "attachment",

    "title":"标题"

    "attachment": {

    "media_id": "MEDIA_ID"

}

 

l  消息体对象

参数

描述

touser

接收方帐号

msgtype

消息类型:link

url

链接地址

 

l  示例数据

{

    "touser": "OPENID",

    "msgtype": "link",

    "link": {

        "url": "http://www.lanxin.cn"

    }

}

 

图文消息条数限制在10条以内,注意,如果图文数超过10,则将会无响应。

l  消息体对象

参数

是否必须

描述

touser

接收方帐号

msgtype

消息类型:news

title

图文标题

description

描述

url

点击后跳转的链接

picurl

图文消息的图片链接

type

图文消息链接类型,默认值为00 URL1 语音; 2 视频; 3 文档 ; 4 未知

flag

int类型:0 默认值,可以不传;

1. 访问link的时候增加nametelephone要求以_ckey为可以传递。例如:http://host/path/uri?_ckey=base64(name=name&telephone=telephon)

l  示例数据

{

    "touser": "手机号",

    "msgtype": "news",

    "news": {

        "articles": [{

                "title": "Happy Day",

                "description": "Is Really A Happy Day",

                "url": "URL",

                "picurl": "PIC_URL",

                "type": 0,

                "flag": 0},

{

                "title": "Happy Day",

                "description": "Is Really A Happy Day",

                "url": "URL",

                "picurl": "PIC_URL",

                "type": 0,

                "flag": 0}]

    }

}

 

    邮件消息是一种特殊的图文消息。

l  消息体对象:

参数

描述

touser

接收方帐号

msgtype

消息类型:mail

url

邮件消息链接地址

title

邮件消息标题

l  示例数据:

{

    "touser": "OPENID",

    "msgtype": "mail",

    "mail": {

        "url": "http://www.lanxin.cn",

        "title": "邮件标题"

    }

}

重要说明

1) 邮件消息url返回数据对象:

参数

描述

flag

有无附件标识,0-无附件;1-有附件

link

邮件打开链接

mainText

新邮件文本内容

mailFrom

发送者邮箱

time

邮件发送时间

title

邮件标题

2) 示例数据:

[

    {

        "flag": 0,

        "link": "http://ip:端口/lanxin_opc_360cloud/videoTest.jsp",

        "mainText:”新邮件文本内容",

        "mailFrom": "zhangsan@comisys.net",

        "time": "14-05-23 15:30",

        "title": "邮件标题"

    }

]

 

 

l  接口名:

http://ip:端口/cgi-bin/message/mass/send?access_token=ACCESS_TOKEN

l  接口描述:

群发消息指第三方向多人或者多组织(分支部门)的成员发送消息。

l  http请求方式:POSTPOST一个JSON数据包来发送消息

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

10   response参数对象:

参数

描述

errcode

状态码,参照1.2.4中全局返回码说明

errmsg

返回信息描述

11   返回数据示例:

c)  成功返回:

{

    "errcode": 0,

    "errmsg": "请求成功"

}

d)  错误返回:

{

    "errcode": 40014,

    "errmsg": "不合法的access_token "

}

消息体说明如下:

 

12   消息体对象:

参数

描述

tousers

多个接收方手机号,多个以“,”间隔

togroups

多个接收方分支ID,多个以“,”间隔

toall

true:群发给整个组织;false:按照touserstogroups群发

msgtype

消息类型:text

content

文本消息内容

13   示例数据

{

"toall": true,

"tousers": ["手机号1","手机号2"],

    "togroups": ["分支1","分支2"],

    "msgtype": "text",

    "text": {

        "content": "Hello World"

    }

}

 

支持图片、音频、视频、office文件等附件消息。

14   消息体对象

参数

描述

tousers

多个接收方手机号,多个以“,”间隔

togroups

多个接收方分支ID,多个以“,”间隔

toall

true:群发给整个组织;false:按照touserstogroups群发

msgtype

消息类型:attachment

title

标题

media_id

附件资源文件ID

l  示例数据

{

"toall": true,

"tousers": ["手机号1","手机号2"],

    "togroups": ["分支1","分支2"],

    "msgtype": "attachment",

    "title":"标题",

    "attachment": {

        "media_id": "MEDIA_ID"

    }

}

 

l  消息体对象

参数

描述

tousers

多个接收方手机号,多个以“,”间隔

togroups

多个接收方分支ID,多个以“,”间隔

toall

true:群发给整个组织;false:按照touserstogroups群发

msgtype

消息类型:link

url

链接地址

 

l  示例数据

{

"toall": true,

"tousers": ["手机号1","手机号2"],

    "togroups": ["分支1","分支2"],

    "msgtype": "link",

    "link": {

        "url": "http://www.lanxin.cn"

    }

} }

 

图文消息条数限制在10条以内,注意,如果图文数超过10,则将会无响应。

l  消息体对象

参数

是否必须

描述

tousers

多个接收方手机号,多个以“,”间隔,touserstogroups二者至少有一个

togroups

多个接收方分支ID,多个以“,”间隔

toall

true:群发给整个组织;false:按照touserstogroups群发

msgtype

消息类型:news

title

图文标题

description

描述

url

点击后跳转的链接

picurl

图文消息的图片链接

Type

图文消息链接类型,默认值为00 URL1 语音; 2 视频; 3 文档 ; 4 未知

Flag

int类型:0 默认值,可以不传;

1. 访问link的时候增加nametelephone要求以_ckey为可以传递。例如:http://host/path/uri?_ckey=base64(name=name&telephone=telephon)

l  示例数据

{

"toall": true,

"tousers": ["手机号1","手机号2"],

    "togroups": ["分支1","分支2"],

"msgtype": "news",

"news": {

        "articles": [

            {

                "title": "Happy Day",

                "description": "Is Really A Happy Day",

                "url": "URL",

                "picurl": "PIC_URL",

                "type": 0,

                "flag": 0

            },

            {

                "title": "Happy Day",

                "description": "Is Really A Happy Day",

                "url": "URL",

                "picurl": "PIC_URL",

                "type": 0,

                "flag": 0

            }

        ]

    }

}

 

    邮件消息是一种特殊的图文消息。

l  消息体对象:

参数

描述

tousers

多个接收方手机号,多个以“,”间隔

togroups

多个接收方分支ID,多个以“,”间隔

toall

true:群发给整个组织;false:按照touserstogroups群发

msgtype

消息类型:mail

url

邮件消息链接地址

title

邮件消息标题

l  示例数据:

{

"toall": true,

"tousers": ["手机号1","手机号2"],

    "togroups": ["分支1","分支2"],

    "msgtype": "mail",

    "mail": {

        "url": "http://www.lanxin.cn",

        "title": "邮件标题"

    }

}

重要说明

1) 邮件消息url返回数据对象:

参数

描述

Flag

有无附件标识,0-无附件;1-有附件

Link

邮件打开链接

mainText

新邮件文本内容

mailFrom

发送者邮箱

Time

邮件发送时间

title

邮件标题

2) 示例数据:

[

    {

        "flag": 0,

        "link": "http://ip:端口/lanxin_opc_360cloud/videoTest.jsp",

        "mainText:”新邮件文本内容",

        "mailFrom": "zhangsan@comisys.net",

        "time": "14-05-23 15:30",

        "title": "邮件标题"

    }

]

 

l  接口名:

http://ip:端口/cgi-bin/member/get?access_token=ACCESS_TOKEN&orgId=

ORGID&mobile=MOBILE&email=EMAIL

l  接口描述:

查询成员信息,此接口缓存时间为5分钟,非实时数据

l  http请求方式:POST/GET

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

mobile

待查询成员手机号

email

待查询成员email

orgId

组织ID

    注:mobileemail填写一个即可,优先取mobile进行查询

l  response参数对象(当返回的数据中某个字段的值为null时,该key-value在报文中不显示)

参数

描述

errcode

状态码

errmsg

返回状态描述

Code

成员在组织中的位置(code路径)

mobile

手机号

orgId

组织号

userUniId

用户标识符

company

成员所在公司名称,对应蓝信中的“单位”,一般和orgName一样。如果为集团公司,company一般为集团子公司名称

photoResId

头像资源ID(头像不存在时报文中无此字段)

email

Email

companyId

所属单位ID

orgName

成员所在组织名称,一般和company一样。如果是集团公司,orgName为集团名称

secondPosition

岗位类别

busiTags

业务属性列表

posiTags

职务属性列表

contactExs

联系方式扩展

position

 

serialNumber

序列号,如警号

Note

备注,说明

Name

成员名称

Id

成员id

Path

成员在组织中的位置

orgNamecompanypath关系说明:

a)   集团公司

   

    如上图所示:

    orgName:集团名称。

    company:集团下子公司名称

    path:张三在组织机构中的位置pathorgName-company1-研发中心

b)   非集团公司

    如上图所示:

    orgNamecompany一样,都表示公司的名称。

    path:张三在组织机构中的位置pathorgName/company-技术开发部-张三。

l  返回数据示例:

{

    "errcode": 0,

    "errmsg": "请求成功",

    "openOrgMemberList": [

     {

             mobile: "18612345678",

             orgId: 34,

             userUniId:"83191@34.uni1",

             company:"蓝信工厂",

             photoResId:"fe7cf9a1-e5b4-4469-961e-82d72c05e24d",

             parentId: 111111,

             email: "yangxue@comisys.net",

             companyId:594771,

             orgName: "蓝信工场",

             secondPosition: "",

             busiTags:

             [

 

             ],

             posiTags:

             [

 

             ],

             contactExs:

             [

           

             ],

             position:"",

             serialNumber:"",

             note:"",

             name: "杨雪",

             id: 1113,

             code : "34-594771",

            "path": "蓝信工场-研发部",

        },

        {

             mobile: "18612345678",

             orgId: 34,

             userUniId:"83191@34.uni1",

             company:"蓝信工厂",

             photoResId:"fe7cf9a1-e5b4-4469-961e-82d72c05e24d",

             parentId: 111111,

             email: "yangxue@comisys.net",

             companyId:594771,

             orgName: "蓝信工场",

             secondPosition: "",

             busiTags:

             [

 

             ],

             posiTags:

             [

 

             ],

             contactExs:

             [

           

             ],

             position:"",

             serialNumber:"",

             note:"",

             name: "杨雪",

             id: 1104,

             code : "34-594772",

             path: "蓝信工场-产品部",

        }

    ]

}

 

l  接口名:

http://ip:端口/cgi-bin/org/struct/parent/get?access_token=ACCESS_TOKEN&

orgId=ORGID&structId=STRUCTID&queryType=QUERYTYPE

l  接口描述:

根据组织和分支ID查询分支下的数据,可用于展示组织结构和人员信息。

l  http请求方式:POST/GET

l  request参数对象:

 

参数

是否必须

描述

access_token

调用接口凭证

structId

分支ID,为0时表示从根节点查询

queryType

0:分支节点;1:成员节点;-1:全部节点

l  response参数对象(当返回的数据中某个字段的值为null时,该key-value在报文中不显示)

参数

描述

errcode

状态码

errmsg

返回状态描述

openOrgStructList

分支机构列表

Id

分支ID

Name

分支名称

Path

分支所在位置

parentId

分支父级机构,为0时,表示当前节点为根节点

openOrgMemberList

成员列表

Id

成员ID

Name

成员名称

email

Email

Mobile

手机号

Path

成员所在组织位置

orgName

成员所在组织名称

orgId

成员所在组织id

company

成员所在公司

Code

成员在组织中的位置(code路径)

l  返回数据示例:

{

    "openOrgStructList": [

        {

            "id": 9,

            "order":0

            "name": "北京分公司",

            "path": "蓝信工场-一级分支-二级分支-北京分公司",

            "code" : "34-594771-594792-594743",

            "parentId": 5

        },

        {

            "id": 12,

            "order":0

            "name": "上海分公司",

            "path": "蓝信工场-一级分支-二级分支-上海分公司",

            "code" : "34-594771-594792-594749",

            "parentId": 5

        }

    ],

    "openOrgMemberList": [

        {

            "id": 1113,

            "name": "杨雪",

            "userUniId":"87284@34.uni1",

             photoResId:"fe7cf9a1-e5b4-4469-961e-82d72c05e24d",

            "email": "yangxue@comisys.net",

            "mobile": "18612345678",

            "path": "蓝信工场-一级分支-二级分支",

            "code" : "34-594771-594792-594743",

            "orgName": "蓝信工场",

            "orgId": 1,

            "company": "蓝信工场"

        },

        {

            "id": 1104,

            "name": "杨冰",

            "userUniId":"87285@34.uni1",

             photoResId:"4t64cf9a1-e5b4-4469-961e-82d72c0534e1",

            "email": "yangbing@comisys.net",

            "mobile": "18687654321",

            "path": "蓝信工场-一级分支-二级分支",

            "code" : "34-594771-594792-594743",

            "orgName": "蓝信工场",

            "orgId": 1,

            "company": "蓝信工场"

        }

    ],

    "errmsg": "请求成功",

    "errcode": 0

}

 

l  接口名:

http://ip:端口/cgi-bin/message/control?access_token=ACCESS_TOKEN&msgId=MSGID

l  接口描述:

查询消息送达状态,支持客服消息、群发消息的状态查询。

注:要记录消息送达状态数据量会很大,默认状态下是不保存发送状态的。如果想要记录消息发送状态,需在发送的消息报文体中加入needSendingState字段

客服消息

{

    "touser": "手机号",

    "msgtype": "text",

    "needSendingState": 1,

    "text": {

        "content": "Hello World"

    }

}

 

群发消息

{

    "tousers": ["手机号1","手机号2"],

    "togroups": ["分支1","分支2"],

    "msgtype": "text",

    "needSendingState": 1,

    "text": {

        "content": "Hello World"

    }

}

l  http请求方式:POST/GET

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

msgId

待查询消息ID

l  response参数对象:

参数

描述

errcode

状态码

errmsg

返回状态描述

Id

成员id

sendingState

发送状态

mobile

手机号

dialogId

Appid

sendTime

发送时间

userMessageId

消息ID

recieveTime

到达时间

userMessageBodyId

消息体ID

readTime

阅读时间

l  返回数据示例:

客服消息

{

"msgSendStateList":[{

"id":27,

"sendingState":0,

"mobile":"13683520979",

"dialogId":"100909",

"sendTime":1432611450000,

"userMessageId":234845,

"recieveTime":1432611450000,

"userMessageBodyId":136277,

"readTime":1432611450000

}],

"errmsg":"请求成功",

"errcode":0

}

群发消息

{

"msgSendStateList":[

{

"dialogId":"100909",

"sendingState":0,

"sendTime":1431671397000,

"userMessageId":232211,

"id":25,

"mobile":"13683520979",

"recieveTime":1431671397000,

"readTime":1431671397000,

"userMessageBodyId":134908

},

{

"dialogId":"100909",

"sendingState":0,

"sendTime":1431671397000,

"userMessageId":232212,

"id":26,

"mobile":"13910425062",

"recieveTime":1431671397000,

"readTime":1431671397000,

"userMessageBodyId":134908

}],

"errmsg":"请求成功",

"errcode":0

}

 

l  接口名:

http://ip:端口/cgi-bin/menu/create?access_token=ACCESS_TOKEN

l  接口描述:

创建自定义菜单。

l  http请求方式:POSTPOST一个JSON数据包

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

说明:

菜单参数说明

参数

描述

button

一级菜单数组,个数应为1~3

sub_button

二级菜单数组,个数应为1~5

type

菜单的响应动作类型,目前有clickviewlocationproxyView四种类型

name

菜单标题,不超过16个字节,子菜单不超过40个字节

key

菜单KEY值,用于消息接口推送,不超过128字节

flag

1 oauth菜单view类型使用,0或者不传普通view类型

url

网页链接,用户点击菜单可打开链接,不超过256字节

示例数据:

{

    "button": [

        {

            "type": "click",

            "name": "今日歌曲",

            "key": "V1001_TODAY_MUSIC"

        },

        {

            "type": "click",

            "name": "歌手简介",

            "key": "V1001_TODAY_SINGER"

        },

        {

            "type": "click",

            "name": "签到",

            "key": "qiandaokey"

        },

        {

            "name": "菜单",

            "sub_button": [

                {

                    "type": "view",

                    "name": "搜索",

                    "url": "https://www.soso.com/"

                    "flag": 1

                },

                {

                    "type": "view",

                    "name": "视频",

                    "url": "https://v.lanxin.com/"

                },

                {

                    "type": "click",

                    "name": "赞一下我们",

                    "key": "V1001_GOOD"

                }

            ]

        }

    ]

}

 

l  response参数对象:

参数

描述

errcode

状态码,参照1.2.4中全局返回码说明

errmsg

返回信息描述

l  返回数据示例:

a) 成功返回:

{

    "errcode": 0,

    "errmsg": "请求成功"

}

b)错误返回:

{

    "errcode": 40018,

    "errmsg": "不合法的按钮名字长度"

}

 

l  接口名:

http://ip:端口/cgi-bin/menu/get?access_token=ACCESS_TOKEN

l  接口说明:

查询菜单。

l  http请求方式:POST/GET

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

l  response参数对象:

参数

描述

menu

菜单数据列表

button

一级菜单数组,个数应为1~3

sub_button

二级菜单数组,个数应为1~5

type

菜单的响应动作类型,目前有clickviewlocationproxyView四种类型

name

菜单标题,不超过16个字节,子菜单不超过40个字节

key

菜单KEY值,用于消息接口推送,不超过128字节

url

网页链接,用户点击菜单可打开链接,不超过256字节

l  返回数据示例:

{

    "errcode": 0,

    "errmsg": "请求成功",

    "menu": {

        "button": [

            {

                "type": "click",

                "name": "今日歌曲",

                "key": "V1001_TODAY_MUSIC",

                "sub_button": []

            },

            {

                "type": "click",

                "name": "歌手简介",

                "key": "V1001_TODAY_SINGER",

                "sub_button": []

            },

            {

                "name": "菜单",

                "sub_button": [

                    {

                        "type": "view",

                        "name": "搜索",

                        "url": "https://www.soso.com/",

                        "sub_button": []

                    },

                    {

                        "type": "view",

                        "name": "视频",

                        "url": "https://v.lanxin.com/",

                        "sub_button": []

                    },

                    {

                        "type": "click",

                        "name": "赞一下我们",

                        "key": "V1001_GOOD",

                        "sub_button": []

                    }

                ]

            }

        ]

    }

}

 

l  接口:

http://ip:端口/cgi-bin/menu/delete?access_token=ACCESS_TOKEN

l  接口描述:

删除菜单。

l  http请求方式:POST/GET

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

l  response参数对象:

参数

描述

errcode

状态码,参照1.2.4中全局返回码说明

errmsg

返回信息描述

l  返回数据示例:

{

    "errcode": 0,

    "errmsg": "请求成功"

}

 

l  接口:

http://ip:端口/cgi-bin/user/ssoauth?access_token=ACCESS_TOKEN

l  接口描述:

通过认证令牌验证用户,返回用户的登录名(手机号码)。

l  http请求方式:POST/GET

l  request参数对象:

参数

是否必须

描述

access_token

调用接口凭证

sso_token

认证令牌

l  response参数对象:

参数

描述

errcode

状态码,参照1.2.4中全局返回码说明

errmsg

返回信息描述

mobile

ssotoken对应的用户登录名(手机号码)

l  返回数据示例:

{

    "errcode": 0,

"errmsg": "请求成功",

"mobile": "13400000000"

}

 

 

l  接口描述

  通过手机号获取该手机号对应的联系人信息(信息包括:nameuseriduseruniidcompanypath 五个字段)

l  请求说明

Http请求方式: GET

http://ip:端口/lop-client/orgMember?access_token=ACCESS_TOKEN&mobile=MOBILE

例如:

http://oft05-open.e.lanxin.cn/cgi-bin/orgMember?access_token=f58b045fe9668d9f351ff92455a85514b90ad0f098e3e2de1793837f97b0feaa&mobile=18611024907

l  参数说明

参数

是否必须

描述

access_token

令牌,根据appidsecret获取

mobile

手机号

 

l  response参数对象:

参数

描述

name

名称

mobile

手机号

comanyView

显示单位

departmentView

显示部门路径

l  返回数据示例:

{

"errcode":0,

"errmsg":"请求成功",

"list":[{

"comanyView":"蓝信工场oft05",

"departmentView":"",

"name":"王好",

"mobile":"186011111111"

},

{

"comanyView":"蓝信工场oft05",

"departmentView":"产品中心",

"name":"张松",

"mobile":""

},

{

"comanyView":"蓝信工场oft05",

"departmentView":"产品中心",

"name":"戴维张",

"mobile":"134100000000"

},

{

"comanyView":"蓝信工场oft05",

"departmentView":"产品中心-产品部",

"name":"于茜茜",

"mobile":"18810622936"

},

{

"comanyView":"蓝信工场oft05",

"departmentView":"产品中心-产品部",

"name":"刘慧丽",

"mobile":"18510167960"

}]

}