# Live chat events

## How it works[](#how-it-works)

If you send live chat events into Data Customer.io, you should shape incoming events using the formats on this page. We use this specification to support default actions—any we have now and ones we might add in the future. If you send live chat events that conform to this specification, you’ll be ready to trigger downstream actions in integrations that rely on an live chat events. See [Live Chat Events](/integrations/api/cdp/live-chat/) if you want to download the specification or try out live chat events.

## Events in the live chat lifecycle[](#events-in-the-live-chat-lifecycle)

Live chats typically produce the following events. To make the most of your live chat events, make sure that you use the event names and structures set below.

In general, you’ll open a conversation, send and receive messages, and then close the conversation.

*   Live Chat Conversation Started
*   LIve Chat Conversation Ended
*   Live Chat Message Sent
*   Live Chat Message Received

## Live Chat Events[](#live-chat-events)

Live chat consists of four events. You can see payloads below, but the schema is the same for each; only the event `name` changes. These events are from your perspective, so you’ll send *Live Chat Message Sent* events when you or your agent sends a message and *Live Chat Message Received* events when you or your agent receives a message.

While all `properties` in events are optional, you should send the `conversation_id` and `message_id` properties in your events at a minimum, so you can trace individual messages to a specific chat instance.

#### Live Chat Conversation Started[](#Live Chat Conversation Started)

```json
{
  "userId": "020ba8yf4r",
  "action": "track",
  "event": "Live Chat Conversation Started",
  "properties": {
    "agent_id": "adf21fcad99100",
    "agent_name": "Wile E Coyote",
    "agent_username": "wileecoyte",
    "conversation_duration": 0,
    "conversation_id": "abd627dbecffc",
    "message_body": "Meep Meep",
    "message_id": "fgdaab013614cda"
  }
}
```

#### Live Chat Conversation Ended[](#Live Chat Conversation Ended)

```json
{
  "userId": "020ba8yf4r",
  "action": "track",
  "event": "Live Chat Conversation Ended",
  "properties": {
    "agent_id": "adf21fcad99100",
    "agent_name": "Wile E Coyote",
    "agent_username": "wileecoyte",
    "conversation_duration": 120,
    "conversation_id": "abd627dbecffc",
    "message_body": "That's all, folks!",
    "message_id": "fgdaab013614cda"
  }
}
```

#### Live Chat Message Sent[](#Live Chat Message Sent)

```json
{
  "userId": "020ba8yf4r",
  "action": "track",
  "event": "Live Chat Message Sent",
  "properties": {
    "agent_id": "adf21fcad99100",
    "agent_name": "Wile E Coyote",
    "agent_username": "wileecoyte",
    "conversation_duration": 80,
    "conversation_id": "abd627dbecffc",
    "message_body": "*Help!*",
    "message_id": "fgdaab013614cda"
  }
}
```

#### Live Chat Message Received[](#Live Chat Message Received)

```json
{
  "userId": "020ba8yf4r",
  "action": "track",
  "event": "Live Chat Message Received",
  "properties": {
    "agent_id": "adf21fcad99100",
    "agent_name": "Wile E Coyote",
    "agent_username": "wileecoyte",
    "conversation_duration": 40,
    "conversation_id": "abd627dbecffc",
    "message_body": "Meep Meep",
    "message_id": "fgdaab013614cda"
  }
}
```

*   agent\_id string
    
    The ID of the agent taking the conversation.
    
*   agent\_name string
    
    The real name of the agent.
    
*   agent\_username string
    
    The username of the agent.
    
*   conversation\_duration integer
    
    The duration of the conversation in seconds. 0 when the conversation starts, and the number of seconds indicates the time in the conversation when each message
    
*   conversation\_id string
    
    The ID of the conversation.
    
*   message\_id string
    
    The ID of the message that starts the conversation.