Jump to

• Request
• Response
• Examples

Send a message

post

/engagement/api/consumer/{fqSiteName}/v1/postMessage

This operation is used by the end user to send messages to the agent. The collection of these messages comprises a chat engagement.
The user can start sending messages as soon as the chat engagement is created and does not have to wait until the chat engagement is accepted by the agent.

Spam handling (Tier‐1)

The server evaluates each posted message with fast Tier‐1 checks to reduce abusive/disruptive content (e.g., excessive length/URLs, duplicate content, emoji/symbol flooding, burst rate).

Possible Responses:

• Allowed: HTTP 200 with PostEngagementMessageResponse. The post is accepted.
• Single block ( no termination ): HTTP 200 with PostEngagementMessageResponse. The server injects a user visible system message into the engagement explaining that the message was blocked for suspicious content. Clients should surface the conversation stream so users see the system message, not only the HTTP status.
• Auto‐termination ( extreme or repeated violations ): HTTP 409 CONFLICT with a message explaining the termination. The server posts termination notices, disconnects the end user and concludes the engagement.

Tier‐1 runs by default for the tenant/interface unless disabled by configuration. Deployments may tune thresholds; reason details are not included in the API payloads but the server logs structured reason codes and posts explanatory system messages in the engagement. Some deployments may choose to bypass Tier‐1 for agent originated posts; otherwise, the same rules apply to both end user and agent messages.

Request

Supported Media Types

• application/json; charset=utf-8

Path Parameters

• fqSiteName(required): string
  The name of the site returned by the call to establish a session.

Query Parameters

• pool(required): string
  The pool ID specified in the Establish Sessions response or provided in an RNEngagementConfigurationChangedMessage system message.

Header Parameters

• SessionId(required): string
  The unique identifier of the consumer session.

Body ()

The object containing the request information.

Root Schema : com.rightnow.chat.rest.consumer_api.model.requests.v1.PostEngagementMessageRequest

Type: object

Show Source

• body(required): string
  The text message from the end user to the agent.
• clientRequestTime: string
  The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format.
• clientTransactionId: integer(int64)
  The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses.
• messageDataMap: object messageDataMap
  An optional map of client supplied key/value String pairs associated with this message.
• messageId: string
  The unique identifier of the message.
• offTheRecord: boolean
  Indicates whether the text message should be considered 'off the record' and not logged. If true, then the message is not logged. The default value is false.
• richText: boolean
  Indicates whether the text message is rich text. If true, then the message is rich text. The default value is false.

{
    "required":[
        "body"
    ],
    "properties":{
        "body":{
            "type":"string",
            "description":"The text message from the end user to the agent."
        },
        "offTheRecord":{
            "type":"boolean",
            "description":"Indicates whether the text message should be considered 'off the record' and not logged. If true, then the message is not logged. The default value is false."
        },
        "messageId":{
            "type":"string",
            "description":"The unique identifier of the message."
        },
        "richText":{
            "type":"boolean",
            "description":"Indicates whether the text message is rich text. If true, then the message is rich text. The default value is false."
        },
        "messageDataMap":{
            "type":"object",
            "description":"An optional map of client supplied key/value String pairs associated with this message."
        },
        "clientRequestTime":{
            "type":"string",
            "description":"The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "clientTransactionId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses."
        }
    }
}

Nested Schema : messageDataMap

Type: object

An optional map of client supplied key/value String pairs associated with this message.

Back to Top

Response

Supported Media Types

• application/json; charset=utf-8

200 Response

The request completed successfully.

Body ()

Root Schema : com.rightnow.chat.rest.consumer_api.model.responses.v1.PostEngagementMessageResponse

Type: object

Show Source

• clientId: integer(int64)
  The unique identifier of the client.
• clientIdString: string
  The unique identifier of the client as a String.
• clientRequestTime: string
  The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format.
• clientTransactionId: integer(int64)
  The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses.
• clientTransactionIdString: string
  The unique identifier of the client transaction as a String.
• serviceFinishTime: string
  The time when the request processing completed in yyyy-MM-dd'T'HH:mm:ssXXX format.
• serviceStartTime: string
  The time when the request processing started in yyyy-MM-dd'T'HH:mm:ssXXX format.

{
    "properties":{
        "clientRequestTime":{
            "type":"string",
            "description":"The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "clientTransactionId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the client transaction. The value specified in this field is echoed back in the response object. It is used to link requests to responses."
        },
        "clientTransactionIdString":{
            "type":"string",
            "description":"The unique identifier of the client transaction as a String."
        },
        "serviceStartTime":{
            "type":"string",
            "description":"The time when the request processing started in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "serviceFinishTime":{
            "type":"string",
            "description":"The time when the request processing completed in yyyy-MM-dd'T'HH:mm:ssXXX format."
        },
        "clientId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the client."
        },
        "clientIdString":{
            "type":"string",
            "description":"The unique identifier of the client as a String."
        }
    }
}

400 Response

The validation of the request object failed.

Body ()

Root Schema : schema

Type: object

403 Response

The consumer session identifier is unknown.

Body ()

Root Schema : schema

Type: object

404 Response

The resource was not found.

Body ()

Root Schema : schema

Type: object

409 Response

The lead agent participant has left the engagement.

Body ()

Root Schema : schema

Type: object

500 Response

An error occurred in the chat server while processing the request.

Body ()

Root Schema : schema

Type: object

Back to Top

Examples

The following example shows how to a send message to an agent by submitting a POST request using cURL:

cURL Command Example

curl -X POST https://chat_rest_server_domain.com/engagement/api/consumer/day119_181100_sql_238h/v1/postMessage?pool=297:1 -H 'Content-Type: application/json; charset=UTF-8' -H 'SessionId: 192hyto5qomm8r8rpzzmuzsa6' -d '{"body":"Hello I need help with my refund, it has been very long time."}'

Request Body Example

The following shows an example of the request body in JSON format.

{
   "body":"Hello I need help with my refund, it has been very long time."
}

Response Header Example

The following shows an example of the response header.

Status: 200 OK
Content-Type: application/json;charset=utf-8

Response Body Example

The following shows an example of the response body in JSON format.

{
    "clientRequestTime": null,
    "serviceStartTime": "2018-10-23T14:00:38.205Z",
    "serviceFinishTime": "2018-10-23T14:00:38.218Z",
    "clientId": 34,
    "clientIdString": "34",
    "clientTransactionId": 0,
    "clientTransactionIdString": "0"
}

Back to Top