客户登录 免费使用
首页 keyboard_arrow_right 使用教程 keyboard_arrow_right 使用 HTTP API 开发访客端聊天界面
使用 HTTP API 开发访客端聊天界面

丁贵金

April 8, 2018

PPMESSAGE 的访客界面和座席界面都支持再开发。

PPMESSAGE访客端支持两种模式的开发:

  • 使用 PPMESSAGE 提供的 JS API 进行开发
  • 使用 PPMESSAGE 提供的 HTTP REST API 进行开发

使用 JS API 比较简单,能够重用 PPMESSAGE 的访客端的界面程序,但是能做的事情有限,主要是针对已有界面的样式的定制和消息的响应。

使用 HTTP REST API,从严格意义上讲不是 RESTFUL API,只是 HTTP 接口,这些接口并没有遵循 REST 的规范。通过这些接口可以完全不依赖于 PPMESSAGE 的原有访客界面,直接可以开发全新的访客界面。但是需要了解 API 的调用细节。比较复杂,但是可以完成各种功能。

基本架构

通讯

PPMESSAGE 后台和前端的通讯方法是通过两种途径完成:

  • 后台提供 API 供前台调用
  • 后台与前台之间通过 WEBSOCKET 连接,通过 WEBSOCKET 向前台推送消息(这个消息比较泛化,不仅仅包括座席消息,还包括一些其他的如座席上线,界面特效等要求前台做出实时改变的消息)

认证

分为 API 认证和 WEBSOCKET 认证:

  • API 认证通过一个 token API 获取 token,这个 token API 不需要认证;所有后续的 API 调用都需要在 HTTP HEADER 中引用这个token

  • WEBSOCKET 认证,在获取 token 后,才能与 WEBSOCKET 建立连接,连接成功后,把 token 通过 WEBSOCKET 发送一个认证消息,WEBSOCKET 才能完成认证,后台才会通过这个 WEBSOCKET 连接向前台推送实时消息

token 24 小时超时,如果这个 token 24 内没有使用,那么就会超时删除,如果一直在使用就永远不过期。

开发准备

  • APP UUID, 即团队 UUID,在 设置 - 开发者 - 开发者秘钥 - 访客端
  • 开发者秘钥,对于访客端开发我们需要需要访客端开发者秘钥,在 设置 - 开发者 - 开发者秘钥 - 访客端

对于访客端,PPMESSAGE 采用 client credentials 的方式,只要能够通过 KEY 确定是 PPMESSAGE 访客端,那么就可以通过认证。

通过认证会通过 HTTP 返回 token。

基本过程

  • 获取 token

  • 创建匿名或者具名访客用户

  • 创建访问设备

  • 获取 APP 信息

  • 连接 WEBSOCKET,并且认证,等待授权通过

  • 创建默认会话

  • 获取默认会话 (轮询)

  • 获取默认会话的消息历史 (分页获取)

  • 收取来自 WEBSOCKET 的消息推送

  • 发送访客输入的消息

PPMESSAGE 后台推送 的 WEBSOCKET 的消息和访客的行为继续驱动前端的运行。

接口参考

  • 接口中除获取 token 接口除外,都需要在 HTTP 请求头中设置 token。形如: Authorization:OAuth ==
  • 除 token 接口外,所有接口返回值都包含 error_code, error_string,error_code 为 0 表示成功,其他值都是失败。
  • 除 token 接口外,所有接口都通过一个 URL 进行请求 /ppquery/PP_QUERY,请求数据封装为 JSON,其形式如: { api_url: 接口名称, api_data: { 接口参数 } }

获取 token

  • 接口名称: token
  • 接口URL:/ppauth/token
  • 请求方式:POST
  • 内容类型(Content-Type):application/x-www-form-urlencoded
  • 接口参数: “grant_type=client_credentials” + “&client_secret=” + window.ppmessage_secret + “&client_id=” + window.ppmessage_key;
参数名称 参数类型 参数含义
grant_type string 必须填写为 client_credentials
client id string 开发者秘钥中的 Client ID
client secret string 开发者秘钥中的 Client Secret

POST 的数据是上述参数的拼接: “grant_type=client_credentials&client_secret=your_client_secret&client_id=your_client_id”。

  • 接口返回:
参数名称 参数类型 参数含义
access_token string 后续接口调用中使用的 token

如果失败,则 HTTP 请求返回 4xx,并且没有 access token。

连接 WEBSOCKET

WEBSOCKET 地址: /pcsocket/WS

连接 WEBSOCKET 之后要发送 auth 消息数据包进行认证,auth 消息数据包中包含 token 和访客的基本信息,没有通过认证的 WEBSOCKET 是不会有消息的,并且会在10秒内自动关闭。

访客与服务器之间的 WEBSOCKET 要保持连接,因为访客端和服务器可能经过了很多网络设备,在没有数据通讯的情况下,在几十秒钟内可能就会被断掉,访客端需要简单回复 PONG 消息,即可维护 WEBSOCKET 连接的有效性,当然还是有各种情况会断开,这种断开只需要提示使用者即可,无需自动处理。

创建匿名用户

  • 接口名称: PPCOM_CREATE_ANONYMOUS_USER
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
ppcom_trace_uuid string 一个64字节以内的跟踪 UUID,应该是一个 cookie,唯一区分每一个匿名访客
user_channel string CHANNEL_WEB 对于网页或者 H5访客,CHANNEL_APP 对于APP 访客
  • 接口返回:
参数名称 参数类型 参数含义
uuid string 访客 UUID,这是 PPMESSAGE 后台根据 ppcom trace uuid 一一映射的 UUID
user_email string 访客电子邮件地址,访客有可能在含有表单的消息中提交过自己的邮件地址
user_mobile string 访客手机号码,访客可能在含有表单的消息中提交过自己的手机号码
user_fullname string 访客有可能在含有表单的消息中提交过自己的名字

一般来说,访客都是匿名访客,PPMESSAGE 后台会自动根据访客 IP 进行归属地查找,归属地查找也是一个大致范围,不是绝对精确,仅供参考。

创建具名用户

  • 接口名称: PPCOM_GET_USER_UUID
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
ppcom_trace_uuid string 访问的唯一 UUID,一般指 COOKIE,小于64字节
ent_user_id string 具名访客的 ID,具名访客是指开发者拥有访客数据,这个 ID 是在开发者的数据库中对访客进行区分的标识
ent_user_name string 访客名称
ent_user_icon string 访客图标
ent_user_create_time int 访客创建时间,时间戳,以毫秒为单位
ent_company_id string 访客公司 ID,是开发者拥有数据库中访客公司的唯一标识
ent_company_name string 访客公司名称简称
ent_company_fullname string 访客公司名称全称
user_channel string 如果是网页(H5)访客CHANNE_WEB,如果是 APP 访客 CHANNE_APP

具名访客的意义在于,如果你在业务系统中使用 PPMESSAGE 的访客端,那么你的客户应该是具名,他们有自己的账号,所以才能使用您的业务系统。如何将您业务系统的信息带入 PPMESSAGE ,就要通过这个接口。这个接口与 PPCOM CREATE ANONYMOUS 很显然是互斥的,二者一定选其一,不会同时使用。

  • 接口返回:
参数名称 参数类型 参数含义
uuid string 访客 UUID
user_fullname string 访客名称
user_email string 邮件地址
user_mobile string 移动电话

创建设备

  • 接口名称: PPCOM_CREATE_DEVICE
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
user_uuid string 访客的 UUID
device_ostype string OS
is_browser_device boolean 是否浏览器
device_ios_token string ios push token
device_android_fcmtoekn string android firebase cloud token
  • OSTYPE
OS = Enum([
    "AND", # ANDROID
    "IOS", # IOS
    "ANB", # ANDROID BROWSER
    "IOB", # IOS BROWSER
    "WIP", # WIN PHONE
    "MAC", # MAC OS X PC
    "LIN", # LINUX PC
    "WIN", # WINDOWS PC
    "MAB", # MAC BROWSER
    "LIB", # LINUX BROWSER
    "WIB", # WINDOWS BROWSER
    "W32", # WINDOWS 32 BIT
    "W64", # WINDOWS 64 BIT
])

  • 接口返回:
参数名称 参数类型 参数含义
uuid string device uuid

