Webhooks

美洽通过 Webhooks 功能将工作台的对话、顾客数据,以回调方式主动同步到你的服务器,你可以基于收到的数据做进一步处理。

Webhooks 是 2021 全新在线客服企业版、旗舰版功能点击我前往工作台设置页。

主题

当主题对应的事件被触发时,美洽会向 Webhook URL 发送请求,你可前往APIs查看请求的完整数据结构。

主题名称业务数据触发事件
创建对话 conversation.createdConversation创建对话
结束对话 conversation.closedConversation手动或自动结束对话
更新对话 conversation.updatedConversation客服修改对话小结
首次分配客服 conversation.scheduledConversation首次分配客服
创建顾客 client.createdClient创建顾客、访客转化为顾客
更新顾客 client.updatedClient在工作台更新顾客参数
删除顾客 client.deletedClient删除顾客
通话结束 cdr.hangupCdr通话结束
机器人通话结束 call_robot.hangupCdr机器人通话结束
工单状态第一次变为处理中 new_ticket.processing_firstnew_ticket工单状态类型第一次变为处理中
状态每一次变为处理中new_ticket.processing_everynew_ticket工单状态类型每一次变为处理中
工单结束 new_ticket.closednew_ticket工单状态类型每一次变为结束
工单回复 new_ticket.commentnew_ticket工单新增回复
美洽提供的主题

请求

请求中,美洽会在 HTTP Header 中增加 Meiqia-Signature,企业需要校验该签名,以验证数据安全性,以下是签名校验的具体流程:

  1. 读取 HTTP 请求的 Body,将其转换为字符串 body_str
  2. body_strsecret 拼接成需要加密的字符串 encrypted_strbody_str 在前, secret 在后;
  3. encrypted_str 进行 SHA1 加密得到 signature_str
  4. sign_str 和 HTTP Header 中的 Meiqia-Signature的值进行比对。

请求示例

POST /api/meiqia/notify HTTP/1.1
Host: 127.0.0.1:5005
User-Agent: Go-http-client/1.1
Content-Length: 3140
Content-Type: application/json; charset=utf-8
Meiqia-Sign: 44cb7f1e544d8830ab0e1feb959b94b3e02eb7e9
Accept-Encoding: gzip

{
    "id": "sub_09e4bee581ffbcd347fcf634e0f99df8_1632648830",   //美洽定义的请求唯一标识
    "event": "conversation.updated",                           //本次请求对应的主题
    "enterprise_token": "09e4bee581ffbcd347fcf634e0f99df8",    //美洽定义的企业 token   
    "created_at": 1632648830,                                  //请求的创建时间
    "conversation": {                                          //请求的业务数据
        "enterprise_id": 97631,
        "dev_client_id": null,
        "page_from_url": "",
        "search_engine": ""
    }
}

响应

状态码描述
200成功,美洽将订阅的主题成功推送到 Webhook URL
状态码

如果没有返回状态码,那么美洽认为本次推送通知失败,暂无重试机制。

通话记录模型

参数类型说明
call_uuidString通话ID
call_typeString通话类型:外呼,来电,呼出转接,呼入转接
start_timeString通话开始时间
end_timeString通话结束时间
statesString通话状态:
外呼状态:主叫未接、被叫未接、接听(双方接听)
来电状态:ivr、队列放弃、振铃未接、接听
answer_wayString接听方式
hangup_dispositionString挂断方
wait_timeInteger振铃等待时长
queue_wait_timeInteger队列等待时长
durationInteger总时长
agent_idInteger客服ID
work_numString客服工号
agent_phoneString客服呼叫坐席账号
agent_evaluatedInteger客服被评价的分数
customer_phoneString顾客号码
customer_attributionString顾客号码归属地
customer_durationInteger顾客通话时长
trunk_numberString中继号码
trunk_number_nameString中继号码别名
record_pathString录音文件
ent_tokenString企业token
user_dataString用户自定义数据

机器人通话记录模型

名称类型是否必须备注其他信息
Billsecinteger非必须format: int64
answer_atstring非必须应答时间format: date-time
answer_statestring必须应答状态:answered:正常接通|not_connected:未接通
billsecstring非必须计费时长
business_idstring非必须业务ID
call_statestring必须呼叫状态:synthesis:待合成|pending:待开始|calling:呼叫中|called:已呼叫|timeout:已超时|replay:待重播|terminated:已终止
calleestring必须被叫号码
callee_attributionstring非必须被叫号码归属地
callerstring必须主叫号码
end_atstring必须挂机时间format: date-time
idinteger非必须format: int64
intent_taginteger []非必须意图标签IDitem 类型: integer
├─非必须
record_filestring非必须录音文件
redirectstring非必须
ring_timestring非必须
skill_namestring必须话术模版名称
start_atstring必须呼叫开始时间format: date-time
task_namestring必须任务名称
uuidstring必须
call_timesinteger必须重播轮次
hangup_dispositioninteger必须挂断方:1-顾客挂断|2-系统挂断
hangup_casestring必须power off – 关机
does not exist – 空号
out of service – 停机
hold on – 通话中
is not reachable – 用户正忙 无法接通
not answer – 无人接听
not in service – 暂停服务
Bad Request – 请求语法错误
Unauthorized – 请求需要用户验证
Payment Required – 保留,可能用于未来使用
Forbidden – 服务器拒绝请求
Not Found – 服务器无法找到请求的资源
Method Not Allowed – 请求方法不被允许
Not Acceptable – 无法生成客户端接受的响应
Proxy Authentication Required – 需要代理服务器认证
Request Timeout – 请求超时
Gone – 请求的资源永久删除
Request Entity Too Large – 请求实体过大
Request-URI Too Long – 请求的URI过长
Unsupported Media Type – 不支持的媒体类型
Unsupported URI Scheme – 不支持的URI方案
Bad Extension – 扩展字段不正确
Temporarily Unavailable – 被叫方暂时不可用
Call/Transaction Does Not Exist – 呼叫/事务不存在
Loop Detected – 检测到循环
Too Many Hops – 跳数过多
Address Incomplete – 地址不完整
Ambiguous – 地址不明确
Busy Here – 被叫方忙
Request Terminated – 请求被终止
Not Acceptable Here – 此处不可接受
Request Pending – 请求等待中

工单业务模型

字段下一级字段数据格式描述
eventString
businessIdLong工单业务ID
contentString回复内容
textContentString回复内容(纯文本)
contentByString回复人
contentAtString回复时间
ticketList工单信息
fieldNameString工单字段name
fieldValueObject工单字段value
displayBoolean字段显示状态
customerobject顾客信息
__follow_sourceString顾客来源
__openidString微信的open_id
addressString地址
ageinteger年龄
commentString备注
contactString联系人
emailString邮箱
enterprise_idinteger顾客所属企业
genderString性别(M:男;W:女)
nameString姓名
qqStringqq
telString电话号码
weiboString微博
weixinString微信
${自定义字段name}String自定义的顾客字段,可能有多个

常见问题

美洽 Webhooks 请求时服务器地址是什么?

127.0.0.1

Updated on 2024年10月9日

本文是否有帮助?

您可能想了解