Http api

来自恩布企业IM,协作平台文档
2014年5月7日 (三) 16:06Admin讨论 | 贡献的版本

(差异) ←上一版本 | 最后版本 (差异) | 下一版本→ (差异)
跳转至: 导航搜索


概述

本文档列出了恩布SDK为HTTP REST开发提供的所有API接口,包括名称、调用方式、参数及相关说明等等,适合开发人员在开发过程中参考。

支持开发环境

  • 标准HTTP协议
  • 支持所有标准HTTP协议环境;
  • 支持HTTP GET和HTTP POST二种访问方式;
  • HTTP GET:使用key=value&…格式参数
  • HTTP POST:使用JSON格式参数
  • 返回JSON格式内容。

接口描述

使用HTTP[S] GET接口

HTTP GET是浏览器地址栏输入回车访问方式,参数KEY=VALUE格式,放在URL后面;
访问格式:http://ip/rest.v01.ebweblc.xxx?key=value&...
成功调用,返回JSON格式内容;
调用例子:
https://test-lc.entboost.com/rest.v01.ebweblc.authappid?appid=278573612908&appkey=ec1b9c69094db40d9ada80d657e08cc6
成功返回例子:
{"code":"0","app_online_key":"05423213962293421d957b34668c1ff9010e53186f4974b0"}

使用HTTP[S] POST接口

HTTP POST类似HTML表单提交访问方式,参数JSON格式,放在HTTP包体后面;
成功调用,返回JSON格式内容;
访问格式例子参见HTTP GET接口。


登录验证

概述

登录验证,必须使用https://加密安全连接模式;

验证登录接口

ebweblc.authappid

验证开发者APPID和APPKEY,验证成功会返回app_online_key;
用户开发某些APP应用,部分接口将需要appid和验证成功app_online_key才能正常访问,具体请看接口说明,或联系恩布技术支持。
输入参数 默认值(非空) 描述
appid 开发者APP ID
appkey 开发者APP KEY
返回协议
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述
app_online_key 应用ID在线KEY
url 登录UM地址
appname 可选 登录应用信息
address 可选 登录地址信息

ebweblc.oauth

验证用户帐号;
  • uid和pwd不为空,验证用户ID密码,是否正确;
  • account和pwd不为空,验证用户帐号密码,是否正确;
  • account和oauth_key不为空,用户登录;
  • 其他情况,请求开放验证;
输入参数 默认值(非空) 描述
uid 可选 用户ID
account 可选 用户帐号
pwd 可选 帐号密码
oauth_key 可选 客户端唯一识别验证KEY
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述
oauth_url [开放验证]开放验证登录URL
logon_type [用户登录]登录类型
url [用户登录]登录URL地址
appname [用户登录]登录应用信息
address [用户登录]登录地址信息
account [用户登录]用户帐号
online_key [用户登录]用户在线KEY
acm_key [用户登录]用户管理KEY
username [用户登录]用户名称
description [用户登录]备注信息
setting [用户登录]个人设置
default_member_code [用户登录]个人默认群组成员代码


ebweblc.logonvisitor

游客登录;
输入参数 默认值(非空) 描述
req_code 可选 开放验证登录请求码
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述
logon_type [用户登录]登录类型
url [用户登录]用户管理服务URL
appname [用户登录]用户管理应用信息
uid [用户登录]用户ID
account [用户登录]用户帐号
online_key [用户登录]用户在线密钥
acm_key [用户登录]用户管理KEY

ebweblc.logonaccount

用户登录;
account支持以下各种不同帐号格式:
xx@xxx邮箱帐号、1开头11位数字手机号码帐号,900xxx*ext客服号码帐号和用户数字ID帐号;
输入参数 默认值(非空) 描述
req_code 可选 开放验证登录请求码
account 可选 用户账号
pwd 可选 账号密码
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述
logon_type [用户登录]登录类型
url [用户登录]用户管理服务URL
appname [用户登录]用户管理应用信息
uid [用户登录]用户ID
account [用户登录]用户帐号
online_key [用户登录]用户在线密钥
acm_key [用户登录]用户管理密钥
username [用户登录]用户名称
description [用户登录]备注信息
setting [用户登录]个人设置
default_member_code [用户登录]个人默认群组成员代码

验证密码接口

ebweblc.regauth