设备 UUID,访客 UUID,APP UUID 将会在下面的 API 调用中反复使用

创建默认会话

  • 接口名称: PPCOM_CREATE_DEFAULT_CONVERSATION
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
user_uuid string 访客的 UUID
device_uuid string 设备的 UUID
  • 接口返回:
参数名称 参数类型 参数含义

只返回 error code,这个接口必须在 WEBSOCKET 认证通过之后调用

获取默认会话

  • 接口名称: PPCOM_GET_DEFAULT_CONVERSATION
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
user_uuid string 访客的 UUID
device_uuid string 设备的 UUID
  • 接口返回:
参数名称 参数类型 参数含义
uuid string 会话 UUID
createtime string YYYY-MM-DDTHH:mm:ss UTC时间,使用的时候按照本地时区转换
updatetime string YYYY-MM-DDTHH:mm:ss UTC时间,使用时候按照本地时区转换
conversation_users object 会话中用户的信息,不包含访客自己

会话中用户的信息:

{
  uuid: "用户 UUID", 
  user_fullname: "用户名称",
  user_icon:"用户头像"
}

这里面的用户,就是座席信息

分页获取会话消息

  • 接口名称: PP_PAGE_MESSAGE_HISTORY
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
user_uuid string 访客的 UUID
conversation_uuid string 会话的 UUID
offset int 从哪开始 0 为第一个, 逆序
size int 页面大小
  • 接口返回:
参数名称 参数类型 参数含义
list array 消息列表
total int 总共有多少消息

每个会话的数据结构:

{
    uuid: 消息 UUID,
    body: 消息体,
    from_user: 消息发送者
}

发送消息

  • 接口名称: PP_SEND_MESSAGE
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
from_uuid string 访客 UUID
conversation_uuid string 会话的 UUID
message_type string 必须是 NOTI
message_subtype string TEXT/IMAGE/FILE/MARKDOWN/LINK/AUDIO
body string TEXT/IMAGE/FILE/MARKDOWN/LINK/AUDIO 不相同

当消息 subtype 是 TEXT 或者 MARKDOWN,body 是消息内容,如果是其他则为 对应的 json 字符串

  • 接口返回:
参数名称 参数类型 参数含义

一般不会使用这个接口进行消息发送,而是使用 WEBSOCKET 直接向服务器推送消息

发送事件消息

  • 接口名称: PP_SEND_EVENT_MESSAGE
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:

    _app_uuid = _body.get("app_uuid")
    _conversation_uuid = _body.get("conversation_uuid")
    _user_uuid = _body.get("user_uuid")
    _event_body = _body.get("event_body")
    _is_browser_message = _body.get("is_browser_message") or False
    
参数名称 参数类型 参数含义
app_uuid string APP UUID
user_uuid string 访客的 UUID
conversation_uuid string 会话的 UUID
is_browser_message boolean 是否浏览器事件
event_body json string 消息的 json string

访客打开关闭聊天组件,进入退出某个页面的事件消息

  • 接口返回:
参数名称 参数类型 参数含义

发送跟踪事件

  • 接口名称: PPCOM_TRACK_EVENT
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
user_uuid string 访客的 UUID
device_uuid string 设备 UUID
event_uuid string event UUID
event_data string event 数据
event_timestamp int 毫秒时间戳
  • 接口返回:
参数名称 参数类型 参数含义

设置访客变量

  • 接口名称: PPCOM_SET_VAR
  • 接口URL:/ppquery/PP_QUERY
  • 请求方式:POST
  • 内容类型(Content-Type):application/json
  • 接口参数:
参数名称 参数类型 参数含义
app_uuid string APP UUID
user_uuid string 访客 UUID
var_name string 变量名称
var_value string 变量值
  • 接口返回:
参数名称 参数类型 参数含义

可以设置 user_fullname, extrafield 开头的任何自定义变量

WEBSOCKET 消息

通过WEBSOCKET,访客端可以与 PPMESSAGE 服务端进行实时的数据交互。主要传递的消息是:

  • 访客认证消息
  • 认证回应消息
  • 访客发送给客服的会话消息
  • 客服发送给访客的会话消息
  • 确认消息
  • 系统发送给访客的PING消息
  • 访客发送给系统的PONG消息

