CEAPI endpoint reference

This topic describes the endpoints exposed in the CEAPI.

Note: In all code samples in this topic, tokens and other long strings have been truncated to save space.

activity

POST activity sends chat activity messages into the system. These messages will not be stored in the chat transcript.

Parameters

HTTP Codes

Example of sending a message

POST https://{api.nuance.com}/engagementAPI/v1/customer/activity

Body:

customerID=111&engagementID=111&activityType=customerStartTyping

Response Example

200 OK

Activity Types

Activity types customerStartTyping and customerStopTyping tell the agent when the customer starts or stops typing. customerStartTyping should only be repeated if there was a customerStopTyping request. The stop typing activity type should be sent when there is no user input for a timeout period (such as 4 seconds, for example.)

The following pseudocode sketches the algorithm for client to send start and stop typing:

boolean isTyping = false;

Timer stopedTypingTimer = null;

// event handler for user typing event (onKeyPress, onChange or similar event)
function onUserTyping() {
  // reschedule the stoppedTyping timer to the new time = now + 4seconds
  cancelTimerIfNotNull(stoppedTypingTimer);
  stoppedTypingTimer = scheduleTimer(now + 4sec, onStoppedTyping);

  if (!isTyping) {
    POST activity ? activityType = customerStartTyping
      isTyping = true;
  }
}

function onStoppedTyping() {
  isTyping = false;
  POST activity ? activityType = customerStopTyping
}

agentAvailability

GET agentAvailability determines the current agent availability status.

Agent availability status depends on currently active engagements, total agent “slots” (sum of available slots across all agents in the relevant agent group) and queue threshold (configured per agent group). The primary value in the response is agent availability (true or false) which is based on the following algorithm:

(Queue Threshold) * (Total Agent Slots) – ((Total Active Engagements) + (Total Queued Engagements))

If this number is greater than 0, agent availability is true. If it is less than or equal to 0 agent availability is false.

agentAvailability is typically used to decide whether to present an invitation to engage or to determine whether a program is within the hours of operation.

Parameters

Response HTTP Code

Response Values

							estimatedWaitTime
						

Request Example

GET https://{api.nuance.com}/engagementAPI/v1/customer/agentAvailability?siteID=10003715&businessUnitID=13000508&agentGroupID=10004026

Note: Business Unit ID parameter is required.

Response Example

200 OK

<?xml version="1.0" encoding="UTF-8"?>
  <message>
    <inHOP>true</inHOP>
    <status>online</status>
    <availability>true</availability>
    <queueDepth>0</queueDepth>
    <estimatedWaitTime>0</estimatedWaitTime>
  </message>

Note: If all chat slots are taken up and the agent gets another chat request then the status will be busy and availability will be false.

Here is an example:

<?xml version="1.0" encoding="UTF-8"?>
<message>
<inHOP>true</inHOP>
<status>busy</status>
<availability>False</availability>
<queueDepth>0</queueDepth>
<estimatedWaitTime>0</estimatedWaitTime>
</message>

assisted

POST assisted allows applications to indicate when the criteria has been met for assisting a customer using an engagement.

Parameters

Response HTTP Code

Request Example

POST https://{api.nuance.com}/engagementAPI/v1/customer/event/assisted

POST body:

{
		 "tcCustomerID": "465657113802851330",
		 "siteID": 306,
		 "businessUnitID": 22,
		 "agentGroupID": 10004091,
		 "viewID": "6789231234",
		"sessionID": "55552456234234",
		"engagementID": 123433332111,
		"businessRuleID":"12351dsf123213",
		"customVariables": [
		{
		"name": "attributeName@&^",
		"value": "attributeValue",
		"persistence": "persistent",
		"action": "append"    }
		],
		"attributes": [
		{
		"name": "visAttr 1",
		"value": "visAttr Value11",
		"attributeType": "visitorAttribute",
		"externalCustomerID": "Yes",
		"action": "set"    },
		{
		"name": "attr1",
		"value": "visAttrValue22 !$>",
		"attributeType": "applicationAttribute",
		"action": "set"    },
		{
		"name": "attr2",
		"value": "visAttrValue22 !$>",
		"attributeType": "engagementAttribute",
		"action": "remove"    }
		]
		}

Response Example

200 OK

ETL logs example:

1495206882128-customer.customAttribute?attributeType=visitor&customerID=465657113802851330&siteID=306&attr=visAttr+1,visAttr+Value11,set&pageName=6789231234&externalCustomerIDs=visAttr+1
1495206882128-customer.customAttribute?attributeType=application&customerID=465657113802851330&siteID=306&sessionID=55552456234234&attr=attr1,visAttrValue22+%21%24%3E,set&pageName=6789231234...
		

Note: ETS logs example has been truncated for brevity.

Request Example 2

POST https://{api.nuance.com}/engagementAPI/v1/customer/event/assisted

POST body:

{
"tcCustomerID": "465657113802851330",
"siteID": 306,
"engagementID": 123433332111,
"businessRuleID":"asdfasdasd4111"}

Response Example

200 OK

ETL log example:

1495206995659-conversionFunnel.assisted?incAssignmentID=465657113802851330&businessRuleID=asdfasdasd4111&chatID=123433332111&customerID=465657113802851330&siteID=306&sessionID=465657113802851330&type=APIchat&inHOP=1

dataPass

POST dataPass sends the agent the context of the user or their experience. dataPass can occur during an engagement and displayed to the agent or agents within the agent interface transcript panel.

Examples of information you can send to an agent are email ID, a client-provided customer identifier, and customer demographics.

Note: You can mark sensitive data values for masking as well.

Parameters

Note: * At least one attribute parameter is required.

Response HTTP Code

Masking

You can use the following syntax to mark attribute values for masking:

((masked{['myDataString']}masked))

Request Example 1

POST https://{api.nuance.com}/engagementAPI/v1/customer/dataPass

POST Body:

engagementID=86448213037320856&agentID=2123411123&key1=value1&key2=value2&key3=value3

Request Example 2

POST https://{api.nuance.com}/engagementAPI/v1/customer/dataPass

POST Body:

engagementID=86448213037320856&agentID=2123411123&key1=((masked{['value1']}masked))&key2=value2&key3=value3

Response Example

200 OK 

emailTranscript

POST emailTranscript sends a chat customer a transcript of the chat content via email. When you call this method, the client may flag an open engagement to be sent to the customer's email address after you complete the engagement.

Note: The engagement is considered as complete only when the session has timed out or the client uses the API to end the chat using the 'stateChange=closed' parameter.

When the engagement is complete, the email containing the transcript will be queued up to be sent by email.

Parameters

Request Headers

Request Example

POST https://{api.nuance.com}/engagementAPI/v1/customer/emailTranscript

POST body:

customerID=12334112&engagementID=39747223223&emailAddress=janesmith@gmail.com&siteID=402

Response Example

200 OK

engagement

GET engagement requests the initiation of an engagement (chat session). Whether or not the engagement is initiated depends on agent availability. Agent availability is based on the following algorithm:

The primary return value is status, which indicates whether the request was immediately assigned to an agent (accepted), placed in a queue (queued), or refused (denied).

Note: Try not to call an engagement request until there is truly a need to assign/reserve an agent slot for a customer. For example, you should avoid an engagement request call before presenting a click to chat or proactive invitation.

You may call an engagement request when the customer engages in chat by sending the first message.

Note: According to this Content-Type, values in all key-value pairs must be URL encoded.

Parameters

Request Headers

Response HTTP Code

Response Values

Request Example 1

GET https://{api.nuance.com}/engagementAPI/v1/customer/engagement?siteID=306&businessUnitID=22&InitialMessage=I%20need%20some%20help

Response Example 2:

200 OK

<?xml version="1.0"encoding="UTF-8"standalone="yes"?><message><status>accepted</status><customerID>7657620078025131029</customerID><engagementID>7657620078025405816</engagementID></message>

Request Example 2

POST https://{api.nuance.com}/engagementAPI/v1/customer/engagement

POST body:

siteID=306&businessUnitID=22&InitialMessage=I%20need%20some%20help

Response Example 2:

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?

<message>
<status>accepted</status>
<customerID>7657620078025131029</customerID>
<engagementID>7657620078025405816</engagementID>

</message>

Example Virtual Agent Datapass / Automaton Fields

GET https://{api.nuance.com}/engagementAPI/v2/customer/engagement?siteID=306&businessUnitID=22&Initial &virtualAgent.NinaVars={"key1":"ABC","key2":"123"}
https://{api.nuance.com}/engagementAPI/v1/customer/engagement?siteID=10000000&businessUnitID=19001192&automatonFields={%22datapass%22:{ "key1":"ABC","key2":"123"}

exitChat

POST exitChat shows an exit from an engagement that is closed by the customer. This action closes the chat for all actions from the customer’s side.

Parameters

Request Example

URL https://{api.nuance.com}/engagementAPI/v1/customer/exitChat

POST body:

customerID=566534534634534&engagementID=52362345623453

Response Example

200 OK

message (GET)

GET message is used to monitor the status of the engagement and retrieve agent messages. The client application should endeavor to have a GET request pending at all times. A GET message should be called immediately following a successful GET engagement call and each GET request-response for which state is not closed. If GET message is not called within the 60-second timeout, the server connection closes the engagement.

GET message also supports callback functionality in which engagement details are pushed to a customer endpoint. The callback response values are a subset of the Message GET response value superset. Callback parameters are indicated in the Response Values table.

Examples of the information returned by GET message:

• Nothing pending (In this case the server will delay the response for several seconds waiting to see if a status change occurs). If a status change occurs, a response is sent immediately with the new status, such as a new message from the agent. If no status change has occurred for 30 seconds, a 204 HTTP status code is returned.
• Queue status – Callback functionality supported
• A new agent message – Callback functionality supported
• Agent is typing – Callback functionality supported

Parameters

Request Headers

Response HTTP Code

Response Values

Request Example

GET https://{api.nuance.com}/engagementAPI/v1/customer/message?engagementID=1234567890&customerID=9876543210

Response Examples

Chat-line example:

200 OK

<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><messages><message><agentID>1</agentID><agent.alias>
Nuance</agent.alias><messageText>Hello</messageText>
<messageType>chatLine</messageType>
<engagementID>11352335599561178</engagementID></message></messages>

Command example:

200 OK

<?xml version="1.0" encoding="UTF-8"
standalone="yes"?><messages><message>
<messageType> command </ messageType >
<engagementID> lj2ga6rl5v4ejpmp2hsjw </ engagementID >
<initiator.id > jhildebrant_poc_test </ initiator.id >
<url>http://www.google.com <url><time>1234567890</time>
</message></messages>

State change example when engagement is assigned to agent:

200 OK

<?xml version="1.0" encoding="UTF-8" standalone="yes"?><messages><message>
<state>assigned</state>
<agentID>2</agentID>
<agent.alias>Agent</agent.alias>
<messageType>stateChange</messageType><engagementID>7657620082316703106</engagementID><host.node.id>192.168.0.20</host.node.id><business_unit.id>22</business_unit.id>
<cobrowse.enabled>true</cobrowse.enabled>
<chatrouter.address>192.168.0.20</chatrouter.address><event.agent_last_name>User Last Name</event.agent_last_name><event.agent_first_name>User First Name</event.agentfirstname><msg.originalrequest.id>5722840234794661</msg.originalrequest.id></message></messages>State change example when chat is closed by the agent: 200 OK <?xml version="1.0" encoding="UTF-standalone="yes"><messages><message><state>closed</state><escalate>false</escalate>
<messageType>stateChange</messageType><display.text>Agent '2' exitchat</display.text><engagementID>7657620082327188868</engagementID></message></messages>

message (POST)

POST message sends a new message from the customer to the agent. This call can also be used to end the engagement.

Note: According to this Content-Type, values in all key-value pairs must be URL encoded. For example, messageText=I%20need%20some%20help

Parameters

Request Headers

Response HTTP Code

Example of sending a message

POST https://{api.nuance.com}/engagementAPI/v1/customer/message

POST body:

customerID=9876543210&engagementID=123456789&messageText=I%20need%20some%20help

Response Example

200 OK

Example of closing an engagement

POST https://{api.nuance.com}/engagementAPI/v1/customer/message

POST body:

customerID=9876543210&engagementID=123456789&messageType=stateChange&state=closed

Response Example

200 OK

surveyUrl

GET surveyUrl allows clients to launch a post-chat survey from an application that uses the engagement API.

This endpoint operates in two modes:

• It allows user to pass in the engagementID and customerID of an active engagement and will return the base URL and parameters for launching the native post-chat survey configured for the site's agent group.
• It allows the user to pass a surveySpecID and will return the base URL for the survey configured for the given surveySpecID.

Parameters for native post-chat survey URL of an active engagement

Parameters for post-chat survey URL from KeySurvey with SurveySpecID

Response HTTP Code

Implementing a post-chat survey

Once you complete the preparations, the client is ready to implement the post-chat survey functionality from their CEAPI app.

During an active engagement, the app should request the post-chat survey URL from the Customer Engagement API. This is done by submitting a GET request to the /surveyUrl endpoint. The siteId, engagementId, and customerId must also be specified.

Here is an example call:

https://{api.nuance.com}/engagementAPI/v1/customer/surveyUrl?siteID=10003715&customerID=-4489709243015478260&engagementID=-4489709243015203473&output=json

This call will return a URL and a string of parameters similar to the following:

{"surveyUrl": "https://bestbrands.inq.com/tagserver/surveys/launchNativePostChatSurvey",

"surveyLaunchData": "engagementID=-4489709243015203473&customerID=-4489709243015478260&siteID=10003715&surveyID=2022&agentGroupID=10004026&businessUnitID=13000508&agentID=achung_a"}

You can launch the survey by loading a web browser and by using a GET or a POST request. To use a GET request, load the page at the survey URL specifying the launch data as a query string. Here is an example to show the loaded URL:

https://bestbrands.inq.com/tagserver/surveys/...

Note: Example (loaded URL) has been truncated for brevity.

The resulting page will launch the post-chat survey within a browser window.

To integrate this experience within the scope of a native app, we recommend opening the post-chat survey via web view client.

Note: Generally, a web view window does not display the address bar, which contains engagement-specific information.

Alternately, the post-chat survey URL will also accept a POST command with the same parameters. This approach is recommended if there are concerns about the engagement details in the address bar.

surveyURL

The surveyURL that is returned by the /surveyUrl request will generally remain constant. However, apps should not hard-code this URL, and instead should use the URL that is returned. This prevents future changes to the survey URL from interrupting post-chat survey functionality.

Chat Themes for Post-Chat Surveys

The chat themes that house the post-chat surveys are set within Nuance Portal and set per device type. The correct theme is loaded automatically when the browser loads the URL. This means that the URL will not change for apps that run on desktop, table, or mobile devices.

Note: If clients need to deploy new apps, they must notify their CSM so Nuance can ensure that a device-appropriate theme is available for the new app's post-chat survey.

Request Example

https://{api.nuance.com}/engagementAPI/v1/customer/surveyUrl?siteID=10003715&customerID=-1655537766535707460&engagementID=-1655537766535432673&output=json

Example, KeySurvey post-chat survey URL

GET https://{api.nuance.com}/engagementAPI/v1/customer/surveyUrl?siteID=306&surveySpecID=2&output=xml

Response Example

200 OK

 <message><survey.url>http://www.keysurvey.com/survey/267053/e7f8/?LQID=1&&surveyID=267053</survey.url></message>

customerSurvey

POST customerSurvey posts the survey response into the system to enhance the user experience. You can view the response of the survey under the Survey Reporting and Survey tabs in the Portal.

Note: This new endpoint for CEAPI is available for v2 only.

POST customerSurvey accepts the survey information and transforms request payload, such as surveyID, siteID, and customerID, in the tag server.

Here is the payload format used by the CEAPI endpoint to submit the survey.

Request Headers

Content-type=application/json, Authorization

Request Payload

{
"siteID": "306",
"engagementID": "2000",
"customerID": "10000",
"surveyID": "1023",
"surveyData": [{
"question": "How would you rate your experience on a scale of 1 to 5?",
"answer": "5"
}, {
"question": "What feature do you like most?",
"answer": "the quality"
}
]
}

Response Example

200 OK

updateDeviceId

POST updateDeviceId updates device IDs for push notification functionality for conversation, in case of absent active engagement.

Parameters

HTTP Codes

Note: If client uses OAuth authorization then valid access token should be set in "Authorization" header otherwise client should login in API as engagement API user.

Example of sending a message

POST https://{api.nuance.com}/engagementAPI/v2/customer/updateDeviceId

POST body:

customerID=-7599162224901667826&businessUnitID=22&pushNotificationDeviceID=1&siteID=306

Response Example

200 OK 

conversationTranscript

GET conversationTranscript is gets the transcript of the last or all conversations to show the customer by customerID or persistentCustomerID. The persistentCustomerID parameter is in JSON format and includes private customer data, such as an email address, phone number, or account ID.

Data is returned according to the filter template in conversation_filter_settings.

For example:

• if filter is "${phone}" IN persistentCustomerID.phone, then if we do not pass persistentCustomerID , it returns nothing.

• if filter is "${email}" IN persistentCustomerID.email OR customerID = "${customerID}" and if we do not pass pcID, then it returns data only by customerID.

Note: If there is no record for site in the conversation_filter_settings then it will use customerID for filtering. Please get in touch with the Nuance Dev team to set up conversation_filter_settings.

It is used only for asynchronous chats users and cannot be used for non-async chats to get transcript.

This returns a list of messages for the last conversation or messages for each conversationID (all mode.) It also returns initialCustomerID (customerID started conversation) in response cross-device or cross-browser support.

Parameters

{"email":"", "phone":"111-11-11"}

persistentCustomerID={"name":"John"}

persistentCustomerID={"id":"12345..."}

HTTP Codes

Note: If client uses OAuth authorization, then valid access token should be set in "Authorization" header otherwise client should log in as an engagement API user.

Example of sending a message

GET https://{api.nuance.com}/engagementAPI/v1/customer/conversationTranscript?siteID=306&customerID=1111111&businessUnitID=22&output=json&persistentCustomerID={%27email%27:%20%27aa@aa.aa%27}

Response Example

200 OK 

Body: "messages":[{"messageText":"I need some help","messageType":"chatLine"},{"messageText":"hi","agentID":"agt@tc.com","messageType":"chatLine","agent.alias":"agt@tc.com"},{"messageText":"bye","agentID":"agt@tc.com","messageType":"chatLine","agent.alias":"agt@tc.com"},{"messageText":"I need some help","messageType":"chatLine"},{"messageText":"hello!","agentID":"agt@tc.com","messageType":"chatLine","agent.alias":"agt@tc.com"},{"messageText":"bye!","agentID":"agt@tc.com","messageType":"chatLine","agent.alias":"agt@tc.com"}]}

topicList

GET topicList gets a list of all topics for the current customer. Filtering is by customerID or persistentCustomerID. This call is available for asynchronous chats only. It cannot be used for non-asynchronous chats.

Parameters

persistentCustomerID={"name":"John"}

persistentCustomerID={"id":"12345..."}

HTTP Codes

Example of sending a message

GET https://{api.nuance.com}/engagementAPI/v1/customer/topicList?siteID=306&customerID=1111111&businessUnitID=22&output=json&persistentCustomerID={%27email%27:%20%27aa@aa.aa%27}

Response Example

200 OK 

Body: {"topics":[{"topicID":"","topicName":""},{"topicID":"1","topicName":"qa"}]},{"topicID":"2","topicName":"2qa"}]}

customerStatus

GET customerStatus checks pending messages for the current customer. Filtering is by persistent CustomerID. This call checks whether agent offline pending messages exist for customer.

It is only for asynchronous chats users.

Query parameters

{"email":"", "phone":"111-11-11"}

persistentCustomerID={"name":"John"}

persistentCustomerID={"id":"12345..."}

HTTP Codes

Request example

GET https://{api.nuance.com}/engagementAPI/v1/customer/customerStatus?siteID=306&output=json&persistentCustomerID={%27email%27:%20%27aa@aa.aa%27}

Response Example

200 OK

Body:{"hasPendingMessages": true}

setAuthenticatedUser

POST setAuthenticatedUser can be called after an engagement has started. It indicates that the user has authenticated and updates the persistentCustomerID of the engagement. The client should use this call to update NDEP when a user authenticates on the client mobile app and a chat is currently active.

Parameters

HTTP Codes

Example

POST https://{api.nuance.com}/engagementAPI/v1/customer/setAuthenticatedUser?customerID=123&engagementID=123&authenticatedUser={"test": "123", "email": "aaa@test.com"}&conversationChannel=CEAPI

Response Example

200 OK

customerActiveConversations

GET customerActiveConversations checks if there are active conversations and returns conversationIDs and additional data without a transcript.

This is only for asynchronous chat users.

Query parameters

{"email":"", "phone":"111-11-11"}

persistentCustomerID={"name":"John"}

persistentCustomerID={"id":"12345..."}

HTTP Codes

Example of sending a message

GET https://{api.nuance.com}/engagementAPI/v1/customer/customerActiveConversations?siteID=306&customerID=1234567&persistentCustomerID={%27email%27:%20%27aa@aa.aa%27}

Response Example

200 OK

Body:

{
"customerID": "1234567",
"conversations": [{
"topicID": "5",
"conversationID": "8",
"topicName": "topicName"
}]
}

verifyToken

GET verifyToken verifies the conversation token generated for cross-channel chats by agent and returns the conversationObjectID and the token in JSON.

This is only for asynchronous chat users.

Query parameters

HTTP Codes

Example of sending a message

GET https://{api.nuance.com}/engagementAPI/v1/customer/verifyToken?siteID=306&customerID=1234567& conversationTokenID=1232134324

Response Example

200 OK

Body:{"conversationTokenID": "1232134324","conversationObjectID": "a634mf7f9a9" }