验证新注册帐号;
输入参数 默认值(非空) 描述
uid 用户ID
reg_code 注册代码
reset_pwd 可选 重设密码;空不重设密码;
auth_only 默认:0 可选 1:只查询,不验证; 2:注册验证;
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebweblc.findpwd

请求找回密码,调用成功用户邮箱会收到一条重设密码邮件,邮件带串32位加密字符串,用于找回密码key使用;邮件30分钟内有效;
account支持以下各种不同帐号格式:
xx@xxx邮箱帐号、1开头11位数字手机号码帐号,900xxx*ext客服号码帐号和用户数字ID帐号;
输入参数 默认值(非空) 描述
account 可选 邮箱帐号
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebweblc.resetpwd

请求找回密码或重设密码;
找回密码KEY(key)、修改指定帐号密码(account、cur_pwd)二选一;
account支持以下各种不同帐号格式:
xx@xxx邮箱帐号、1开头11位数字手机号码帐号,900xxx*ext客服号码帐号和用户数字ID帐号;
输入参数 默认值(非空) 描述
key 可选1 找回密码KEY
account 可选2-1 指定修改密码帐号
cur_pwd 可选2-2 指定帐号旧密码
reset_pwd 可选 重设密码;空只验证,不重设密码;
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

用户管理

状态管理接口

ebwebum.online

用户验证成功后,登记在线状态;或者更新个人在线状态;
输入参数 默认值(非空) 描述
logon_type 登录类型
uid 用户ID
online_key 验证成功在线KEY
line_state 可选 在线状态
appname 登录应用信息
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebum.offline

用户下线;
输入参数 默认值(非空) 描述
uid 用户ID
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

联系人管理接口

ebwebum.loadcontact

加载个人联系人资料;
输入参数 默认值(非空) 描述
uid 用户ID
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述
contacts 联系人信息数组,结构如下:
contact 联系人帐号
group 分组
name 联系人名称
phone 手机号码
email 邮箱
address 地址
description 描述信息
company 公司名称
job_title 职位
tel 电话
fax 传真
url 网址

ebwebum.editcontact

编辑个人联系人资料,contact联系人邮箱帐号不存在新建;
输入参数 默认值(非空) 描述
uid 用户ID
contact 联系人帐号
group 分组
name 联系人名称
phone 手机号码
email 邮箱
address 地址
description 描述信息
company 公司名称
job_title 职位
tel 电话
fax 传真
url 网址
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebum.deletecontact

删除个人联系人资料;
输入参数 默认值(非空) 描述
uid 用户ID
contact 联系人帐号
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

组织结构接口

ebwebum.loadorg

企业员工:加载企业组织结构,头像、表情等;
注册用户:加载固定群组信息,头像、表情等;
游客用户:加载头像,表情资源等;
输入参数 默认值(非空) 描述
uid 用户ID
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述
enterprise_info 公司信息,结构如下:
enterprise_code 企业代码
enterprise_name 企业名称
description 描述信息
phone 联系电话
fax 传真
email 邮箱
url 网址
address 地址
create_time 注册时间
create_uid 注册人UID
groups 群(部门、群组、讨论组)结构数组;结构如下:
enterprise_code 企业代码,空为个人群组,讨论组
group_code 群代码
group_name 群名称
parent_code 上级群代码
description 群描述,(公告)
phone 联系电话
fax 传真
email 邮箱
url 网址
address 地址
create_time 创建时间
create_uid 创建人UID
group_type 群类型,详见附录
members 群成员(部门员工)结构数组;结构如下:
group_code 群代码
member_code 成员代码
member_account 成员帐号
user_name 用户名称
job_title 职位
job_position 岗位
phone 手机号码
fax 传真
tel 电话
email 邮箱
address 地址
description 个人描述
gender 性别,1男;2女
birthday 生日
line_state 当前在线状态
head_file 头像文件URL
emotions 头像表情结构数组;结构如下:
resid 资源编号
server 服务器
appname APP NAME
index 显示排序
type 类别,默认0
res_type 资源类型;3头像;6表情

ebwebum.loadinfo

加载离线信息,离线信息通过hb长轮询连接返回;
输入参数 默认值(非空) 描述
uid 用户ID
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

呼叫会话接口

ebwebum.callaccount

呼叫用户to_account(帐号)和to_mid(成员ID)二选一必填。
输入参数 默认值(非空) 描述
uid 用户ID
to_account 可选 呼叫对方邮箱帐号
to_mid 可选 呼叫对方成员ID
exist_call_id 可选 邀请对方进入现存会话ID;空为新会话;
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebum.callgroup

发起部门(群组)呼叫。
输入参数 默认值(非空) 描述
uid 用户ID
group_code 部门(群组)代码
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebum.callack

响应呼叫,接收或拒绝会话。
输入参数 默认值(非空) 描述
uid 用户ID
call_id 呼叫ID
ack_type 1 响应类型:1:接受呼叫;2:拒绝呼叫
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebum.hangup

挂断或退出会话。
输入参数 默认值(非空) 描述
uid 用户ID
call_id 呼叫ID
hangup 0 是否挂断会话:0:退出会话;1:挂断会话;
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

长轮询心跳接口

ebwebum.hb

ebwebum.online登记在线状态后,保持长连接心跳,同时查询最新数据;
服务端超过二分钟没有收到心跳数据,将会抛弃掉当前连接,清空上线状态;
ebwebum.online无需传入参数
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:0成功,错误值见附录
msg 消息类型:详见附录
error [错误]错误描述
call_info [会话]会话结构信息
call_info结构:
输入参数 默认值(非空) 描述
call_id 呼叫编号
from_uid 对方用户ID
from_account 对方帐号
group_code 群组(部门)编码
url [会话连接]聊天服务URL
appname [会话连接]聊天应用名称
chat_id [会话连接]聊天编号
chat_key [会话连接]聊天密钥
offline_user [会话连接]是否离线用户 1/0


聊天会话

概述

聊天会话管理接口;

聊天会话接口

ebwebcm.enter

进入聊天会话;
输入参数 默认值(非空) 描述
logon_type 登录类型
from_uid 用户UID
chat_id 聊天编号
chat_key 聊天密钥
off_uid 可选 离线用户UID
call_id 呼叫编号
group_code 可选 群组(部门)编码
appname 聊天应用信息
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebcm.exit

退出聊天会话;
输入参数 默认值(非空) 描述
chat_id 聊天编号


返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebcm.sendtext

发送文本信息;
输入参数 默认值(非空) 描述
chat_id 聊天编号
text 文本信息
to_uid 可选 群组会话只发给某个UID
private 可选 群组会话,发私聊信息 0/1
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebcm.sendrich

发送图文混排RICH信息;
该接口访问只支持JSON格式参数,不支持HTTP key=value格式;
输入参数 默认值(非空) 描述
chat_id 聊天编号
text 文本信息
to_uid 可选 群组会话只发给某个UID
private 可选 群组会话,发私聊信息 0/1
rich_info [会话]RICH信息结构数组
rich_info结构;
输入参数 默认值(非空) 描述
text 文本信息
res 表情信息;格式:[resid];[server];[appname]
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

长轮询心跳接口

ebwebcm.hb

ebwebcm.enter进入会话后,保持长连接心跳,查询最新聊天信息;
服务端超过二分钟没有收到心跳数据,将会抛弃掉当前连接,通知退出会话事件给会话其他成员;
通过长轮询心跳接口,实时接收会话的聊天信息;
输入参数 默认值(非空) 描述
chat_id 聊天编号
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
msg 消息类型,详见附录
error [错误]错误描述
from_uid 可选 聊天信息发送帐号
from_account 可选 聊天信息发送UID
to_account 可选 聊天信息接收帐号
private 可选 [聊天信息]私聊
rich_info [会话]RICH信息结构数组
rich_info结构;
输入参数 默认值(非空) 描述
text 文本信息
res 表情HTTP URL
img 屏幕截图HTTP URL


资源管理

概述

主要包括表情、头像、聊天截图等;

资源管理接口

ebwebcm.res

加载(显示)在线资源(表情、头像或其他文件);
输入参数 默认值(非空) 描述
resid 可选 头像、表情资源编号
file 可选 资源文件名称


AP应用中心

概述

通过第三方应用中心,实现更多扩展功能。

管理接口

ebwebap.on

应用登记在线,成功上线,自动加载应用离线消息;
app online key由eb_l_logon登录成功获取;
输入参数 默认值(非空) 描述
app_id 应用ID
app_online_key 应用在线KEY,通过ebweblc.authappid接口获取
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebap.off

应用注销下线;
输入参数 默认值(非空) 描述
app_id 应用ID
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

ebwebap.msg

给某个APPID发送消息。

