Help Center/ Cognitive Engagement Center/ API Reference/ Web Client Access Interface Reference/ Integration Development/ APIs Used in the Multimedia Session Scenario/ Sending a Message (send)

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

View PDF

Sending a Message (send)

Scenario

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

Method

POST

URI

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

Request Description

**Table 1** Request header parameters
No.	Parameter	Type	Mandatory	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	Description
1	reqBody	sendMsgReq	Yes	Request body.

**Table 3** sendMsgReq parameters
No.	Parameter	Type	Mandatory	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. Examples: 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 IMAGE, AUDIO, or VIDEO, the value is fileld, which is objectKey returned by the /ccmessaging/uploadFileStream interface. If mediaType is set to FILE, the value is concatenated by multiple character strings separated by commas (,). The fixed format is fileName,fileSize,fileId,fileType, where the unit of fileSize is byte and fileId indicates the value of objectKey returned by the /ccmessaging/uploadFileStream interface. For example: test_txt.txt,6,7d9fbcdd-e306-4b84-9831-163fb760cca9,txt. If mediaType is set to FILE_IMAGE or FILE_VIDEO, the value is concatenated by multiple character strings separated by commas (,). The fixed format is fileId,mediaType, 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 voices, 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 character 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 through the upload interface","mediaFileType":"Media file type","redirectUrl":"Redirect URL"}. mediaFileType can only be set to img, img/png, or img/jpg. If this parameter is left blank, the default value jpg is used. Either redirectUrl or mediaFileId must be set. Other parameters can be left blank.
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, WEBCARD, and LOCATE.
1.6	senderNickname	String	No	Nickname of the message sender.
1.7	sourceType	String	Yes	Message source type. Set this parameter to CUSTOMER.
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 passed to the robot flow when the robot is connected.

Response Description

Status code: 200

**Table 4** senMsgRsp parameters
No.	Parameter	Type	Description
1.1	resultDesc	String	Result code description. The description varies depending on the scenario. CONNECT message for connecting to an agent If resultCode is 0, the operation is successful. If resultCode is 11, the description is Queuing... If resultCode is 12, the description is The current time is not within the working time of the service agents. If resultCode is 13, the description is No ccucs address available! or connect failed, none channel config found. For other non-0 errors, see "Error Code Reference" in CCUCS Interface Developer Guide. CONNECT message for connecting to the robot If resultCode is 0, the description is connect to robot successfully or process robot multi message successfully. If resultCode is 11, the description is Queuing... If resultCode is 13, the description is Failed to disconnect robot, No ccucs address available!, fail to initialize robot., or connect failed, none channel config found. DISCONNECT message for disconnecting from an agent If resultCode is 0, the description is disconnect successfully. If resultCode is 11, the description is Queuing... If resultCode is 13, the description is disconnect failed., disconnect failed, none channel config found., or disconnect failed, session keep touch failed. DISCONNECT message for disconnecting from the robot If resultCode is 0, the description is Disconnect robot successfully. If resultCode is 11, the description is Queuing... If resultCode is 13, the description is Failed to disconnect robot., disconnect failed, none channel config found., or disconnect failed, session keep touch failed. CHAT message for chatting with an agent If resultCode is 0, the description is sendUserMessage successfully. If resultCode is 3, the description is Incorrect JSON format, content can not be empty, the content Json String must contains mediaFileId or redirectUrl, the content Json String must contains title, or Incorrect mediaFileType. If resultCode is 11, the description is Queuing... If resultCode is 13, the description is sendUserMessage failed., Chat failed because the content is empty., chat failed, none channel config found., or chat failed, send too quick or session keep touch failed. CHAT message for chatting with the robot If resultCode is 0, the description is Failed to disconnect robot, Send message to robot successfully, or process robot multi message successfully. If resultCode is 3, the description is Incorrect JSON format, content can not be empty, the content Json String must contains mediaFileId or redirectUrl, the content Json String must contains title, or Incorrect mediaFileType. If resultCode is 11, the description is Queuing... If resultCode is 13, the description is connect failed, Chat failed because the content is empty., chat failed, none channel config found., or chat failed, send too quick or session keep touch failed. TRANS2AGENT message If resultCode is 13, the description may be transfer to agent failed, none channel config found. If resultCode is 13, the description may be fail to transfer from robot to agent,session keep touch failed. If resultCode is 13, the description may be fail to transfer from robot to agent,it has been agent service. If resultCode is 11, the description is Queuing... If resultCode is 12, the description is The current time is not within the working time of the service agents. If resultCode is 13, the description may be fail to transfer from robot to agent,connect to ccucs failed. If resultCode is 13, the description may be Failed to disconnect robot. If resultCode is 13, the description may be No agents available currently. If resultCode is 0, the description is transfer from robot to agent success. INPUT message If resultCode is 0, the description is sendUserMessage successfully. If resultCode is 11, the description is Queuing... If resultCode is 13, the description may be send inputStatus failed, none channel config found. If resultCode is 13, the description may be This is robot service,this message is prevented! If resultCode is 13, the description may be sendUserMessage failed. If resultCode is 13, the description may be Queuing... If resultCode is 3, the description is as follows: The redirection address is not in the trust list, contact operation staff to add it.
1.2	resultCode	String	Interface return code. The value 0 indicates success, and other values indicate failure.
1.3	offlineMsg	Object	If the offline function is enabled, the value is true. If the offline function is disabled, the AICC does not return this object.
1.3.1	isOfflineStatus	Boolean	This parameter is used by the client to determine whether the user can send messages after the connection fails. This parameter is used in the following scenarios: 1. The user fails to send a message whose controlType is CONNECT. 2. The user fails to send a message whose controlType is CHAT. No session exists. 3. The user sends a message whose controlType is DISCONNECT when waiting in a skill queue.
1.3.2	tipText	String	If isOfflineStatus is true, the offline mode is triggered, and the message is saved.

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": "connect to robot successfully."
}

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 message to robot successfully"
}

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": "transfer from robot to agent success."
}

