# 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"
}
```