Post Answers

Posts the bot’s answers to clients’ questions. After a message is sent to the bot (MESSAGE webhook), you need to send the bot’s response to that message to the POST endpoint /api/v1/chatbot.

There are four types of answers:

  • By threadsClientId – Internal client ID, applicable for both authorized and unauthorized clients. This type is preferable for all new integrations.
  • By questionId – Used when the identifier of a specific question is known.
  • By sessionId and questionIndex – Used when questionID is unknown, and you need to answer to specify the index of the question in the session thread.
  • 4. (Deprecated) By clientId – More often used for authorized clients when it is required to write to a client; it is not tied to a specific question.

For attachments, the image name must contain the file extension, or the file type (for example, image/jpg) must be specified for the file to be displayed correctly to the client.

If a message with the EMAIL type is received, it must be answered by sessionId and questionIndex,because one email client might have several active threads created on the email subject, so you need to knowexactly which thread to send the message to.

Request Parameters

ParameterTypeDescription
textstringBot’s reply to the message from the client. Required if formattedText is not used.
answerIdstringUnique identifier of the reply from the bot, a string up to 4000 characters.
formattedTextstring (optional)Bot’s reply to the message from the client. The reply might contain Markdown syntax. It is recommended to pass the text representation of the response to the “text” field for display in the user interface.
clientIdstring (optional, deprecated)External client ID. The parameter has been deprecated, use threadsClientId instead.
threadsClientIdlong (optional)Internal client ID
sessionIdstring (optional)Internal thread ID (ID of the client’s chat with the agent)
questionIdnumber (optional)Internal ID of the client’s message
questionIndexnumber (optional)Index of the required client’s message in the thread (chat)
segmentationInfoMap<String, String>Additional parameters for changing segmentation (used within both custom and out-of-the-box segments). The segmentation parameter personal_manager is available out-of-the-box. If the agent’s login was passed in this parameter and the route for the segment with this parameter is configured in the system, the client’s threads are distributed via the corresponding route to personal managers (agents).
receivedAtstring (required)Time when the message was received in the UTC format: yyyy-MM-dd’T’HH:mm:ss.SSS’Z’
attachmentsarray (optional)Fields:

url – Link to an attached file, a string up to 4,000 characters
name – Attachment name, a string up to 1,000 characters
type – Attachment type, a string up to 256 characters
quickRepliesarray (optional)Fields:

type – Quick reply type. Possible values are: TEXT for text messages, WEBVIEW for webviews.
text – Message text, a string up to 4,000 characters.
shown_text – Text content, optional parameter, a string up to 2000 characters. It’s only used combined with the text parameter. If the parameter is specified, it’s sent as a client message after clicking the quick reply button.
callback_data – Text content, optional parameter, a string up to 255 characters. The name of the event that will be passed when the JS SDK API is called for subsequent processing by the customer on the site side.
imageUrl – Button icon URL, a string up to 4,000 characters.
url – Link to an attached file, string up to 4,000 characters.

The length and number of quick replies are customized in the database: message.max-quick-repliesmessage.max-quick-reply-length
codestringValues:

UNCLEAR_QUESTION – The question is unclear to the chatbot, so it forwards the conversation to a human operator (i.e, an agent).
SWITCH_TO_HUMAN – The bot got the request to forward the conversation to a human operator (i.e, an agent).
SUCCESS – The bot successfully handled a client’s message and sent a reply.
userIdsset<long>(необязательно)List of identifiers of agents to whom the thread must be assigned after it is transferred from the current bot. This value must be passed along with code = SWITCH_TO_HUMAN.
skillIdsset<long>(необязательно)List of skill identifiers that agents, to whom the thread must be assigned after it is transferred from the current bot, must have. This value must be passed along with code = SWITCH_TO_HUMAN.
unitIdsset<long>(необязательно)List of department identifiers to which agents, to whom the thread must be assigned after it is transferred from the current bot, must belong. This value must be passed along with code = SWITCH_TO_HUMAN.
settingsobject (optional)Additional settings for the message
settings.blockInputboolean (optional)The parameter that defines whether the message input field is blocked (true – blocked, false – not blocked). Only works with quick replies.
settings.maskedboolean (optional)The parameter that is used to mask digits in linked client messages (true – masked, false – not masked).

Example: Post Answers by clientId

Curl Example

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {
        "key": "value"
    },
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.291Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": false,
        "masked": true
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}'

HTTP Request

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 474
Host: localhost: 8080
{
    "segmentationInfo": {
        "key": "value"
    },
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.291Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": false,
        "masked": true
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}

Example of a Successful HTTP Response

HTTP/1.1 200 OK

Example: Post Answers by questionId

Curl Example

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {
        "key": "value"
    },
    "questionId": 43,
    "receivedAt": "2022-05-18T08:45:07.606Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}'

HTTP Request

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 450
Host: localhost: 8080
{
    "segmentationInfo": {
        "key": "value"
    },
    "questionId": 43,
    "receivedAt": "2022-05-18T08:45:07.606Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}

Example of a Successful HTTP Response

HTTP/1.1 200 OK

Example: Post Answers by sessionId and questionIndex

Curl Example

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {},
    "sessionId": "1",
    "questionIndex": 3,
    "receivedAt": "2022-05-18T08:45:07.656Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}'

HTTP Request

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 383
Host: localhost: 8080
{
    "segmentationInfo": {},
    "sessionId": "1",
    "questionIndex": 3,
    "receivedAt": "2022-05-18T08:45:07.656Z",
    "text": "testPostAnswersByClientId",
    "attachments": [
        {
            "url": "http://test...",
            "name": "testImage.png",
            "type": "image/jpeg",
            "size": 256,
            "contentType": null
        }
    ],
    "code": "SWITCH_TO_HUMAN",
    "answerId": "externalAnswerId"
}

Example of a Successful HTTP Response

HTTP/1.1 200 OK

Example: Message with Quick Reply

Curl Example

$ curl 'http: //localhost:8080/api/v1/chatbot' -i -X POST \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <token>' \
-d '{
    "segmentationInfo": {},
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.464Z",
    "quickReplies": [
        {
            "type": "TEXT",
            "text": "quick reply 1",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
        },
        {
            "type": "TEXT",
            "text": "quick reply 2",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SUCCESS",
    "answerId": "externalAnswerId"
}'

HTTP Request

POST /api/v1/chatbot HTTP/1.1
Content-Type: application/json
Authorization: Bearer <token>
Content-Length: 570
Host: localhost: 8080
{
    "segmentationInfo": {},
    "clientId": "1",
    "threadsClientId": 1,
    "receivedAt": "2022-05-18T08:45:07.464Z",
    "quickReplies": [
        {
            "type": "TEXT",
            "text": "quick reply 1",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
        },
        {
            "type": "TEXT",
            "text": "quick reply 2",
            "imageUrl": null,
            "url": null,
            "shown_text": null,
            "callback_data": null
        }
    ],
    "settings": {
        "blockInput": true,
        "masked": false
    },
    "code": "SUCCESS",
    "answerId": "externalAnswerId"
}

Example of a Successful HTTP Response

HTTP/1.1 200 OK
Greet
Next Article Hints