Scenario: Send a text message to an agent.

Request parameters

{
"content": "This is a text message.",
  "controlType": "CHAT",
  "from": "1678101150955228003",
  "mediaType": "TEXT",
  "senderNickname": "user_lk",
  "sourceType": "CUSTOMER",
  "timestamp": "1688038541395",
  "to": "202303061540344336",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

Response parameters

{
    "resultCode": "0",
    "resultDesc": "sendUserMessage successfully."
}

Scenario: Send an image message to an agent.

Request parameters

{
  "content": "e31d0e44e82f",
  "controlType": "CHAT",
  "from": "lk_line_05",
  "mediaType": "IMAGE",
  "senderNickname": "lk_line_05",
  "sourceType": "CUSTOMER",
  "timestamp": "1688038541395",
  "to": "202303061540640554",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "LINE"
}

Response parameters

{
    "resultCode": "0",
    "resultDesc": "sendUserMessage successfully."
}

Scenario: Send an audio message to an agent.

Request parameters

{
  "content": "157831a24986",
  "controlType": "CHAT",
  "from": "lk_line_05",
  "mediaType": "AUDIO",
  "senderNickname": "lk_line_05",
  "sourceType": "CUSTOMER",
  "timestamp": "1688038541395",
  "to": "202303061540640554",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "LINE"
}

Response parameters

{
    "resultCode": "0",
    "resultDesc": "sendUserMessage successfully."
}

Scenario: Send a video message to an agent.

Request parameters

{
  "content": "765c360ab724",
  "controlType": "CHAT",
  "from": "lk_line_05",
  "mediaType": "VIDEO",
  "senderNickname": "lk_line_05",
  "sourceType": "CUSTOMER",
  "timestamp": "1688038541395",
  "to": "202303061540640554",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "LINE"
}

Response parameters

{
    "resultCode": "0",
    "resultDesc": "sendUserMessage successfully."
}

Scenario: Send a file message to an agent.

Request parameters

{
  "content": "test_txt.txt,6,7d9fbcdd-e306-4b84-9831-163fb760cca9,txt",
  "controlType": "CHAT",
  "from": "1678101150955228003",
  "mediaType": "FILE",
  "senderNickname": "user_lk",
  "sourceType": "CUSTOMER",
  "timestamp": "1688038541395",
  "to": "202303061540344336",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

Response parameters

{
    "resultCode": "0",
    "resultDesc": "sendUserMessage successfully."
}

Scenario: Send a file image message to an agent.

Request parameters

{
  "content": "70d46bb7-2272-43b7-acad-c6f893a79848,png",
  "controlType": "CHAT",
  "from": "1678101150955228003",
  "mediaType": "FILE_IMAGE",
  "senderNickname": "user_lk",
  "sourceType": "CUSTOMER",
  "timestamp": "1688038541395",
  "to": "202303061540344336",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

Response parameters

{
    "resultCode": "0",
    "resultDesc": "sendUserMessage successfully."
}

Scenario: Send a file video message to an agent.

Request parameters

{
  "content": "0471a58b-0323-4b94-bc90-55ff36344471,mp4",
  "controlType": "CHAT",
  "from": "1678101150955228003",
  "mediaType": "FILE_VIDEO",
  "senderNickname": "user_lk",
  "sourceType": "CUSTOMER",
  "timestamp": "1688038541395",
  "to": "202303061540344336",
  "userAgent": null,
  "senderAvatar": null,
  "channel": "WEB"
}

Response parameters

{
    "resultCode": "0",
    "resultDesc": "sendUserMessage successfully."
}

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.****.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": "sendUserMessage successfully."
}
or 
{
    "resultCode": "3",
    "resultDesc": "The redirection address is not in the trust list, contact operation staff to add it."
}

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": "Disconnect robot successfully"
}

Parent topic: APIs Used in the Multimedia Session Scenario

Previous topic: Querying Historical Messages (queryHistoryChatMessage)

Next topic: Sending an Asynchronous Channel Message (sendAsync)

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot