# WebSocket Messages

The messages that the EventSub WebSocket server sends your client.

Source: https://dev.twitch.tv/docs/eventsub/websocket-reference/

This section defines the messages that the EventSub WebSocket server sends your client.

> **Note** All timestamps are in RFC3339 format and use nanoseconds instead of milliseconds.

## Welcome message {#welcome-message}

Defines the first message that the EventSub WebSocket server sends after your client connects to the server. [Read More](https://dev.twitch.tv/docs/eventsub/handling-websocket-events.md#welcome-message)

### Message Type

`session_welcome`

### Message Fields

- `metadata` — Object. An object that identifies the message.
  - `metadata.message_id` — String. An ID that uniquely identifies the message. Twitch sends messages at least once, but if Twitch is unsure of whether you received a notification, it’ll resend the message. This means you may receive a notification twice. If Twitch resends the message, the message ID will be the same.
  - `metadata.message_type` — String. The type of message, which is set to **session_welcome**.
  - `metadata.message_timestamp` — String. The UTC date and time that the message was sent.
- `payload` — Object. An object that contains the message.
  - `payload.session` — Object. An object that contains information about the connection.
    - `payload.session.id` — String. An ID that uniquely identifies this WebSocket connection. Use this ID to set the *session_id* field in all [subscription requests](https://dev.twitch.tv/docs/eventsub/manage-subscriptions.md#subscribing-to-events).
    - `payload.session.status` — String. The connection's status, which is set to **connected**.
    - `payload.session.keepalive_timeout_seconds` — Integer. The maximum number of seconds that you should expect silence before receiving a [keepalive message](#keepalive-message). For a welcome message, this is the number of seconds that you have to [subscribe to an event](https://dev.twitch.tv/docs/eventsub/manage-subscriptions.md#subscribing-to-events) after receiving the welcome message. If you don't subscribe to an event within this window, the socket is disconnected.
    - `payload.session.reconnect_url` — String, Nullable. The URL to reconnect to if you get a [Reconnect message](#reconnect-message). Is set to **null**.
    - `payload.session.connected_at` — String. The UTC date and time that the connection was created.

### Message Example

```json
{
  "metadata": {
    "message_id": "96a3f3b5-5dec-4eed-908e-e11ee657416c",
    "message_type": "session_welcome",
    "message_timestamp": "2023-07-19T14:56:51.634234626Z"
  },
  "payload": {
    "session": {
      "id": "AQoQILE98gtqShGmLD7AM6yJThAB",
      "status": "connected",
      "connected_at": "2023-07-19T14:56:51.616329898Z",
      "keepalive_timeout_seconds": 10,
      "reconnect_url": null
    }
  }
}
```

## Keepalive message {#keepalive-message}

Defines the message that the EventSub WebSocket server sends your client to indicate that the WebSocket connection is healthy. [Read More](https://dev.twitch.tv/docs/eventsub/handling-websocket-events.md#keepalive-message)

### Message Type

`session_keepalive`

### Message Fields

- `metadata` — Object. An object that identifies the message.
  - `metadata.message_id` — String. An ID that uniquely identifies the message. Twitch sends messages at least once, but if Twitch is unsure of whether you received a notification, it’ll resend the message. This means you may receive a notification twice. If Twitch resends the message, the message ID is the same.
  - `metadata.message_type` — String. The type of message, which is set to **session_keepalive**.
  - `metadata.message_timestamp` — String. The UTC date and time that the message was sent.
- `payload` — Object. An empty object.

### Message Example

```json
{
    "metadata": {
        "message_id": "84c1e79a-2a4b-4c13-ba0b-4312293e9308",
        "message_type": "session_keepalive",
        "message_timestamp": "2023-07-19T10:11:12.634234626Z"
    },
    "payload": {}
}
```

## Ping message {#ping-message}

A standard WebSocket [Ping](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.2) frame. [Read More](https://dev.twitch.tv/docs/eventsub/handling-websocket-events.md#ping-message)

## Notification message {#notification-message}

Defines a message that the EventSub WebSocket server sends your client when an event that you subscribe to occurs. [Read More](https://dev.twitch.tv/docs/eventsub/handling-websocket-events.md#notification-message)

### Message Type

`notification`

### Message Fields

- `metadata` — Object. An object that identifies the message.
  - `metadata.message_id` — String. An ID that uniquely identifies the message. Twitch sends messages at least once, but if Twitch is unsure of whether you received a notification, it’ll resend the message. This means you may receive a notification twice. If Twitch resends the message, the message ID will be the same.
  - `metadata.message_type` — String. The type of message, which is set to **notification**.
  - `metadata.message_timestamp` — String. The UTC date and time that the message was sent.
  - `metadata.subscription_type` — String. The type of event sent in the message.
  - `metadata.subscription_version` — String. The version number of the subscription type's definition. This is the same value specified in the subscription request.
- `payload` — Object. An object that contains the message.
  - `payload.subscription` — Object. An object that contains information about your subscription.
    - `payload.subscription.id` — String. An ID that uniquely identifies this subscription.
    - `payload.subscription.status` — String. The subscription's status, which is set to **enabled**.
    - `payload.subscription.type` — String. The type of event sent in the message. See the `event` field.
    - `payload.subscription.version` — String. The version number of the subscription type's definition.
    - `payload.subscription.cost` — Integer. The event's cost. See [Subscription limits](https://dev.twitch.tv/docs/eventsub/manage-subscriptions.md#subscription-limits).
    - `payload.subscription.condition` — Object. The conditions under which the event fires. For example, if you requested notifications when a broadcaster gets a new follower, this object contains the broadcaster’s ID. For information about the condition's data, see the subscription type's description in [Subscription types](https://dev.twitch.tv/docs/eventsub/reference.md).
    - `payload.subscription.transport` — Object. An object that contains information about the transport used for notifications.
      - `payload.subscription.transport.method` — String. The transport method, which is set to **websocket**.
      - `payload.subscription.transport.session_id` — String. An ID that uniquely identifies the WebSocket connection.
    - `payload.subscription.created_at` — String. The UTC date and time that the subscription was created.
  - `payload.event` — Object. The event's data. For information about the event's data, see the subscription type's description in [Subscription Types](https://dev.twitch.tv/docs/eventsub/reference.md).

### Message Example

```json
{
    "metadata": {
        "message_id": "befa7b53-d79d-478f-86b9-120f112b044e",
        "message_type": "notification",
        "message_timestamp": "2022-11-16T10:11:12.464757833Z",
        "subscription_type": "channel.follow",
        "subscription_version": "1"
    },
    "payload": {
        "subscription": {
            "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
            "status": "enabled",
            "type": "channel.follow",
            "version": "2",
            "cost": 0,
            "condition": {
                "broadcaster_user_id": "12826",
                "moderator_user_id": "12826"
            },
            "transport": {
                "method": "websocket",
                "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
            },
            "created_at": "2022-11-16T10:11:12.464757833Z"
        },
        "event": {
            "user_id": "1337",
            "user_login": "awesome_user",
            "user_name": "Awesome_User",
            "broadcaster_user_id": "12826",
            "broadcaster_user_login": "twitch",
            "broadcaster_user_name": "Twitch",
            "followed_at": "2023-07-15T18:16:11.17106713Z"
        }
    }
}
```

## Reconnect message {#reconnect-message}

Defines the message that the EventSub WebSocket server sends if the server must drop the connection. [Read More](https://dev.twitch.tv/docs/eventsub/handling-websocket-events.md#reconnect-message)

### Message Type

`session_reconnect`

### Message Fields

- `metadata` — Object. An object that identifies the message.
  - `metadata.message_id` — String. An ID that uniquely identifies the message. Twitch sends messages at least once, but if Twitch is unsure of whether you received a notification, it’ll resend the message. This means you may receive a notification twice. If Twitch resends the message, the message ID will be the same.
  - `metadata.message_type` — String. The type of message, which is set to **session_reconnect**.
  - `metadata.message_timestamp` — String. The UTC date and time that the message was sent.
- `payload` — Object. An object that contains the message.
  - `payload.session` — Object. An object that contains information about the connection.
    - `payload.session.id` — String. An ID that uniquely identifies this WebSocket connection.
    - `payload.session.status` — String. The connection's status, which is set to **reconnecting**.
    - `payload.session.keepalive_timeout_seconds` — Integer, Nullable. Is set to **null**.
    - `payload.session.reconnect_url` — String. The URL to reconnect to. Use this URL as is; do not modify it. The connection automatically includes the subscriptions from the old connection.
    - `payload.session.connected_at` — String. The UTC date and time when the connection was created.

### Message Example

```json
{
    "metadata": {
        "message_id": "84c1e79a-2a4b-4c13-ba0b-4312293e9308",
        "message_type": "session_reconnect",
        "message_timestamp": "2022-11-18T09:10:11.634234626Z"
    },
    "payload": {
        "session": {
            "id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB",
            "status": "reconnecting",
            "keepalive_timeout_seconds": null,
            "reconnect_url": "wss://eventsub.wss.twitch.tv?...",
            "connected_at": "2022-11-16T10:11:12.634234626Z"
        }
    }
}
```

## Revocation message {#revocation-message}

Defines the message that the EventSub WebSocket server sends if the user no longer exists or they revoked the authorization token that the subscription relied on. [Read More](https://dev.twitch.tv/docs/eventsub/handling-websocket-events.md#revocation-message)

### Message Type

`revocation`

### Message Fields

- `metadata` — Object. An object that identifies the message.
  - `metadata.message_id` — String. An ID that uniquely identifies the message. Twitch sends messages at least once, but if Twitch is unsure of whether you received a notification, it’ll resend the message. This means you may receive a notification twice. If Twitch resends the message, the message ID will be the same.
  - `metadata.message_type` — String. The type of message, which is set to **revocation**.
  - `metadata.message_timestamp` — String. The UTC date and time that the message was sent.
  - `metadata.subscription_type` — String. The type of event sent in the message.
  - `metadata.subscription_version` — String. The version number of the subscription type's definition. This is the same value specified in the subscription request.
- `payload` — Object. An object that contains the message.
  - `payload.subscription` — Object. An object that contains information about your subscription.
    - `payload.subscription.id` — String. An ID that uniquely identifies this subscription.
    - `payload.subscription.status` — String. The subscription's status.
      Possible values:
      - `authorization_revoked`: The user in the condition object revoked the authorization that let you get events on their behalf.
      - `user_removed`: The user in the condition object is no longer a Twitch user.
      - `version_removed`: The subscribed to subscription type and version is no longer supported.
    - `payload.subscription.type` — String. The type of event sent in the message.
    - `payload.subscription.version` — String. The version number of the subscription type's definition.
    - `payload.subscription.cost` — Integer. The event's cost. See [Subscription limits](https://dev.twitch.tv/docs/eventsub/manage-subscriptions.md#subscription-limits).
    - `payload.subscription.condition` — Object. The conditions under which the event fires. For example, if you requested notifications when a broadcaster gets a new follower, this object contains the broadcaster’s ID. For information about the condition's data, see the subscription type's description in [Subscription Types](https://dev.twitch.tv/docs/eventsub/reference.md).
    - `payload.subscription.transport` — Object. An object that contains information about the transport used for notifications.
      - `payload.subscription.transport.method` — String. The transport method, which is set to **websocket**.
      - `payload.subscription.transport.session_id` — String. An ID that uniquely identifies the WebSocket connection.
    - `payload.subscription.created_at` — String. The UTC date and time that the subscription was created.

### Message Example

```json
{
    "metadata": {
        "message_id": "84c1e79a-2a4b-4c13-ba0b-4312293e9308",
        "message_type": "revocation",
        "message_timestamp": "2022-11-16T10:11:12.464757833Z",
        "subscription_type": "channel.follow",
        "subscription_version": "1"
    },
    "payload": {
        "subscription": {
            "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
            "status": "authorization_revoked",
            "type": "channel.follow",
            "version": "2",
            "cost": 0,
            "condition": {
                "broadcaster_user_id": "12826",
                "moderator_user_id": "12826"
            },
            "transport": {
                "method": "websocket",
                "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
            },
            "created_at": "2022-11-16T10:11:12.464757833Z"
        }
    }
}
```

## Close message {#close-message}

A standard WebSocket [Close](https://datatracker.ietf.org/doc/html/rfc6455#section-5.5.1) frame.
[Read More](https://dev.twitch.tv/docs/eventsub/handling-websocket-events.md#close-message)

The following table lists the reasons for closing the connection.

### Close Codes

- **4000 Internal server error** — Indicates a problem with the server (similar to an HTTP 500 status code).
- **4001 Client sent inbound traffic** — Sending outgoing messages to the server is prohibited with the exception of pong messages.
- **4002 Client failed ping-pong** — You must respond to ping messages with a pong message. See [Ping message](#ping-message).
- **4003 Connection unused** — When you connect to the server, you must create a subscription within 10 seconds or the connection is closed. The time limit is subject to change.
- **4004 Reconnect grace time expired** — When you receive a **session_reconnect** message, you have 30 seconds to reconnect to the server and close the old connection. See [Reconnect message](#reconnect-message).
- **4005 Network timeout** — Transient network timeout.
- **4006 Network error** — Transient network error.
- **4007 Invalid reconnect** — The reconnect URL is invalid.