WebSocket Messages

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

Defines the first message that the EventSub WebSocket server sends after your client connects to the server. Read More

Message Type

Type: session_welcome

Message Fields

metadataObject
An object that identifies the message.
Hide child attributesShow child attributes
- metadata.message_idString
  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_typeString
  The type of message, which is set to session_welcome.
- metadata.message_timestampString
  The UTC date and time that the message was sent.
payloadObject
An object that contains the message.
Hide child attributesShow child attributes
- payload.sessionObject
  An object that contains information about the connection.
  Hide child attributesShow child attributes
  - payload.session.idString
    An ID that uniquely identifies this WebSocket connection. Use this ID to set the session_id field in all subscription requests.
  - payload.session.statusString
    The connection's status, which is set to connected.
  - payload.session.keepalive_timeout_secondsInteger
    The maximum number of seconds that you should expect silence before receiving a keepalive message. For a welcome message, this is the number of seconds that you have to subscribe to an event after receiving the welcome message. If you don't subscribe to an event within this window, the socket is disconnected.
  - payload.session.reconnect_urlStringNullable
    The URL to reconnect to if you get a Reconnect message. Is set to null.
  - payload.session.connected_atString
    The UTC date and time that the connection was created.

Message Example

{
  "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

Defines the message that the EventSub WebSocket server sends your client to indicate that the WebSocket connection is healthy. Read More

Message Type

Type: session_keepalive

Message Fields

metadataObject
An object that identifies the message.
Hide child attributesShow child attributes
- metadata.message_idString
  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_typeString
  The type of message, which is set to session_keepalive.
- metadata.message_timestampString
  The UTC date and time that the message was sent.
payloadObject
An empty object.

Message Example

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

Ping message

A standard WebSocket Ping frame. Read More

Notification message

Defines a message that the EventSub WebSocket server sends your client when an event that you subscribe to occurs. Read More

Message Type

Type: notification

Message Fields

metadataObject
An object that identifies the message.
Hide child attributesShow child attributes
- metadata.message_idString
  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_typeString
  The type of message, which is set to notification.
- metadata.message_timestampString
  The UTC date and time that the message was sent.
- metadata.subscription_typeString
  The type of event sent in the message.
- metadata.subscription_versionString
  The version number of the subscription type's definition. This is the same value specified in the subscription request.
payloadObject
An object that contains the message.
Hide child attributesShow child attributes
- payload.subscriptionObject
  An object that contains information about your subscription.
  Hide child attributesShow child attributes
  - payload.subscription.idString
    An ID that uniquely identifies this subscription.
  - payload.subscription.statusString
    The subscription's status, which is set to enabled.
  - payload.subscription.typeString
    The type of event sent in the message. See the event field.
  - payload.subscription.versionString
    The version number of the subscription type's definition.
  - payload.subscription.costInteger
    The event's cost. See Subscription limits.
  - payload.subscription.conditionObject
    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.
  - payload.subscription.transportObject
    An object that contains information about the transport used for notifications.
    Hide child attributesShow child attributes
    payload.subscription.transport.methodString
    The transport method, which is set to websocket.
    payload.subscription.transport.session_idString
    An ID that uniquely identifies the WebSocket connection.
  - payload.subscription.created_atString
    The UTC date and time that the subscription was created.
- payload.eventObject
  The event's data. For information about the event's data, see the subscription type's description in Subscription Types.

Message Example

{
    "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

Defines the message that the EventSub WebSocket server sends if the server must drop the connection. Read More

Message Type

Type: session_reconnect

Message Fields

metadataObject
An object that identifies the message.
Hide child attributesShow child attributes
- metadata.message_idString
  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_typeString
  The type of message, which is set to session_reconnect.
- metadata.message_timestampString
  The UTC date and time that the message was sent.
payloadObject
An object that contains the message.
Hide child attributesShow child attributes
- payload.sessionObject
  An object that contains information about the connection.
  Hide child attributesShow child attributes
  - payload.session.idString
    An ID that uniquely identifies this WebSocket connection.
  - payload.session.statusString
    The connection's status, which is set to reconnecting.
  - payload.session.keepalive_timeout_secondsIntegerNullable
    Is set to null.
  - payload.session.reconnect_urlString
    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_atString
    The UTC date and time when the connection was created.

Message Example

{
    "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

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

Message Type

Type: revocation

Message Fields

metadataObject
An object that identifies the message.
Hide child attributesShow child attributes
- metadata.message_idString
  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_typeString
  The type of message, which is set to revocation.
- metadata.message_timestampString
  The UTC date and time that the message was sent.
- metadata.subscription_typeString
  The type of event sent in the message.
- metadata.subscription_versionString
  The version number of the subscription type's definition. This is the same value specified in the subscription request.
payloadObject
An object that contains the message.
Hide child attributesShow child attributes
- payload.subscriptionObject
  An object that contains information about your subscription.
  Hide child attributesShow child attributes
  - payload.subscription.idString
    An ID that uniquely identifies this subscription.
  - payload.subscription.statusString
    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.typeString
    The type of event sent in the message.
  - payload.subscription.versionString
    The version number of the subscription type's definition.
  - payload.subscription.costInteger
    The event's cost. See Subscription limits.
  - payload.subscription.conditionObject
    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.
  - payload.subscription.transportObject
    An object that contains information about the transport used for notifications.
    Hide child attributesShow child attributes
    payload.subscription.transport.methodString
    The transport method, which is set to websocket.
    payload.subscription.transport.session_idString
    An ID that uniquely identifies the WebSocket connection.
  - payload.subscription.created_atString
    The UTC date and time that the subscription was created.

Message Example

{
    "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

A standard WebSocket Close frame. Read More

The following table lists the reasons for closing the connection.

Close Codes

4000Internal server error: Indicates a problem with the server (similar to an HTTP 500 status code).
4001Client sent inbound traffic: Sending outgoing messages to the server is prohibited with the exception of pong messages.
4002Client failed ping-pong: You must respond to ping messages with a pong message. See Ping message.
4003Connection 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.
4004Reconnect 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.
4005Network timeout: Transient network timeout.
4006Network error: Transient network error.
4007Invalid reconnect: The reconnect URL is invalid.