You're in the right place! Segment documentation is now part of Twilio Docs. The content you are used to is still here—just in a new home with a refreshed look.

Spec: Live Chat Events

This guide explains what data should be sent to Segment from Live Chat tools and hence is targeted to partners who send Live Chat data back into Segment rather than targeted to customers themselves. The semantic events detailed below represent the ideal for Live Chat events; not every Live Chat tool supports all of these events or all their properties.

Overview

Every Live Chat tool is built around the concept of "conversations" between an agent at the company and a customer who has a question.

Each conversation starts when a customer sends their first message. Within the conversation the customer receives and sends messages. In some situations the conversation also has a clearly recognizable end when the customer or agent explicitly indicates the conversation has ended.

Events

The Live Chat category has the following semantic events:

Live Chat Conversation Started

This event should be sent when a customer sends their first message.

Properties

This event supports the following semantic properties:

Property	Type	Description
`agent_id`	String	The agent's ID.
`agent_name`	String	The agent's real name.
`agent_username`	String	The agent's username.
`conversation_id`	String	The conversation's ID.
`conversation_duration`	Number	The conversation duration in seconds.
`message_id`	String	The message's ID.

Example

1{
2  "userId": "019mr8mf4r",
3  "action": "track",
4  "event": "Live Chat Conversation Started",
5  "properties": {
6    "agent_id": "bce89acdd11901",
7    "agent_name": "Peter Gibbons",
8    "agent_username": "pgibbons",
9    "conversation_duration": 0,
10    "conversation_id": "abd627dbecffc",
11    "message_body": "But my stapler...",
12    "message_id": "beaffc193618cbe"
13  }
14}

Live Chat Conversation Ended

This event should be sent when customer or agent explicitly indicates the conversation has ended.

Properties

This event supports the following semantic properties:

Property	Type	Description
`agent_id`	String	The agent's ID.
`agent_name`	String	The agent's real name.
`agent_username`	String	The agent's username.
`conversation_id`	String	The conversation's ID.
`conversation_duration`	Number	The conversation duration in seconds
`message_id`	String	The message's ID.

Example

1{
2  "userId": "019mr8mf4r",
3  "action": "track",
4  "event": "Live Chat Conversation Ended",
5  "properties": {
6    "agent_id": "bce89acdd11901",
7    "agent_name": "Peter Gibbons",
8    "agent_username": "pgibbons",
9    "conversation_duration": 203,
10    "conversation_id": "abd627dbecffc",
11    "message_body": "I\'ll... set the building on fire",
12    "message_id": "bcadac1183618cbe"
13  }
14}

Live Chat Message Sent

This event should be sent when customer sends a message to the agent.

Properties

This event supports the following semantic properties:

Property	Type	Description
`agent_id`	String	The agent's ID.
`agent_name`	String	The agent's real name.
`agent_username`	String	The agent's username.
`conversation_id`	String	The conversation's ID.
`conversation_duration`	Number	The conversation duration in seconds.
`message_id`	String	The message's ID.

Example

1{
2  "userId": "019mr8mf4r",
3  "action": "track",
4  "event": "Live Chat Message Sent",
5  "properties": {
6    "agent_id": "bce89acdd11901",
7    "agent_name": "Peter Gibbons",
8    "agent_username": "pgibbons",
9    "conversation_duration": 45,
10    "conversation_id": "abd627dbecffc",
11    "message_body": "But then they switched from the Swingline to the Boston stapler!",
12    "message_id": "beaffc193618cbe"
13  }
14}

Live Chat Message Received

This event should be sent when the customer receives a message from the agent.

Properties

This event supports the following semantic properties:

Property	Type	Description
`agent_id`	String	The agent's ID.
`agent_name`	String	The agent's real name.
`agent_username`	String	The agent's username.
`conversation_id`	String	The conversation's ID.
`conversation_duration`	Number	The conversation duration in seconds.
`message_id`	String	The message's ID.

Example

1{
2  "userId": "019mr8mf4r",
3  "action": "track",
4  "event": "Live Chat Message Received",
5  "properties": {
6    "agent_id": "bce89acdd11901",
7    "agent_name": "Peter Gibbons",
8    "agent_username": "pgibbons",
9    "conversation_duration": 98,
10    "conversation_id": "abd627dbecffc",
11    "message_body": "Yeah, uh huh, okay, Milton",
12    "message_id": "beaffc193618cbe"
13  }
14}