Contact Center Chat API Use Case

This page will help you get started with contact center. You'll be up and running in a jiffy!

Contact Center Chat

The 8x8 Contact Center Chat (Chat) API provides a server to server capability enabling a client app to provide chat experiences while retaining full control of the client application's interface and user experience.

Your customers use their phones or digital devices to communicate and engage with your service agents or representatives by messaging. Typically, the types of communication channels include:

  • Mobile app-based chat
  • Desktop web chat bots
  • Messaging via integrations with other apps or platforms

Use of these communications channels can be enhanced using Contact Center with the Chat API. The API routes customer communications to your Contact Center enabled agents within the context of the initial customer engagement. This provides continuity of experience and elicits customer confidence in your enterprise as you proactively respond to their inquiries. Use of Contact Center with the Chat API enables you to scale and manage your customer service engagements.

Integrating Contact Center with the Chat API enables customers to:

  • Provide Chat services while retaining full control of the user interface and experience
  • Initiate (chatbot) conversations with your customers and then hand them to an available agent
  • Leverage Contact Center Chat interaction routing and features to solve customer requests

For an example of Chat API usage, consider a scenario in which an academic institution promotes a mobile app for its registered students which includes helpful information such as course schedule, professor contacts, and more. In this scenario, the institution seeks to add a chat component for the capability to contact student services directly from the mobile app and thus invoke a front end the experience with a chat bot. The academic institution can now build the app with chatbot solution using the Chat API to pass any unresolved queries to an agent.

The following screen shot shows the process from when a student engages with the bot and then is offered the option to communicate with an agent:

For further consideration, consider the example of a travel/hospitality organization with prospective customers and clients who are communicating and messaging through 3rd party portals and applications. Previously, these messages were delivered as emails and thus required substantial non-real time back and forth which would may result in duplicate conversations, present a low speed of response, and prevent possible first contact resolution. By bridging the 3rd party portal/application using the Chat API to Contact Center the travel/hospitality organization would be able to speed the routing and resolution of requests. Additionally, the organization could augment the improved performance with measurement and management capabilities to ensure that service levels could be created and delivered upon.

Data flow in a conversation

A client application begins a conversation with the 8x8 platform for each customer session. The client needs the senderId and the recipientId to start and end the conversation as well as to send and receive messages.

The Chat API routes this conversation using the configured queue for a given channel and then handles the assignment based on an agent's availability and skills.

The channel is associated with a queue. The queue ID needs to be of type chat and can be found in the 8x8 Configuration Manager (CM) in the Queues section.

Base URL description

The Base URL description consists of the cluster URL from your 8x8 contract.

Set-up the API

In order to effectively use the Chat API, set up integration with the API in the following order:

  1. Authentication
  2. Authorize
  3. Hooks
  4. sendMessage
  5. sendMessage
  6. startConversation
  7. endConversation

Authentication

To access the VCC Chat endpoint, you must contact your 8x8 Chat representative to provide you with an 8x8 API Key.

Using the 8x8 API key and your VCC Configuration Manager details, you can then obtain an VCC Chat endpoint access token by making a POST call to the /authorize endpoint with your Base64 encoded tenantId username and password using basic authentication.

To access the VCC Chat endpoint:

  1. Obtain an 8x8 API key from your 8x8 Chat representative.

    The API key must be used for every Chat API call via the header 8x8-apikey.

  2. Compose the basic authentication request for the Chat API /authorize endpoint:

    a. Get the Username and the Action Request Token from your VCC Configuration Manager implementation by accessing the user menu and going to Integrations -> API Token display. Note that the username is the same as the tenant name.

    b. Perform Base64 encoding (https://www.base64decode.org/) on the Username and Action Request Token combination.

    In the Encode field, enter your Username, followed by a semicolon, followed by the Action Request Token. No spaces or other characters can be included in the strings that you are encoding. For example, (Username:Action Request Token).

  3. Call the VCC Chat API /authorize endpoint at the following URL:

    https://8x8gateway-8x8apis.apigee.io/docs/vcc/1/routes/authorize/post

    The header name is Authorization and its value is the Base64 encoding you performed.

The /authorize endpoint returns a JWT_token. This JWT token can then be used for all other calls to the VCC Chat API endpoints such as webhooks or conversation management. The selected endpoints require a header named Authorization and the value to be Bearer JWT_token (JWT_token).

For the complete authentication process refer to Chat Authentication on the Getting Started page.

All requests must be made over HTTPS - calls made over HTTP will fail.

Webhook Registration and Configuration


The 8x8 messaging platform sends events to your webhook to notify your system when a variety of events happen part of a conversation, including when a person sends a message or a read receipt is generated. Webhook events are sent by the 8x8 platform as POST requests to your webhook.

The client system must respond with HTTP code 200 or else the call will be retried up to 5 times.

  • The webhook is configured programmatically by making a POST call to:

baseURL/chat-subscriptions/hooks

  • The webhook can be updated by making a PUT call to:

baseURL/chat-subscriptions/hooks/{channelId}

Note: Once you have added a webhook, 8x8 refers to it as a channel. The channelId will be the recipient of system messages sent back to the user.

  • The webhook can be deleted by making a DELETE call to:

baseURL/chat-subscriptions/hooks/{channelId}

  • To list all webhooks (channels) make a GET request to:

baseURL/chat-subscriptions/hooks/

  • To list a specific webhooks (channels) by their channelId make a GET request to:

baseURL/chat-subscriptions/hooks/{channelId}

Conversation Workflow

  • A chat conversation is started by making a POST call to:

baseURL/chat-api/startConversation

An interaction can be created by making a call to /startConversation endpoint if transaction details or history messages with the bot need to be added to the conversation.

Note: The metadata (attached data) with customer details is send in the body of a start conversation event and it contains key-value pairs. A few predefined keys are: senderName, email, language, company, but anything can be added in attached data and will be marked as transaction details. The previous messages between a customer and a bot can also be sent in the body (history) of the start conversation event

  • A chat conversation concludes by the client making a POST call to:

baseURL/chat-api/endConversation

Note: A conversation can be ended by agent also, in which case you will receive a system event. Refer to the System Events section for more information.

  • A message can be sent to a channel by making a POST call to:

baseURL/chat-api/sendMessage

Note: An interaction is created also by making a direct call to /sendMessage without calling first /startConversation.

  • The 8x8 system will POST the following content to the configured webhook:
{ 
    "messageType": "text", 
    "recipientId": "userId", 
    "message": "Hello World!", 
    "senderId": "agent", 
    "senderName": "agentNickname" 
} 

System events

The 8x8 system sends events regarding conversation participants changes (agent join, agent ending) as they happen in real time. System events are used to configure attached data during the conversation and get changes in attached data or control system functionality like translation. The 8x8 system will POST the following content to the configured webhook:

  • For agent joining live conversation the 8x8 system will POST the following content to the configured webhook:
{ 
  "messageType": "systemEvent", 
    "eventType": "agent_joined", 
    "agentName": "agentNickname"
} 
  • For agent ending conversation the 8x8 system will POST the following content to the configured webhook:
{ 
    "messageType": "systemEvent", 
    "eventType": "conversation_ended_by_agent", 
    "agentName": "agentNickname" 
} 

Chat API endpoints

You can test the endpoints here.

API REFERENCE

Refer to the API Reference for additional information.


Did this page help you?