输入参数 默认值(非空) 描述
app_id 应用ID
to_app_id 消息接收应用ID
uid 0 用户ID
account "" 邮箱帐号
type 0 消息类型
name "" 消息名称
content "" 消息内容
off_save 1 是否保存应用离线信息:1:保存离线信息;0:不保存离线信息
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述
msg_id [成功]消息ID

ebwebap.mack

响应某条接收消息。
输入参数 默认值(非空) 描述
app_id 应用ID
msg_id 消息ID
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
error [错误]错误描述

长轮询心跳接口

ebwebap.hb

ebwebap.on应用上线后,保持长连接心跳,查询最新APP信息;
服务端超过二分钟没有收到心跳数据,将会抛弃掉当前连接;
输入参数 默认值(非空) 描述
app_id 应用ID
返回协议;
输入参数 默认值(非空) 描述
code 返回状态:见附录
msg 消息类型,详见附录
error [错误]错误描述
msg_info 结构 收到消息
msg_info结构;
输入参数 默认值(非空) 描述
from_app_id 消息来源应用ID
uid 0 用户ID
account "" 邮箱帐号
type 0 消息类型
name "" 消息名称
content "" 消息内容
time "" 离线消息时间,空为当前时间


附录

在线状态

typedef enum EB_USER_LINE_STATE {

EB_LINE_STATE_UNKNOWN
, EB_LINE_STATE_ONLINE // 在线
, EB_LINE_STATE_OFFLINE // 离线
, EB_LINE_STATE_BUSY // 忙
, EB_LINE_STATE_AWAY // 离开

};

性别类型

typedef enum EB_GENDER_TYPE {

EB_GENDER_UNKNOWN
, EB_GENDER_MALE
, EB_GENDER_FEMALE

};

群组类型

typedef enum EB_GROUP_TYPE {

EB_GROUP_TYPE_DEPARTMENT // 企业部门(由公司人员设定,不能随意添加用户,或退出)
, EB_GROUP_TYPE_PROJECT // 项目组(同上)
, EB_GROUP_TYPE_GROUP // 固定群组(所有人可以创建,管理员随时添加成员,或退出)
, EB_GROUP_TYPE_TEMP = 9 // 临时讨论组(由聊天成员动态创建,所有人随时添加成员,或退出)

};

消息类型

WM_USER=0;
EB_WM_UNKNOWN = 0
, EB_WM_APPID_SUCCESS = WM_USER+0x101
, EB_WM_APPID_ERROR
, EB_WM_LOGON_APPCENTER
, EB_WM_LOGOUT_APPCENTER
, EB_WM_AP_MSG
, EB_WM_REGISTER_RESPONSE
, EB_WM_EDITINFO_RESPONSE
, EB_WM_USER_STATE_CHANGE
, EB_WM_USER_HEAD_CHANGE
, EB_WM_OAUTH_FORWARD
, EB_WM_LOGON_SUCCESS
, EB_WM_LOGON_TIMEOUT
, EB_WM_LOGON_ERROR
, EB_WM_ONLINE_ANOTHER
, EB_WM_LOGOUT
/*==========================================================
会话
===========================================================*/
// call_info
, EB_WM_CALL_INCOMING = WM_USER+0x201
, EB_WM_CALL_ALERTING
, EB_WM_CALL_BUSY
, EB_WM_CALL_HANGUP
, EB_WM_CALL_ERROR
, EB_WM_CALL_CONNECTED
/*==========================================================
视频
===========================================================*/
, EB_WM_V_REQUEST_RESPONSE = WM_USER+0x211
, EB_WM_V_ACK_RESPONSE
, EB_WM_VIDEO_REQUEST
, EB_WM_VIDEO_ACCEPT
, EB_WM_VIDEO_REJECT
, EB_WM_VIDEO_CLOSE
/*==========================================================
组织结构
===========================================================*/
, EB_WM_ENTERPRISE_INFO = WM_USER+0x301
, EB_WM_GROUP_INFO
, EB_WM_GROUP_DELETE
, EB_WM_GROUP_EDIT_ERROR
, EB_WM_REMOVE_GROUP
, EB_WM_EXIT_GROUP
, EB_WM_MEMBER_INFO
, EB_WM_MEMBER_DELETE
, EB_WM_MEMBER_EDIT_ERROR
/*==========================================================
通讯录(联系人)
===========================================================*/
, EB_WM_CONTACT_INFO = WM_USER+0x311
, EB_WM_CONTACT_DELETE
, EB_WM_RESOURCE_INFO
, EB_WM_RESOURCE_DELETE
, EB_WM_RESOURCE_MOVE
, EB_WM_NEW_VERSION = WM_USER+0x401
, EB_WM_SERVER_CHENGE = WM_USER+0x411
/*==========================================================
聊天会话
===========================================================*/
CR_WM_ENTER_ROOM = WM_USER+0x1101
, CR_WM_EXIT_ROOM
/*
const CCrAccountInfo* pAccountInfo = (const CCrAccountInfo*)wParam;
*/
, CR_WM_USER_ENTER_ROOM
, CR_WM_USER_EXIT_ROOM
/*
const CCrRichInfo * pRichInfo = (const CCrRichInfo*)wParam;
*/
, CR_WM_SEND_RICH = WM_USER+0x1111
, CR_WM_RECEIVE_RICH
/*
const CCrFileInfo * pCrFileInfo = (const CCrFileInfo*)wParam;
*/
, CR_WM_SENDING_FILE
, CR_WM_SENDED_FILE
, CR_WM_CANCEL_FILE
, CR_WM_RECEIVING_FILE
, CR_WM_RECEIVED_FILE
/*
const CChatRoomFilePercent * pChatRoomFilePercent = (const CChatRoomFilePercent*)wParam;
*/
, CR_WM_FILE_PERCENT
// const CCrInfo* pParameter = (const CCrInfo*)wp;
, CR_WM_INVALIDATE_SESSION = WM_USER+0x1131
, CR_WM_ENTER_ANOTHER

返回状态码

/*========================================================== 状态码 ===========================================================*/

typedef enum EB_STATE_CODE {

EB_STATE_OK = 0
, EB_STATE_ERROR = 1
, EB_STATE_NOT_AUTH_ERROR // 没有权限
, EB_STATE_ACC_PWD_ERROR // 帐号或密码错误
, EB_STATE_NEED_RESEND // 需要重发数据
, EB_STATE_TIMEOUT_ERROR // 超时错误
, EB_STATE_EXIST_OFFLINE_MSG // 存在离线消息
, EB_STATE_USER_OFFLINE // 用户离线状况
, EB_STATE_USER_BUSY // 用户线路忙
, EB_STATE_USER_HANGUP // 用户挂断会话
, EB_STATE_OAUTH_FORWARD // OAUTH转发
, EB_STATE_UNAUTH_ERROR // 未验证错误
, EB_STATE_PARAMETER_ERROR = 15 // 参数错误
, EB_STATE_DATABASE_ERROR // 数据库操作错误
, EB_STATE_NEW_VERSION // 新版本
, EB_STATE_FILE_ALREADY_EXIST // 文件已经存在
, EB_STATE_ACCOUNT_NOT_EXIST = 20 // 帐号不存在
, EB_STATE_ACCOUNT_ALREADY_EXIST // 帐号已经存在
, EB_STATE_ACCOUNT_DISABLE_OFFCALL // 禁止离线会话
, EB_STATE_ACCOUNT_DISABLE_EXTCALL // 禁止外部会话
, EB_STATE_ENTERPRISE_ALREADY_EXIST = 30 // 公司名称已经存在
, EB_STATE_ENTERPRISE_NOT_EXIST // 没有公司信息(企业不存在)
, EB_STATE_DEP_NOT_EXIST // 不存在群组(部门)
, EB_STATE_EXIST_SUB_DEPARTMENT // 存在子部门
, EB_STATE_DEP_ACC_ERROR // 群组或成员不存在
, EB_STATE_ONLINE_KEY_ERROR = 40
, EB_STATE_UM_KEY_ERROR
, EB_STATE_CM_KEY_ERROR
, EB_STATE_DEVID_KEY_ERROR
, EB_STATE_APPID_KEY_ERROR
, EB_STATE_APP_ONLINE_KEY_TIMEOUT
, EB_STATE_CALL_NOT_EXIST = 50
, EB_STATE_CHAT_NOT_EXIST
, EB_STATE_MSG_NOT_EXIST
, EB_STATE_RES_NOT_EXIST
, EB_STATE_NOT_MEMBER_ERROR
, EB_STATE_ATTACHMENT_NOT_EXIST
, EB_STATE_NO_UM_SERVER = 60
, EB_STATE_NO_CM_SERVER
, EB_STATE_NO_VM_SERVER
, EB_STATE_NO_AP_SERVER

};