Detailed Description

Start conversation

Overview

This API allows client applications to create a new conversation. The conversation can be created with, or without a customer.
A new customer will be created if a customer with provided details does not already exist in the application.
This is used for Asynchronous messaging. Refer Asynchronous messaging for more details.
For this API to execute successfully:

Assignment service must be running.
An agent must be available to serve the chat.
The webhook callback URL of the client application must be active. Refer Deactivation of webhook callback URL for more details.

As part of completing this API:

A new chat activity is created in the application, and assigned to an available agent.

Since: 12.0 ES1

APIs

Method	URL	Description
POST	`/ws/v19/clientapplications/messaging/conversation/start?anonymousCustomer=yes`	Creates a new conversation without a customer.
POST	`/ws/v19/clientapplications/messaging/conversation/start?searchContactOnAttribute={value}`	Creates a new conversation for a customer. The customer will be identified based on value provided for the query parameter "searchContactOnAttribute". Refer the section Supported API specific query parameters for more details about the query parameter "searchContactOnAttribute".

Authentication

Authentication is required. Only authenticated client applications of type 'Chat' are allowed to access this API. This API must contain the access token returned by the Authentication API.

Permissions

The client application must be configured to use the entry point provided in request.

Licenses

N/A

Request

Request headers

Name	Description	Allowed values	Default value
Authorization	Access token for the client. The value must be "Bearer" followed by access token. To elaborate, the value must be "Bearer <access_token>"	N/A	N/A
Content-Type	Media type sent by the client.	`application/xml` or `application/json` or `multipart/form-data`	N/A
Accept	Content type accepted by the client.	`application/xml` or `application/json`	N/A
Accept-Language	Language locale accepted by client (used for locale specific fields in resource representation and in error responses)	Supported 'Accept-Language' header codes	`default system language`

Request Body

The request body is mandatory. Request body can be in either XML or JSON format.

Elements required in request body

Name	Description
entryPointConfiguration.entryPoint.id	Entrypoint ID which will be used for starting chat conversation.
entryPointConfiguration.lastModified.date	The date when the entry point configuration was last modified.

Optional elements allowed in request body

Name	Description
activity.case.id	The case ID with which the conversation has to be associated with. If case.id is provided: The case must exist in the application. The case must belong to the same customer who is initiating the conversation. The query parameter "searchContactOnAttribute" must be provided. This implies that case will only be associated for identified customers. If case.id is not provided, the application will create a new case for the conversation.
activity.subject	Subject of the conversation, in plain text. Must be at least 1 character, and must not exceed 255 characters.
activity.payload.chat.clientInfo.timeOffset	End user time zone offset.
activity.payload.chat.clientInfo.referrerName	Referrer name
activity.payload.chat.clientInfo.referrerURL	Referrer URL
activity.payload.chat.clientInfo.isRichTextSupported	This indicates whether client supports rich text. If client does not support rich text, the application will send messages in plain text. Below are the allowed values: true: Client supports rich text false: Client does not support rich text The default value is true.
activity.customAttributes	Custom attributes for the activity being created as part of this conversation. Name must match one of the custom attributes configured in application. If the custom attribute is configured as an enumeration, the value must be one of the predefined values. For string type of custom attribute that is not configured as an enumeration, refer list of Allowed Characters For Custom Attributes.
activity.customer	This must be provided if the query parameter "searchContactOnAttribute" is provided. This must not be provided if the query parameter "anonymousCustomer" is provided. If a customer is not found using the value of the query parameter "searchContactOnAttribute", a new customer will be created using the provided values. Otherwise, this attribute is ignored. Custom attributes for the contact can also be provided

Supported API specific query parameters

Only one of the below mutually exclusive parameters must be provided:

Name	Description	Allowed values	Default value
anonymousCustomer	Indicates whether the conversation is for an anonymous customer.	yes: Conversation is for an anonymous customer.	N/A
searchContactOnAttribute	This parameter indicates the attribute of the contact, on which customer records will be looked up. The attribute corresponding to the provided value must exist in the customer representation. Eg: If provided value is "externalId", the contact in the customer representation must contain externalId. If "Customer departmentalization" setting is enabled, this API will search the customer in the department of the entry point, otherwise it will search the customer across the application. If a customer with the value of this attribute does not exist, a new customer will be created using the customer details provided in the customer element.	email.emailAddress: Email address of the customer. home.phone: Home phone number of the customer. mobile.phone: Mobile phone number of the customer. office.phone: Office phone number of the customer. social.facebookId: Facebook ID of the customer. social.twitterId: Twitter ID of the customer. social.instagramId: Instagram ID of the customer. externalId: A unique identifier of the contact. custom.<attribute_name>: Custom attributes of the contact.	N/A

The below optional parameter can be provided:

Name	Description	Allowed values	Default value
sendTypingNotification	This indicates whether notifications about the below agent actions have to be posted on the callback URL: Agent starts typing Agent stops typing	yes: Notify the client application no: Do not notify the client application.	no
conversationContact	The contact to be used for the conversation. This can be provided only if the query parameter "searchContactOnAttribute" is provided. If this parameter is not provided, the activity created for this conversation will not be associated with any contact point. The attribute corresponding to the provided value must exist in the customer representation. Eg: If provided value is "email.emailAddress", the contact in the customer representation must contain an email contact point.	email.emailAddress: Email address of the customer. home.phone: Home phone number of the customer. mobile.phone: Mobile phone number of the customer. office.phone: Office phone number of the customer. social.facebookId: Facebook ID of the customer. social.twitterId: Twitter ID of the customer. social.instagramId: Instagram ID of the customer.	N/A

Supported common query parameters

None

Response

Response headers

Name	Description	Possible values
Content-Type	Media type of response body	`application/xml` or `application/json`

Response body XML schemas:

v19-schema-kb-WSError - used in case of error
v19-schema-live-Conversation - used in case of success

HTTP status codes

Success Status codes

200 - OK

Chat conversation started successfully.

Failure Status codes

400 - Bad Request

None of the mutually exclusive mandatory query parameters are provided.
Any unsupported query parameters are provided.
Invalid value provided for any of the query parameters.
Customer search found multiple contacts.
Customer was not found, and customer creation using the provided details failed.
Any rules stated in Overview or Request Body sections are violated.

401 - Unauthorized

Authorization header is not provided.
Authorization header format is incorrect.
Session does not exist corresponding to the provided authorization header.
The session identified through authorization header is not a client application session.

403 - Forbidden

The client application is not configured to use the provided entry point.

406 - Not Acceptable

Invalid 'Accept-Language' header value.

500 - Internal server error

Request processing failed because of internal server error.

Examples:

Example 1 - Start conversation with required attributes
Example 2 - Start conversation with all attributes
Example 3 - Start conversation with all default attributes
Example 4 - Start conversation with required attributes for anonymous customer
Example 5 - Start conversation with all attributes for anonymous customer
Example 6 - Start conversation with default attributes for anonymous customer