访客认证消息

{
"type":"auth",
"api_token":"ZTBmN2I1M2QxN2RhNjI1ZjYxOTEyMTMwYzA0OTM0YmE1MzM2NGU2Yw==",
"app_uuid":"caac93e6-2d8b-11e8-9b51-ac87a318f324",
"user_uuid":"3b4eb9b5-3ae6-11e8-a599-ac87a318f324",
"device_uuid":"3b7d4221-3ae6-11e8-8297-ac87a318f324",
"extra_data":{
"user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/65.0.3325.181 Safari/537.36",
"page_title":"PPMESSAGE",
"page_url":"http://192.168.0.102:8945/ppcom/enterprise/eyJ1dWlkIjoiY2FhYzkzZTYtMmQ4Yi0xMWU4LTliNTEtYWM4N2EzMThmMzI0IiwiYXBwX25hbWUiOiJQUE1FU1NBR0UifQ==",
"page_origin":"http://192.168.0.102:8945",
"browser_os":"Mac OS X",
"browser_os_version":"10_13_4",
"browser_name":"Chrome","browser_version":"65.0.3325.181",
"browser_language":"zh-CN",
"language_override":"zh-CN",
"document_referrer":"http://192.168.0.102:8945/ppkefu/",
"search_keyword":null
},
"is_sider_device":false,
"is_mobile_device":false,
"is_service_user":false
}

认证回应消息

{
"what": "AUTH", 
"code": 0,
 "type": "ACK",
 "reason": "SUCCESS",
 "extra": null
}

访客发送给座席的会话消息

{
"type":"send",
"send":{
"conversation_uuid":"3bfa11f8-3ae6-11e8-b186-ac87a318f324",
"to_uuid":"3bfa11f8-3ae6-11e8-b186-ac87a318f324",
"to_type":"DU",
"conversation_type":"P2S",
"message_type":"NOTI",
"message_subtype":"TEXT",
"from_uuid":"3b4eb9b5-3ae6-11e8-a599-ac87a318f324",
"device_uuid":"3b7d4221-3ae6-11e8-8297-ac87a318f324",
"uuid":"e3107d72-2697-4dd1-e2b5-9de442e2aeba",
"from_type":"DU",
"app_uuid":"caac93e6-2d8b-11e8-9b51-ac87a318f324",
"is_browser_message":true,
"is_service_user":false,
"message_body":"Hello World"
}
}

座席发送给访客的会话消息

{
"msg": {
"fi": "caac9500-2d8b-11e8-861b-ac87a318f324",
 "ci": "3bfa11f8-3ae6-11e8-b186-ac87a318f324",
 "bo": "World is good!",
 "ft": "DU",
 "tt": "DU",
 "ir": false,
 "pid": "3540a68c-3ae7-11e8-a8d6-ac87a318f324",
 "ts": 1523162533.4607,
 "mt": "NOTI",
 "tl": null, 
"im": false,
 "ms": "TEXT",
 "from_user": {
"updatetime": 1523162533,
 "uuid": "caac9500-2d8b-11e8-861b-ac87a318f324",
 "user_fullname": "Guijin Ding",
 "user_type": "SERVICE_USER",
 "user_icon": "http://192.168.0.102:8945/ppidenticon/ppidenticon/e3587f54-2f39-11e8-9012-ac87a318f324", 
"user_channel": null,
 "user_email": "dingguijin@gmail.com"
},
 "ia": false,
 "ti": "",
 "ic": false,
 "ie": false,
 "id": "0e920c2b-0090-4958-ddbc-c562ffa7d692",
 "ct": ""
},
 "type": "MSG"
}

确认消息

{
"what": "SEND", 
"code": 0,
 "type": "ACK",
 "reason": "SUCCESS",
 "extra": {
"conversation_uuid": "3bfa11f8-3ae6-11e8-b186-ac87a318f324",
 "uuid": "e3107d72-2697-4dd1-e2b5-9de442e2aeba"
}
}

系统发送给访客的PING消息

{"type": "PING"}

访客发送给系统的PONG消息

{"type":"PONG"}