Updated on 2025-03-31 GMT+08:00

Sending an Asynchronous Channel Message (sendAsync)

Scenario

After a customer is connected to an agent, the customer sends asynchronous channel messages to the agent, including connection, input status, session, transfer-to-manual, and disconnection messages.

Method

POST

URI

https://Domain name/apiaccess/ccmessaging/sendSync (For example, the domain name is https://service.besclouds.com.)

Request Description

Table 1 Request header parameters

No.

Parameter

Type

Mandatory or Not

Description

1

ccmessaging-token

String

Yes

Value of ccmessaging-token generated by the applyToken interface

2

x-app-key

String

Yes

App key, which is the user ID and is configured on the API Fabric

3

Authorization

String

Yes

Authentication field. The format is Bearer {Value of AccessToken returned by the tokenByAkSk interface}. (A space is required after Bearer.)

Table 2 Request body parameter

No.

Parameter

Type

Mandatory or Not

Description

1

reqBody

sendMsgReq

Yes

Request body

Table 3 sendMsgReq parameters

No.

Parameter

Type

Mandatory or Not

Description

1.1

channel

String

Yes

Type of the channel through which the client sends a message, for example, the web channel (web customer service access channel)

1.2

content

String

No

Message content, which varies depending on mediaType. For example, if mediaType is set to TEXT, the value is the text content to be sent. The size of the text content to be sent cannot exceed 1 KB. If mediaType is set to AUDIO, VIDEO, or other media types, the value is in fileId,mediaType format, where fileId indicates the value of objectKey returned by the /ccmessaging/uploadFileStream interface. The value is Value of objectKey,jpg for images, Value of objectKey,mp4 for videos, Value of objectKey,mp3 for audio, and Value of objectKey,txt for locations. The file download interface uses fileId to download a file.

If mediaType is set to WEBCARD, the value is a string converted from the JSON structure. For example, the fixed JSON structure is as follows:

{"title":"Card title","description":"Card description","mediaFileId":"Card media file ID, which is returned by the upload interface","mediaFileType":"Only fixed values img, img/png, and img/jpg are supported. If this parameter is left blank, the default value jpg is used.","redirectUrl":"Redirection URL"}

Either redirectUrl or mediaFileId must be set. Other parameters can be left empty. For details, see the example of sending a web card message to an agent.

NOTE:

This parameter is optional when controlType is set to CONNECT, DISCONNECT, or TRANS2AGENT.

1.3

controlType

String

Yes

Message control type. The options are CONNECT, CHAT, TRANS2AGENT, INPUT, DISCONNECT, and READ.

1.4

from

String

Yes

ID of the user who sends a message through a channel. The value is a string of 1 to 24 characters.

1.5

mediaType

String

Yes

Message media type. The options are TEXT, IMAGE, AUDIO, VIDEO, FILE, FILE_IMAGE, FILE_VIDEO, and WEBCARD.

1.6

senderNickname

String

No

Nickname of the message sender

1.7

sourceType

String

Yes

Message source type

1.8

timestamp

String

No

Time when a message is sent

1.9

to

String

Yes

Channel configuration ID

1.10

userAgent

String

No

User client type, which is obtained from UserAgent

1.11

senderAvatar

String

No

Avatar of the message sender. The value is the avatar transfer URL of the channel and can contain a maximum of 1024 characters.

1.12

messageId

String

No

Unique ID of the user who sends a message. The value can contain a maximum of 32 characters. The value cannot contain commas (,).

1.13

transData

String

No

Data in JSON format, which is transferred to the robot flow when the robot is connected

Response Description

  • Status code: 200
    Table 4 senMsgRsp parameters

    No.

    Parameter

    Type

    Mandatory or Not

    Description

    1.1

    resultDesc

    String

    No

    Result code description.

    The value of resultCode is 0.

    1.2

    resultCode

    String

    Yes

    Return code. The value is 0.

  • Status code: 400

    Incorrect request. Check the request path and parameters.

  • Status code: 401

    Unauthorized operation. 1. Check whether you have purchased related services. 2. Contact customer service to check the status of your account.

  • Status code: 404

    The requested content is not found. Check the request path.

  • Status code: 500

    Business failure. Check the values of parameters in the request.

Error Codes

None

Example

  • Scenario: Send a request for connecting to the robot.

Request parameters:

{
  "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"
}

Response parameters:

{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • Scenario: Send a request for chatting with a robot.

Request parameters:

{
  "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"
}
Response parameters:
{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • Scenario: Send a request for switching from robot service to manual service.

Request parameters:

{
  "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"
}

Response parameters:

{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • Scenario: Send a web card message to an agent.

Request parameters:

{
  "content": "{\"title\":\"Test title\",\"description\":\"Test 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"
}

Response parameters:

{
    "resultCode": "0",
    "resultDesc": "send sendMessageForOpenApiAsync success."
}
  • Scenario: Send a disconnection request.

Request parameters:

{
  "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"
}

Response parameters:

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