更新时间:2025-03-07 GMT+08:00

发送消息 (sendAsync)

描述

用户接入座席后,用户侧向座席侧发送渠道异步消息,包括连接,发送输入状态,会话,转人工,断连多种类型消息

接口方法

POST

接口URI

https://域名/apiaccess/ccmessaging/sendAsync,例如域名是https://service.besclouds.com

请求说明

表1 请求头参数

序号

名称

参数类型

是否必选

说明

1

ccmessaging-token

string

True

applyToken接口生成的ccmessaging-token

2

x-app-key

string

True

appKey字段,用户标识,在ApiFabric工具上配置

3

Authorization

string

True

鉴权字段,内容格式为: Bearer +tokenByAKSK接口的返回值中AccessToken(Bearer后有空格)

表2 请求体参数

序号

名称

参数类型

是否必选

说明

1

reqBody

sendMsgReq

True

请求体

表3 sendMsgReq参数结构

序号

名称

参数类型

是否必选

说明

1.1

channel

string

True

客户端发送消息的所属渠道类型,如WEB(WEB客服接入渠道)

1.2

content

string

False

消息内容,视mediaType而定,例如mediaType是TEXT,content就是发送的文本内容,文本内容大小不能超过1K;如果是音视频等媒体,content是fileId,mediaType,fileId为/ccmessaging/uploadFileStream接口返回的objectKey,具体入参为"field,mediaType",如图片为"objectKey,jpg",视频为"objectKey,mp4",音频为"objectKey,mp3",位置为"objectKey,txt",文件下载接口会使用此fileId做文件下载用。

如果mediaType值为WEBCARD,content的值为JSON结构转换的字符串,例如JSON固定结构如下:

{"title":"卡片标题","description":"卡片描述","mediaFileId":"卡片媒体文件ID,通过upload接口返回","mediaFileType":"当前仅支持固定值img,img/png,img/jpg,不填类型默认按jpg","redirectUrl":"跳转地址"

},其中redirectUrl和mediaFileId为二选一必填项,其他项不填可以为空值,具体可参考报文样例:向座席发送网页卡片消息。

说明:

controlType为CONNECT、DISCONNECT、TRANS2AGENT时,该参数为可选。

1.3

controlType

string

True

消息控制类型,如连接(CONNECT),聊天(CHAT),转人工(TRANS2AGENT),用户输入中(INPUT),断开连接(DISCONNECT),已读(READ)

1.4

from

string

True

渠道下发送消息的用户ID,取值范围:1到24位字符串。

1.5

mediaType

string

True

消息媒体类型,包括:文本类型(TEXT),图片类型(IMAGE),音频类型(AUDIO),视频类型(VIDEO),文件类型(FILE),文件图片(FILE_IMAGE),文件视频(FILE_VIDEO),网页卡片消息(WEBCARD)

1.6

senderNickname

string

False

消息发送者的昵称

1.7

sourceType

string

True

消息来源类型

1.8

timestamp

string

False

消息发送时间

1.9

to

string

True

渠道配置ID

1.10

userAgent

string

False

用户客户端类型,取自UserAgent

1.11

senderAvatar

string

False

消息发送者的头像,渠道传输头像URL,最长1024字符

1.12

messageId

string

False

用于标识发送的消息用户的唯一值。最大长度为32。值不能包含逗号“,”。

1.13

transData

string

False

json格式数据,连接机器人的时候传给机器人流程。

响应说明

  • 响应状态码: 200
    表4 senMsgRsp参数结构

    序号

    名称

    参数类型

    是否必选

    说明

    1.1

    resultDesc

    string

    False

    返回结果码描述

    resultCode返回0

    1.2

    resultCode

    string

    True

    接口返回码0

  • 响应状态码: 400

    错误的请求:请检查请求路径及参数。

  • 响应状态码: 401

    未授权:1.请确认是否购买了相关服务。2.请联系客服人员检查您账号的当前状态。

  • 响应状态码: 404

    请求的内容未找到:请检查请求的路径。

  • 响应状态码: 500

    业务失败:请依次确认您请求中各参数的取值。

错误码

无。

报文样例

  • 场景描述:连接机器人

请求参数:

{
  "content": "",
  "controlType": "CONNECT",
  "from": "session_1619573111751_user_1619573111751",
  "mediaType": "TEXT",
  "senderNickname": "user_1619573111751",
  "sourceType": "CUSTOMER",
  "timestamp": "1619573122352",
  "to": "1011577355744904195",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

响应参数:

{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • 场景描述:与机器人交谈请求

请求参数:

{
  "content": "Version",
  "controlType": "CHAT",
  "from": "session_1619573111751_user_1619573111751",
  "mediaType": "TEXT",
  "senderNickname": "user_1619573111751",
  "sourceType": "CUSTOMER",
  "timestamp": "1619573123199",
  "to": "1011577355744904195",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}
响应参数:
{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • 场景描述:机器人转人工请求

请求参数:

{
  "content": "",
  "controlType": "TRANS2AGENT",
  "from": "session_1619573111751_user_1619573111751",
  "mediaType": "TEXT",
  "senderNickname": "user_1619573111751",
  "sourceType": "CUSTOMER",
  "timestamp": "1619573129953",
  "to": "1011577355744904195",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

响应参数:

{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • 场景描述:向座席发送网页卡片消息

请求参数:

{
  "content": "{\"title\":\"测试title 测试title 测试title\",\"description\":\"测试描述 测试描述 测试描述 测试描述\",\"mediaFileId\":\"xxxx-xxxx-xxxx-xxxx-2e171ac78313\",\"mediaFileType\":\"img\",\"redirectUrl\":\"https://www.xxx.com\"}",
  "controlType": "CHAT",
  "from": "session_1619573111751_user_1619573111751",
  "mediaType": "WEBCARD",
  "senderNickname": "user_1619573111751",
  "sourceType": "CUSTOMER",
  "timestamp": "1619573129953",
  "to": "1011577355744904195",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

响应参数:

{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • 场景描述:断连请求

请求参数:

{
  "content": "",
  "controlType": "DISCONNECT",
  "from": "session_1619573842490_user_1619573842490",
  "mediaType": "TEXT",
  "senderNickname": "user_1619573842490",
  "sourceType": "CUSTOMER",
  "timestamp": "1619573854156",
  "to": "1011577355744904195",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

响应参数:

{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}