Live Chat over API
API Metadata
The Live Chat API send_contextual_data allows you to send data to conversations between the agent and the customer initialized via Live Chat. You can use the metadata to distribute any data about customer behavior on your website that you are tracking, which could help the agent or bot resolve conversations more effectively.
For example, a car manufacturer that uses Live Chat on their website has a customer who configures their ideal car. The customer starts a conversation via Live Chat (i.e., via the Contact Us button at the end of the configuration). All data about the customer's car configuration is sent to the agent as the conversation is started and it is visible to them to fully understand the client's needs.
The Conversation context card in the Agent interface will automatically display all the metadata you share, allowing the Agent to quickly review it, like, e.g., the items the user already added to the shopping cart.
The metadata can be accessed by the bot or any external system using the Conversations API Get Metadata (opens in a new tab).
API Metadata usage
You need to call the API 'send_contextual_data' when you have the data you want to send (in our example when the customer finishes their dream car configuration).
This is what it looks like:
liveChat('send_contextual_data', \{ metadata: \{ color: "red" \}, multiThreadStrategy: "ACTIVE" \});
Where:
livechat(...)- A simple function that can be called in client websites that have Live Chat installed. It is used to do all the available Live Chat API calls with two arguments: the name of called API, and the data required for the API to work.'send_contextual_data'- First argument, the name for the specific API.\{ metadata: \{ color: "red" \}, multiThreadStrategy: "ACTIVE" \}- second argument, an object containing the data for API to work. The first field is metadata itself, the second field is optional and it defines the strategy for multi-threading described later.
There are two possible API usage scenarios:
- Metadata is available before a conversation between an agent and customer is started. Live Chat stores the metadata and automatically sends it once the conversation starts. In a multi-thread, if the ALL strategy was chosen, it will just send the data to this new conversation.
- Metadata is available after a conversation between an agent and customer started. In a single thread, the data will be sent to an open conversation. In multi-thread, Live Chat tracks a list of open conversations, and based on the strategy, it will either send it to a currently ACTIVE conversation or ALL conversations.
Multi-thread strategy
Live Chat supports having multiple conversations between an agent and a customer. Considering this, API needs to know to which conversations send contextual metadata:
- ACTIVE - sends metadata to a currently active conversation
- ALL - sends metadata to all conversations between an agent and a customer
Note: This field has no impact in case of a single-thread Live Chat
Public endpoints
The following public endpoints allow you to manage the visibility of Live Chat:
liveChat('show'); - Opens the chat window with a message preview.
liveChat('hide') - Hides the Live Chat part for displaying the messages, but the Live Chat launcher stays on the page.
liveChat('show_launcher') - Displays the widget icon.
liveChat('hide_launcher') - Hides the entire widget from the page.
liveChat('set_theme', 'theme_name') - Applies the theme to the Live Chat widget.