# Subscription (Web socket)

## Overview

Our GraphQL subscription endpoint:

```
wss://api-ws.dlive.tv
```

Note that, the subscription **does not** work like normal GraphQL subscription in the sense that it returns **every possible** event with **all available** **fields** regardless of the subscription query given. So you cannot only listen to, say chat messages, and so you need to filter out uninterested events.

The server sends a "ka" message every 25 seconds. If you do not receive "ka", you should reconnect.

## Endpoints

We currently provide two web socket endpoints type. One for livestream/chat events `streamMessageReceived` and the other for chest events `treasureChestMessageReceived` .

The currently available `streamMessageReceived` events are:

| Event        | Description          |
| ------------ | -------------------- |
| Message      | Chat message         |
| Gift         | Donation             |
| Live         | Stream go live       |
| Offline      | Stream go offline    |
| Follow       | First time follow    |
| Subscription | Subscribe            |
| Delete       | Message deletion     |
| Host         | Host                 |
| ChatMode     | Change of chat mode  |
| Ban          | User banned          |
| Mod          | Moderator add/remove |
| Emote        | Emote addition       |
| Timeout      | User timeout         |

The currently available `treasureChestMessageReceived` events are:

| Event                        | Description                                                        |
| ---------------------------- | ------------------------------------------------------------------ |
| TreasureChestGiveawayEnded   | Chest giveway ended message                                        |
| TreasureChestGiveawayStarted | Chest giveway started message. Chest value should be updated to 0. |
| TreasureChestValueExpired    | Some amount of chest value is expired message                      |
| TreasureChestValueUpdated    | Chest value updated message                                        |

## How to connect

Clients establish a secure WebSocket connection to our endpoint.

Client sends

```
{
    "type": "connection_init",
    "payload": {
        "authorization" : "YOUR_APP_ACCESS_TOKEN"
    }
}
```

and expects to receive an ack:

```
{
    "type":"connection_ack"
}
```

Then client could subscribe to a particular endpoint by sending as follows:

```
{
    "id":"1",
    "type":"start",
    "payload":{
        "query":"subscription{streamMessageReceived(streamer:\"dbl-lee\"){__typename}}"
    }
}
```

The id is a unique string during current connection and "dbl-lee" is the `username` of the streamer (NOT `displayname`).

When a chat message is received, you should receive:

```
{  
   "payload":{  
      "data":{  
         "streamMessageReceived":[  
            {  
               "__typename":"ChatText",
               "type":"Message",
               "id":"80364c42-1d4e-49f2-ac16-dffc9cb2e3d8",
               "content":"hello",
               "createdAt":"1560812097380375004",
               "sender":{  
                  "__typename":"StreamchatUser",
                  "id":"streamchatuser:testpotato",
                  "username":"testpotato",
                  "displayname":"testPotato",
                  "avatar":"https://images.prd.dlivecdn.com/avatar/default22.png",
                  "partnerStatus":"NONE",
                  "badges":[]
               },
               "role":"None",
               "roomRole":"Member",
               "subscribing":false
            }
         ]
      }
   },
   "id":"1",
   "type":"data"
}
```

You could subscribe to multiple streamers and distinguish server payload by the `id` string. The schema of different events could be found by clicking corresponding types [here](https://dev.dlive.tv/schema/subscription.doc.html).

Note that, sending message is not through web socket but by mutation.

To unsubscribe to a particular endpoint, just send stop message with id as follows:

```
{
    "id":"1",
    "type":"stop"
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dlive.tv/api/api/subscription-web-socket.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.