Jump to

• Request
• Response
• Examples

Create an engagement

post

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

This operation is used by the end user to create a chat engagement. Once a session is started and an engagement ID is generated by the chat server, the chat engagement is created and the end user is ready to conduct a chat session. The Authorization header must include the 'Bearer ' prefix before the JSON web token (JWT).

Request

Supported Media Types

• application/json; charset=utf-8

Path Parameters

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

Query Parameters

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

Header Parameters

• Authorization: string
  The HTTP request header that contains the JWT for authenticating the request.

Body ()

The object containing the request information.

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

Type: object

Show Source

• clientRequestTime(optional): string
  The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format.
• clientTransactionId(optional): 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.

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

Back to Top

Response

Supported Media Types

• application/json; charset=utf-8

200 Response

The chat session was created successfully.

Body ()

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

Type: object

Show Source

• cancelledSurveyAuth(optional): string
  The unique authentication parameter of the survey that appears when a chat is abandoned or cancelled by the consumer. For the survey to appear when a chat is abandoned or cancelled, you will need both the cancelledSurveyAuth and cancelledSurveyId parameters.
• cancelledSurveyId(optional): integer(int64)
  The unique identifier of the survey that appears when a chat is abandoned or cancelled by the consumer. For the survey to appear when a chat is abandoned or cancelled, you will need both the cancelledSurveyAuth and cancelledSurveyId parameters.
• cancelledSurveyIdString(optional): string
  The unique identifier of the survey (in string format)that appears when a chat is abandoned or cancelled by the consumer. For the survey to appear when a chat is abandoned or cancelled, you will need both the cancelledSurveyAuth and cancelledSurveyId parameters.
• clientId(optional): integer(int64)
  The unique identifier of the client.
• clientIdString(optional): string
  The unique identifier of the client as a String.
• clientRequestTime(optional): string
  The local time of the requesting client in yyyy-MM-dd'T'HH:mm:ssXXX format.
• clientTransactionId(optional): 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(optional): string
  The unique identifier of the client transaction as a String.
• completedSurveyAuth(optional): string
  The unique authentication parameter of the survey that appears when a chat is completed by either the consumer or the agent. For the survey to appear upon completion of a chat, you will need both the completedSurveyAuth and completedSurveyId parameters.
• completedSurveyId(optional): integer(int64)
  The unique identifier of the survey that appears when a chat is completed by either the consumer or the agent. For the survey to appear upon completion of a chat, you will need both the completedSurveyAuth and completedSurveyId parameters.
• completedSurveyIdString(optional): string
  The unique identifier of the survey (in string format) that appears when a chat is completed by either the consumer or the agent. For the survey to appear upon completion of a chat, you will need both the completedSurveyAuth and completedSurveyId parameters.
• engagementId(optional): integer(int64)
  The unique identifier of the chat engagement.
• engagementIdString(optional): string
  The unique identifier of the chat engagement as a String.
• resultType: string
  The type of the result. For example, 'SUCCESS'.
• sendSurveyAuth(optional): string
  The unique authentication parameter of the survey, to make the survey appear, which is sent after a certain delay.
• sendSurveyDelay(optional): integer(int32)
  The delay in sending the survey, in seconds.
• sendSurveyId(optional): integer(int64)
  The unique identifier of the survey, which is sent after a certain delay.
• sendSurveyIdString(optional): string
  The unique identifier of the survey (in string format), which is sent after a certain delay.
• serviceFinishTime(optional): string
  The time when the request processing completed in yyyy-MM-dd'T'HH:mm:ssXXX format.
• serviceStartTime(optional): string
  The time when the request processing started in yyyy-MM-dd'T'HH:mm:ssXXX format.
• sessionId: string
  The unique identifier of the session.
• sneakPreviewInterval(optional): integer(int32)
  The number of milliseconds that the end user is required to wait between sending sneak preview messages.
• sneakPreviewState(optional): string
  Allowed Values: [ "NONE", "ENABLED", "DISABLED", "SITE_UNAVAILABLE", "SERVICE_UNAVAILABLE" ]

  The current state of the sneak preview functionality from the end user's perspective.

  • NONE: Sneak preview state not set (or undefined)
  • ENABLED: Sneak preview is enabled on the end user interface.
  • DISABLED: Sneak preview is disabled on the end user interface.
  • SITE_UNAVAILABLE: Sneak preview is enabled on the end user interface but is disabled for the site.
  • SERVICE_UNAVAILABLE: Sneak preview is enabled on the end user interface but is disabled globally.

{
    "required":[
        "resultType",
        "sessionId"
    ],
    "properties":{
        "engagementId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the chat engagement."
        },
        "engagementIdString":{
            "type":"string",
            "description":"The unique identifier of the chat engagement as a String."
        },
        "resultType":{
            "type":"string",
            "description":"The type of the result. For example, 'SUCCESS'."
        },
        "sessionId":{
            "type":"string",
            "description":"The unique identifier of the session."
        },
        "sneakPreviewState":{
            "type":"string",
            "description":"<p>The current state of the sneak preview functionality from the end user's perspective.</p><ul><li>NONE: Sneak preview state not set (or undefined)</li><li>ENABLED: Sneak preview is enabled on the end user interface.</li><li>DISABLED: Sneak preview is disabled on the end user interface.</li><li>SITE_UNAVAILABLE: Sneak preview is enabled on the end user interface but is disabled for the site.</li><li>SERVICE_UNAVAILABLE: Sneak preview is enabled on the end user interface but is disabled globally.</li></ul>",
            "enum":[
                "NONE",
                "ENABLED",
                "DISABLED",
                "SITE_UNAVAILABLE",
                "SERVICE_UNAVAILABLE"
            ]
        },
        "sneakPreviewInterval":{
            "type":"integer",
            "format":"int32",
            "description":"The number of milliseconds that the end user is required to wait between sending sneak preview messages."
        },
        "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."
        },
        "sendSurveyId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the survey, which is sent after a certain delay."
        },
        "sendSurveyIdString":{
            "type":"string",
            "description":"The unique identifier of the survey (in string format), which is sent after a certain delay."
        },
        "sendSurveyAuth":{
            "type":"string",
            "description":"The unique authentication parameter of the survey, to make the survey appear, which is sent after a certain delay."
        },
        "sendSurveyDelay":{
            "type":"integer",
            "format":"int32",
            "description":"The delay in sending the survey, in seconds."
        },
        "completedSurveyId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the survey that appears when a chat is completed by either the consumer or the agent. For the survey to appear upon completion of a chat, you will need both the completedSurveyAuth and completedSurveyId parameters."
        },
        "completedSurveyIdString":{
            "type":"string",
            "description":"The unique identifier of the survey (in string format) that appears when a chat is completed by either the consumer or the agent. For the survey to appear upon completion of a chat, you will need both the completedSurveyAuth and completedSurveyId parameters."
        },
        "completedSurveyAuth":{
            "type":"string",
            "description":"The unique authentication parameter of the survey that appears when a chat is completed by either the consumer or the agent. For the survey to appear upon completion of a chat, you will need both the completedSurveyAuth and completedSurveyId parameters."
        },
        "cancelledSurveyId":{
            "type":"integer",
            "format":"int64",
            "description":"The unique identifier of the survey that appears when a chat is abandoned or cancelled by the consumer. For the survey to appear when a chat is abandoned or cancelled, you will need both the cancelledSurveyAuth and cancelledSurveyId parameters."
        },
        "cancelledSurveyIdString":{
            "type":"string",
            "description":"The unique identifier of the survey (in string format)that appears when a chat is abandoned or cancelled by the consumer. For the survey to appear when a chat is abandoned or cancelled, you will need both the cancelledSurveyAuth and cancelledSurveyId parameters."
        },
        "cancelledSurveyAuth":{
            "type":"string",
            "description":"The unique authentication parameter of the survey that appears when a chat is abandoned or cancelled by the consumer. For the survey to appear when a chat is abandoned or cancelled, you will need both the cancelledSurveyAuth and cancelledSurveyId parameters."
        }
    }
}

400 Response

The validation of the request object failed.

Body ()

Root Schema : schema

Type: object

403 Response

The validation on the JWT failed.

Body ()

Root Schema : schema

Type: object

404 Response

The resource was not found.

Body ()

Root Schema : schema

Type: object

408 Response

The request timed out.

Body ()

Root Schema : schema

Type: object

409 Response

The engagement was dequeued via the routing rules.

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 create a chat engagement 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/requestEngagement?pool=297:1 -H 'Content-Type: application/json; charset=utf-8' -d '{}' -H 'Authorization: Bearer eyJhbGciOiJSU...Wst7gbQ6Nqs'

Request Body Example

The following shows an example of the request body in JSON format. For this operation it is an empty payload.

{}

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.

{
"engagementId":34,
"engagementIdString":"34",
"cancelledSurveyId":0,
"cancelledSurveyIdString":"0",
"completedSurveyId":0,
"completedSurveyIdString":"0",
"cancelledSurveyAuth":"",
"completedSurveyAuth":"",
"resultType":"SUCCESS",
"sessionId":"192hyto5qomm8r8rpzzmuzsa6",
"sneakPreviewState":"DISABLED",
"sneakPreviewInterval":3000,
"clientRequestTime":null,
"clientTransactionId":0,
"clientTransactionIdString":"0",
"serviceStartTime":"2018-10-16T12:28:46.544Z",
"serviceFinishTime":"2018-10-16T12:28:46.688Z",
"clientId":34,
"clientIdString":"34"
}

Back to Top