Chat - EventSub Reference | Twitch Developers

Channel Chat Settings Update

This event sends a notification when a broadcaster's chat settings are updated.

Subscription

Type: channel.chat_settings.update
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.
- The channel:bot scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat_settings.update.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  User ID of the channel to receive chat settings update events for.
- condition.user_idStringRequired
  The user ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    User ID of the channel to receive chat settings update events for.
  - subscription.condition.user_idString
    The user ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The ID of the broadcaster specified in the request.
- event.broadcaster_user_loginString
  The login of the broadcaster specified in the request.
- event.broadcaster_user_nameString
  The user name of the broadcaster specified in the request.
- event.emote_modeBoolean
  A Boolean value that determines whether chat messages must contain only emotes. True if only messages that are 100% emotes are allowed; otherwise false.
- event.follower_modeBoolean
  A Boolean value that determines whether the broadcaster restricts the chat room to followers only, based on how long they've followed.
  
  True if the broadcaster restricts the chat room to followers only; otherwise false.
  
  See follower_mode_duration_minutes for how long the followers must have followed the broadcaster to participate in the chat room.
- event.follower_mode_duration_minutesIntegerNullable
  The length of time, in minutes, that the followers must have followed the broadcaster to participate in the chat room. See follower_mode.
  
  Null if follower_mode is false.
- event.slow_modeBoolean
  A Boolean value that determines whether the broadcaster limits how often users in the chat room are allowed to send messages.
  
  Is true, if the broadcaster applies a delay; otherwise, false.
  
  See slow_mode_wait_time_seconds for the delay.
- event.slow_mode_wait_time_secondsIntegerNullable
  The amount of time, in seconds, that users need to wait between sending messages. See slow_mode.
  
  Null if slow_mode is false.
- event.subscriber_modeBoolean
  A Boolean value that determines whether only users that subscribe to the broadcaster's channel can talk in the chat room.
  
  True if the broadcaster restricts the chat room to subscribers only; otherwise false.
- event.unique_chat_modeBoolean
  A Boolean value that determines whether the broadcaster requires users to post only unique messages in the chat room.
  
  True if the broadcaster requires unique messages only; otherwise false.

Subscription Request Body Example

{
  "type": "channel.chat_settings.update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat_settings.update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat_settings.update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.chat_settings.update",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337",
            "user_id": "9001"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2023-04-11T10:11:12.123Z"
    },
    "event": {
        "broadcaster_user_id": "1337",
        "broadcaster_user_login": "cool_user",
        "broadcaster_user_name": "Cool_User",
        "emote_mode": true,
        "follower_mode": false,
        "follower_mode_duration_minutes": null,
        "slow_mode": true,
        "slow_mode_wait_time_seconds": 10,
        "subscriber_mode": false,
        "unique_chat_mode": false
    }
}

Channel Chat Clear

The channel.chat.clear subscription type sends a notification when a moderator or bot clears all messages from the chat room.

Subscription

Type: channel.chat.clear
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.
- The channel:bot scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat.clear.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  User ID of the channel to receive chat clear events for.
- condition.user_idStringRequired
  The user ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    User ID of the channel to receive chat clear events for.
  - subscription.condition.user_idString
    The user ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The broadcaster user ID.
- event.broadcaster_user_nameString
  The broadcaster display name.
- event.broadcaster_user_loginString
  The broadcaster login.

Subscription Request Body Example

{
  "type": "channel.chat.clear",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat.clear",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat.clear",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.chat.clear",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337",
            "user_id": "9001"
        },
        "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2023-04-11T10:11:12.123Z"
    },
    "event": {
        "broadcaster_user_id": "1337",
        "broadcaster_user_name": "Cool_User",
        "broadcaster_user_login": "cool_user"
    }
}

Channel Chat Clear User Messages

The channel.chat.clear_user_messages subscription type sends a notification when a moderator or bot clears all messages for a specific user.

Subscription

Type: channel.chat.clear_user_messages
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.
- The channel:bot scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat.clear_user_messages.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  User ID of the channel to receive chat clear user messages events for.
- condition.user_idStringRequired
  The user ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    User ID of the channel to receive chat clear user messages events for.
  - subscription.condition.user_idString
    The user ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The broadcaster user ID.
- event.broadcaster_user_nameString
  The broadcaster display name.
- event.broadcaster_user_loginString
  The broadcaster login.
- event.target_user_idString
  The ID of the user that was banned or put in a timeout. All of their messages are deleted.
- event.target_user_nameString
  The user name of the user that was banned or put in a timeout.
- event.target_user_loginString
  The user login of the user that was banned or put in a timeout.

Subscription Request Body Example

{
  "type": "channel.chat.clear_user_messages",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat.clear_user_messages",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat.clear_user_messages",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.chat.clear_user_messages",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337",
            "user_id": "9001"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2023-04-11T10:11:12.123Z"
    },
    "event": {
        "broadcaster_user_id": "1337",
        "broadcaster_user_name": "Cool_User",
        "broadcaster_user_login": "cool_user",
        "target_user_id": "7734",
        "target_user_name": "Uncool_viewer",
        "target_user_login": "uncool_viewer"
    }
}

Channel Chat Message

The channel.chat.message subscription type sends a notification when any user sends a message to a channel's chat room.

Subscription

Type: channel.chat.message
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.
- The channel:bot scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat.message.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  The User ID of the channel to receive chat message events for.
- condition.user_idStringRequired
  The User ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    The User ID of the channel to receive chat message events for.
  - subscription.condition.user_idString
    The User ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The broadcaster user ID.
- event.broadcaster_user_nameString
  The broadcaster display name.
- event.broadcaster_user_loginString
  The broadcaster login.
- event.chatter_user_idString
  The user ID of the user that sent the message.
- event.chatter_user_nameString
  The user name of the user that sent the message.
- event.chatter_user_loginString
  The user login of the user that sent the message.
- event.message_idString
  A UUID that identifies the message.
- event.messageObject
  The structured chat message.
  Hide child attributesShow child attributes
  - event.message.textString
    The chat message in plain text.
  - event.message.fragmentsObject[]
    Ordered list of chat message fragments.
    Hide child attributesShow child attributes
    event.message.fragments.typeString
    The type of message fragment.
    Possible values
    text
    cheermote
    emote
    mention
    gif
    event.message.fragments.textString
    Message text in fragment.
    event.message.fragments.cheermoteObjectNullable
    Metadata pertaining to the cheermote.
    Hide child attributesShow child attributes
    event.message.fragments.cheermote.prefixString
    The name portion of the Cheermote string that you use in chat to cheer Bits, converted to lowercase. The full Cheermote string is the concatenation of {prefix} + {number of Bits}.
    
    For example, if the prefix is "cheer" and you want to cheer 100 Bits, the full Cheermote string is cheer100. When the Cheermote string is entered in chat, Twitch converts it to the image associated with the Bits tier that was cheered.
    event.message.fragments.cheermote.bitsInteger
    The amount of Bits cheered.
    event.message.fragments.cheermote.tierInteger
    The tier level of the cheermote.
    event.message.fragments.emoteObjectNullable
    Metadata pertaining to the emote.
    Hide child attributesShow child attributes
    event.message.fragments.emote.idString
    An ID that uniquely identifies this emote.
    event.message.fragments.emote.emote_set_idString
    An ID that identifies the emote set that the emote belongs to.
    event.message.fragments.emote.owner_idString
    The ID of the broadcaster who owns the emote.
    event.message.fragments.emote.formatString[]
    The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static. But if the emote is available as a static PNG and an animated GIF, the array contains static and animated.
    Possible values
    animated
    An animated GIF is available for this emote.
    static
    A static PNG file is available for this emote.
    event.message.fragments.mentionObjectNullable
    Metadata pertaining to the mention.
    Hide child attributesShow child attributes
    event.message.fragments.mention.user_idString
    The user ID of the mentioned user.
    event.message.fragments.mention.user_nameString
    The user name of the mentioned user.
    event.message.fragments.mention.user_loginString
    The user login of the mentioned user.
    event.message.fragments.gifObjectNullable
    Metadata pertaining to the GIF.
    Hide child attributesShow child attributes
    event.message.fragments.gif.idString
    An ID that uniquely identifies this GIF.
    event.message.fragments.gif.urlString
    The URL of the GIF asset. Applications rendering the GIF must use the full URL provided; it must not be modified.
- event.message_typeString
  The type of message.
  Possible values
  - text
  - channel_points_highlighted
  - channel_points_sub_only
  - user_intro
  - power_ups_message_effect
  - power_ups_gigantified_emote
- event.badgesObject[]
  List of chat badges.
  Hide child attributesShow child attributes
  - event.badges.set_idString
    An ID that identifies this set of chat badges. For example, Bits or Subscriber.
  - event.badges.idString
    An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
  - event.badges.infoString
    Contains metadata related to the chat badges in the badges tag. Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
- event.cheerObjectNullable
  Metadata if this message is a cheer.
  Hide child attributesShow child attributes
  - event.cheer.bitsInteger
    The amount of Bits the user cheered.
- event.colorString
  The color of the user's name in the chat room. This is a hexadecimal RGB color code in the form, #<RGB>. This tag may be empty if it is never set.
- event.replyObjectNullable
  Metadata if this message is a reply.
  Hide child attributesShow child attributes
  - event.reply.parent_message_idString
    An ID that uniquely identifies the parent message that this message is replying to.
  - event.reply.parent_message_bodyString
    The message body of the parent message.
  - event.reply.parent_user_idString
    User ID of the sender of the parent message.
  - event.reply.parent_user_nameString
    User name of the sender of the parent message.
  - event.reply.parent_user_loginString
    User login of the sender of the parent message.
  - event.reply.thread_message_idString
    An ID that identifies the parent message of the reply thread.
  - event.reply.thread_user_idString
    User ID of the sender of the thread's parent message.
  - event.reply.thread_user_nameString
    User name of the sender of the thread's parent message.
  - event.reply.thread_user_loginString
    User login of the sender of the thread's parent message.
- event.channel_points_custom_reward_idStringNullable
  The ID of a channel points custom reward that was redeemed.
- event.source_broadcaster_user_idStringNullable
  The broadcaster user ID of the channel the message was sent from. Is null when the message happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_broadcaster_user_nameStringNullable
  The user name of the broadcaster of the channel the message was sent from. Is null when the message happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_broadcaster_user_loginStringNullable
  The login of the broadcaster of the channel the message was sent from. Is null when the message happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_message_idStringNullable
  The UUID that identifies the source message from the channel the message was sent from. Is null when the message happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_badgesObject[]Nullable
  The list of chat badges for the chatter in the channel the message was sent from. Is null when the message happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
  Hide child attributesShow child attributes
  - event.source_badges.set_idString
    The ID that identifies this set of chat badges. For example, Bits or Subscriber.
  - event.source_badges.idString
    The ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
  - event.source_badges.infoString
    Contains metadata related to the chat badges in the badges tag. Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
- event.is_source_onlyBooleanNullable
  Determines if a message delivered during a shared chat session is only sent to the source channel. Has no effect if the message is not sent during a shared chat session.

Subscription Request Body Example

{
  "type": "channel.chat.message",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat.message",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat.message",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
  "subscription": {
    "id": "0b7f3361-672b-4d39-b307-dd5b576c9b27",
    "status": "enabled",
    "type": "channel.chat.message",
    "version": "1",
    "condition": {
      "broadcaster_user_id": "1971641",
      "user_id": "2914196"
    },
    "transport": {
      "method": "websocket",
      "session_id": "AgoQHR3s6Mb4T8GFB1l3DlPfiRIGY2VsbC1h"
    },
    "created_at": "2023-11-06T18:11:47.492253549Z",
    "cost": 0
  },
  "event": {
    "broadcaster_user_id": "1971641",
    "broadcaster_user_login": "streamer",
    "broadcaster_user_name": "streamer",
    "chatter_user_id": "4145994",
    "chatter_user_login": "viewer32",
    "chatter_user_name": "viewer32",
    "message_id": "cc106a89-1814-919d-454c-f4f2f970aae7",
    "message": {
      "text": "Hi chat",
      "fragments": [
        {
          "type": "text",
          "text": "Hi chat",
          "cheermote": null,
          "emote": null,
          "mention": null
        }
      ]
    },
    "color": "#00FF7F",
    "badges": [
      {
        "set_id": "moderator",
        "id": "1",
        "info": ""
      },
      {
        "set_id": "subscriber",
        "id": "12",
        "info": "16"
      },
      {
        "set_id": "sub-gifter",
        "id": "1",
        "info": ""
      }
    ],
    "message_type": "text",
    "cheer": null,
    "reply": null,
    "channel_points_custom_reward_id": null,
    "source_broadcaster_user_id": null,
    "source_broadcaster_user_login": null,
    "source_broadcaster_user_name": null,
    "source_message_id": null,
    "source_badges": null
  }
}

Channel Chat Message Delete

The channel.chat.message_delete subscription type sends a notification when a moderator removes a specific message.

Subscription

Type: channel.chat.message_delete
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.
- The channel:bot scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat.message_delete.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  User ID of the channel to receive chat message delete events for.
- condition.user_idStringRequired
  The user ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    User ID of the channel to receive chat message delete events for.
  - subscription.condition.user_idString
    The user ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The broadcaster user ID.
- event.broadcaster_user_nameString
  The broadcaster display name.
- event.broadcaster_user_loginString
  The broadcaster login.
- event.target_user_idString
  The ID of the user whose message was deleted.
- event.target_user_nameString
  The user name of the user whose message was deleted.
- event.target_user_loginString
  The user login of the user whose message was deleted.
- event.message_idString
  A UUID that identifies the message that was removed.

Subscription Request Body Example

{
  "type": "channel.chat.message_delete",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat.message_delete",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat.message_delete",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Channel Chat Notification

The channel.chat.notification subscription type sends a notification when an event that appears in chat occurs, such as someone subscribing to the channel or a subscription is gifted.

Subscription

Type: channel.chat.notification
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.
- The channel:bot scope for the user represented by the broadcaster_user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat.notification.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  User ID of the channel to receive chat notification events for.
- condition.user_idStringRequired
  The user ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    User ID of the channel to receive chat notification events for.
  - subscription.condition.user_idString
    The user ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The broadcaster user ID.
- event.broadcaster_user_nameString
  The broadcaster display name.
- event.broadcaster_user_loginString
  The broadcaster login.
- event.chatter_user_idString
  The user ID of the user that sent the message.
- event.chatter_user_nameString
  The display name of the user that sent the message.
- event.chatter_user_loginString
  The user login of the user that sent the message.
- event.chatter_is_anonymousBoolean
  Whether or not the chatter is anonymous.
- event.colorString
  The color of the user's name in the chat room.
- event.badgesObject[]
  The list of chat badges for the chatter in the channel the message was sent from.
  Hide child attributesShow child attributes
  - event.badges.set_idString
    An ID that identifies this set of chat badges. For example, Bits or Subscriber.
  - event.badges.idString
    An ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
  - event.badges.infoString
    Contains metadata related to the chat badges in the badges tag. Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
- event.system_messageString
  The message Twitch shows in the chat room for this notice.
- event.message_idString
  A UUID that identifies the message.
- event.messageObject
  The structured chat message.
  Hide child attributesShow child attributes
  - event.message.textString
    The chat message in plain text.
  - event.message.fragmentsObject[]
    Ordered list of chat message fragments.
    Hide child attributesShow child attributes
    event.message.fragments.typeString
    The type of message fragment.
    Possible values
    text
    cheermote
    emote
    mention
    event.message.fragments.textString
    Message text in fragment.
    event.message.fragments.cheermoteObjectNullable
    Metadata pertaining to the cheermote.
    Hide child attributesShow child attributes
    event.message.fragments.cheermote.prefixString
    The name portion of the Cheermote string that you use in chat to cheer Bits, converted to lowercase. The full Cheermote string is the concatenation of {prefix} + {number of Bits}.
    
    For example, if the prefix is "cheer" and you want to cheer 100 Bits, the full Cheermote string is cheer100. When the Cheermote string is entered in chat, Twitch converts it to the image associated with the Bits tier that was cheered.
    event.message.fragments.cheermote.bitsInteger
    The amount of Bits cheered.
    event.message.fragments.cheermote.tierInteger
    The tier level of the cheermote.
    event.message.fragments.emoteObjectNullable
    Metadata pertaining to the emote.
    Hide child attributesShow child attributes
    event.message.fragments.emote.idString
    An ID that uniquely identifies this emote.
    event.message.fragments.emote.emote_set_idString
    An ID that identifies the emote set that the emote belongs to.
    event.message.fragments.emote.owner_idString
    The ID of the broadcaster who owns the emote.
    event.message.fragments.emote.formatString[]
    The formats that the emote is available in. For example, if the emote is available only as a static PNG, the array contains only static. But if the emote is available as a static PNG and an animated GIF, the array contains static and animated.
    Possible values
    animated
    An animated GIF is available for this emote.
    static
    A static PNG file is available for this emote.
    event.message.fragments.mentionObjectNullable
    Metadata pertaining to the mention.
    Hide child attributesShow child attributes
    event.message.fragments.mention.user_idString
    The user ID of the mentioned user.
    event.message.fragments.mention.user_nameString
    The user name of the mentioned user.
    event.message.fragments.mention.user_loginString
    The user login of the mentioned user.
- event.notice_typeString
  The type of notice.
  Possible values
  - sub
  - resub
  - sub_gift
  - community_sub_gift
  - gift_paid_upgrade
  - prime_paid_upgrade
  - raid
  - unraid
  - pay_it_forward
  - announcement
  - bits_badge_tier
  - charity_donation
  - watch_streak
  - modiversary
  - gifted_drops_summary
  - shared_chat_sub
  - shared_chat_resub
  - shared_chat_sub_gift
  - shared_chat_community_sub_gift
  - shared_chat_gift_paid_upgrade
  - shared_chat_prime_paid_upgrade
  - shared_chat_raid
  - shared_chat_pay_it_forward
  - shared_chat_announcement
  - shared_chat_modiversary
  - shared_chat_gifted_drops_summary
  - unknown
- event.subObjectNullable
  Information about the sub event. Null if notice_type is not sub.
  Hide child attributesShow child attributes
  - event.sub.sub_tierString
    The type of subscription plan being used.
    Possible values
    1000
    First level of paid or Prime subscription.
    2000
    Second level of paid subscription.
    3000
    Third level of paid subscription.
  - event.sub.is_primeBoolean
    Indicates if the subscription was obtained through Amazon Prime.
  - event.sub.duration_monthsInteger
    The number of months the subscription is for.
- event.resubObjectNullable
  Information about the resub event. Null if notice_type is not resub.
  Hide child attributesShow child attributes
  - event.resub.cumulative_monthsInteger
    The total number of months the user has subscribed.
  - event.resub.duration_monthsInteger
    The number of months the subscription is for.
  - event.resub.streak_monthsIntegerNullable
    The total number of months the user has subscribed.
  - event.resub.sub_tierString
    The type of subscription plan being used.
    Possible values
    1000
    First level of paid or Prime subscription.
    2000
    Second level of paid subscription.
    3000
    Third level of paid subscription.
  - event.resub.is_primeBooleanNullable
    Whether or not this subscription is a Prime subscription.
  - event.resub.is_giftBoolean
    Whether or not the resub was a result of a gift.
  - event.resub.gifter_is_anonymousBooleanNullable
    Whether or not the gift was anonymous.
  - event.resub.gifter_user_idStringNullable
    The user ID of the subscription gifter. Null if anonymous.
  - event.resub.gifter_user_nameStringNullable
    The user name of the subscription gifter. Null if anonymous.
  - event.resub.gifter_user_loginStringNullable
    The user login of the subscription gifter. Null if anonymous.
- event.sub_giftObjectNullable
  Information about the gift sub event. Null if notice_type is not sub_gift.
  Hide child attributesShow child attributes
  - event.sub_gift.duration_monthsInteger
    The number of months the subscription is for.
  - event.sub_gift.cumulative_totalIntegerNullable
    The amount of gifts the gifter has given in this channel. Null if anonymous.
  - event.sub_gift.recipient_user_idString
    The user ID of the subscription gift recipient.
  - event.sub_gift.recipient_user_nameString
    The user name of the subscription gift recipient.
  - event.sub_gift.recipient_user_loginString
    The user login of the subscription gift recipient.
  - event.sub_gift.sub_tierString
    The type of subscription plan being used.
    Possible values
    1000
    First level of paid or Prime subscription.
    2000
    Second level of paid subscription.
    3000
    Third level of paid subscription.
  - event.sub_gift.community_gift_idStringNullable
    The ID of the associated community gift. Null if not associated with a community gift.
- event.community_sub_giftObjectNullable
  Information about the community gift sub event. Null if notice_type is not community_sub_gift.
  Hide child attributesShow child attributes
  - event.community_sub_gift.idString
    The ID of the associated community gift.
  - event.community_sub_gift.totalInteger
    Number of subscriptions being gifted.
  - event.community_sub_gift.sub_tierString
    The type of subscription plan being used.
    Possible values
    1000
    First level of paid or Prime subscription.
    2000
    Second level of paid subscription.
    3000
    Third level of paid subscription.
  - event.community_sub_gift.cumulative_totalIntegerNullable
    The amount of gifts the gifter has given in this channel. Null if anonymous.
- event.gift_paid_upgradeObjectNullable
  Information about the community gift paid upgrade event. Null if notice_type is not gift_paid_upgrade.
  Hide child attributesShow child attributes
  - event.gift_paid_upgrade.gifter_is_anonymousBoolean
    Whether the gift was given anonymously.
  - event.gift_paid_upgrade.gifter_user_idStringNullable
    The user ID of the user who gifted the subscription. Null if anonymous.
  - event.gift_paid_upgrade.gifter_user_nameStringNullable
    The user name of the user who gifted the subscription. Null if anonymous.
- event.prime_paid_upgradeObjectNullable
  Information about the Prime gift paid upgrade event. Null if notice_type is not prime_paid_upgrade
  Hide child attributesShow child attributes
  - event.prime_paid_upgrade.sub_tierString
    The type of subscription plan being used.
    Possible values
    1000
    First level of paid or Prime subscription.
    2000
    Second level of paid subscription.
    3000
    Third level of paid subscription.
- event.pay_it_forwardObjectNullable
  Information about the pay it forward event. Null if notice_type is not pay_it_forward
  Hide child attributesShow child attributes
  - event.pay_it_forward.gifter_is_anonymousBoolean
    Whether the gift was given anonymously.
  - event.pay_it_forward.gifter_user_idStringNullable
    The user ID of the user who gifted the subscription. Null if anonymous.
  - event.pay_it_forward.gifter_user_nameStringNullable
    The user name of the user who gifted the subscription. Null if anonymous.
  - event.pay_it_forward.gifter_user_loginStringNullable
    The user login of the user who gifted the subscription. Null if anonymous.
- event.raidObjectNullable
  Information about the raid event. Null if notice_type is not raid
  Hide child attributesShow child attributes
  - event.raid.user_idString
    The user ID of the broadcaster raiding this channel.
  - event.raid.user_nameString
    The user name of the broadcaster raiding this channel.
  - event.raid.user_loginString
    The login name of the broadcaster raiding this channel.
  - event.raid.viewer_countInteger
    The number of viewers raiding this channel from the broadcaster's channel.
  - event.raid.profile_image_urlString
    Profile image URL of the broadcaster raiding this channel.
- event.unraidObjectNullable
  Returns an empty payload if notice_type is unraid, otherwise returns null.
- event.announcementObjectNullable
  Information about the announcement event. Null if notice_type is not announcement
  Hide child attributesShow child attributes
  - event.announcement.colorString
    Color of the announcement.
- event.bits_badge_tierObjectNullable
  Information about the Bits badge tier event. Null if notice_type is not bits_badge_tier
  Hide child attributesShow child attributes
  - event.bits_badge_tier.tierInteger
    The tier of the Bits badge the user just earned. For example, 100, 1000, or 10000.
- event.charity_donationObjectNullable
  Information about the announcement event. Null if notice_type is not charity_donation
  Hide child attributesShow child attributes
  - event.charity_donation.charity_nameString
    Name of the charity.
  - event.charity_donation.amountObject
    An object that contains the amount of money that the user paid.
    Hide child attributesShow child attributes
    event.charity_donation.amount.valueInteger
    The monetary amount. The amount is specified in the currency's minor unit. For example, the minor units for USD is cents, so if the amount is $5.50 USD, value is set to 550.
    event.charity_donation.amount.decimal_placeInteger
    The number of decimal places used by the currency. For example, USD uses two decimal places.
    event.charity_donation.amount.currencyString
    The ISO-4217 three-letter currency code that identifies the type of currency in value.
- event.watch_streakObjectNullable
  Information about the Watch Streak event. Null if notice_type is not watch_streak.
  Hide child attributesShow child attributes
  - event.watch_streak.streak_countInteger
    The number of consecutive broadcasts for which the user has been watching.
  - event.watch_streak.channel_points_awardedInteger
    The number of channel points awarded for the Watch Streak milestone.
- event.modiversaryObjectNullable
  Information about the modiversary event. Null if notice_type is not modiversary.
  Hide child attributesShow child attributes
  - event.modiversary.monthsInteger
    The number of months the user has been a moderator in this channel.
- event.gifted_drops_summaryObjectNullable
  Information about the gifted Drops summary event. Null if notice_type is not gifted_drops_summary
  Hide child attributesShow child attributes
  - event.gifted_drops_summary.recipient_countInteger
    The number of users who received a gifted Drop.
- event.source_broadcaster_user_idStringNullable
  The broadcaster user ID of the channel the message was sent from. Is null when the message notification happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_broadcaster_user_nameStringNullable
  The user name of the broadcaster of the channel the message was sent from. Is null when the message notification happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_broadcaster_user_loginStringNullable
  The login of the broadcaster of the channel the message was sent from. Is null when the message notification happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_message_idStringNullable
  The UUID that identifies the source message from the channel the message was sent from. Is null when the message happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
- event.source_badgesObject[]Nullable
  The list of chat badges for the chatter in the channel the message was sent from. Is null when the message happens in the same channel as the broadcaster. Is not null when in a shared chat session, and the action happens in the channel of a participant other than the broadcaster.
  Hide child attributesShow child attributes
  - event.source_badges.set_idString
    The ID that identifies this set of chat badges. For example, Bits or Subscriber.
  - event.source_badges.idString
    The ID that identifies this version of the badge. The ID can be any value. For example, for Bits, the ID is the Bits tier level, but for World of Warcraft, it could be Alliance or Horde.
  - event.source_badges.infoString
    Contains metadata related to the chat badges in the badges tag. Currently, this tag contains metadata only for subscriber badges, to indicate the number of months the user has been a subscriber.
- event.is_source_onlyBooleanNullable
  Whether the notification is only sent to the source channel. Is null if the notification is not in a shared chat session.
- event.shared_chat_subObjectNullable
  Information about the shared_chat_sub event. Is null if notice_type is not shared_chat_sub. This field has the same information as the sub field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_resubObjectNullable
  Information about the shared_chat_resub event. Is null if notice_type is not shared_chat_resub. This field has the same information as the resub field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_sub_giftObjectNullable
  Information about the shared_chat_sub_gift event. Is null if notice_type is not shared_chat_sub_gift. This field has the same information as the chat_sub_gift field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_community_sub_giftObjectNullable
  Information about the shared_chat_community_sub_gift event. Is null if notice_type is not shared_chat_community_sub_gift. This field has the same information as the community_sub_gift field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_gift_paid_upgradeObjectNullable
  Information about the shared_chat_gift_paid_upgrade event. Is null if notice_type is not shared_chat_gift_paid_upgrade. This field has the same information as the gift_paid_upgrade field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_prime_paid_upgradeObjectNullable
  Information about the shared_chat_chat_prime_paid_upgrade event. Is null if notice_type is not shared_chat_prime_paid_upgrade. This field has the same information as the prime_paid_upgrade field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_pay_it_forwardObjectNullable
  Information about the shared_chat_pay_it_forward event. Is null if notice_type is not shared_chat_pay_it_forward. This field has the same information as the pay_it_forward field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_raidObjectNullable
  Information about the shared_chat_raid event. Is null if notice_type is not shared_chat_raid. This field has the same information as the raid field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_announcementObjectNullable
  Information about the shared_chat_announcement event. Is null if notice_type is not shared_chat_announcement. This field has the same information as the announcement field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_modiversaryObjectNullable
  Information about the shared_chat_modiversary event. Is null if notice_type is not shared_chat_modiversary. This field has the same information as the modiversary field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.
- event.shared_chat_gifted_drops_summaryObjectNullable
  Information about the shared_chat_gifted_drops_summary event. Is null if notice_type is not shared_chat_gifted_drops_summary. This field has the same information as the gifted_drops_summary field but for a notice that happened for a channel in a shared chat session other than the broadcaster in the subscription condition.

Subscription Request Body Example

{
  "type": "channel.chat.notification",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641",
    "user_id": "2914196"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat.notification",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641",
    "user_id": "2914196"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat.notification",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641",
    "user_id": "2914196"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
  "subscription": {
    "id": "dc1a3cfc-a930-4972-bf9e-0ffc4e7a8996",
    "status": "enabled",
    "type": "channel.chat.notification",
    "version": "1",
    "condition": {
      "broadcaster_user_id": "1971641",
      "user_id": "2914196"
    },
    "transport": {
      "method": "websocket",
      "session_id": "AgoQOtgGkFvXRlSkij343CndhIGY2VsbC1h"
    },
    "created_at": "2023-10-06T18:04:38.807682738Z",
    "cost": 0
  },
  "event": {
    "broadcaster_user_id": "1971641",
    "broadcaster_user_login": "streamer",
    "broadcaster_user_name": "streamer",
    "chatter_user_id": "49912639",
    "chatter_user_login": "viewer23",
    "chatter_user_name": "viewer23",
    "chatter_is_anonymous": false,
    "color": "",
    "badges": [],
    "system_message": "viewer23 subscribed at Tier 1. They've subscribed for 10 months!",
    "message_id": "d62235c8-47ff-a4f4--84e8-5a29a65a9c03",
    "message": {
      "text": "",
      "fragments": []
    },
    "notice_type": "resub",
    "sub": null,
    "resub": {
      "cumulative_months": 10,
      "duration_months": 0,
      "streak_months": null,
      "sub_plan": "1000",
      "is_gift": false,
      "gifter_is_anonymous": null,
      "gifter_user_id": null,
      "gifter_user_name": null,
      "gifter_user_login": null
    },
    "sub_gift": null,
    "community_sub_gift": null,
    "gift_paid_upgrade": null,
    "prime_paid_upgrade": null,
    "pay_it_forward": null,
    "raid": null,
    "unraid": null,
    "announcement": null,
    "bits_badge_tier": null,
    "charity_donation": null,
    "watch_streak": null,
    "modiversary": null,
    "shared_chat_sub": null,
    "shared_chat_resub": null,
    "shared_chat_sub_gift": null,
    "shared_chat_community_sub_gift": null,
    "shared_chat_gift_paid_upgrade": null,
    "shared_chat_prime_paid_upgrade": null,
    "shared_chat_pay_it_forward": null,
    "shared_chat_raid": null,
    "shared_chat_announcement": null,
    "shared_chat_modiversary": null,
    "source_broadcaster_user_id": null,
    "source_broadcaster_user_login": null,
    "source_broadcaster_user_name": null,
    "source_message_id": null,
    "source_badges": null,
    "is_source_only": null
  }
}

Channel Chat User Message Hold

The channel.chat.user_message_hold subscription type notifies a user if their message is caught by AutoMod.

Subscription

Type: channel.chat.user_message_hold
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat.user_message_hold.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  User ID of the channel to receive chat message events for.
- condition.user_idStringRequired
  The user ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    User ID of the channel to receive chat message events for.
  - subscription.condition.user_idString
    The user ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The ID of the broadcaster specified in the request.
- event.broadcaster_user_loginString
  The login of the broadcaster specified in the request.
- event.broadcaster_user_nameString
  The user name of the broadcaster specified in the request.
- event.user_idString
  The User ID of the message sender.
- event.user_loginString
  The message sender's login.
- event.user_nameString
  The message sender's display name.
- event.message_idString
  The ID of the message that was flagged by automod.
- event.messageObject
  The body of the message.
  Hide child attributesShow child attributes
  - event.message.textString
    The contents of the message caught by automod.
  - event.message.fragmentsObject[]
    Ordered list of chat message fragments.
    Hide child attributesShow child attributes
    event.message.fragments.typeString
    The type of message fragment.
    Possible values
    text
    cheermote
    emote
    mention
    gif
    event.message.fragments.textString
    Message text in a fragment.
    event.message.fragments.emoteObjectNullable
    Metadata pertaining to the emote.
    Hide child attributesShow child attributes
    event.message.fragments.emote.idString
    An ID that uniquely identifies this emote.
    event.message.fragments.emote.emote_set_idString
    An ID that identifies the emote set that the emote belongs to.
    event.message.fragments.cheermoteObjectNullable
    Metadata pertaining to the cheermote.
    Hide child attributesShow child attributes
    event.message.fragments.cheermote.prefixString
    The name portion of the Cheermote string that you use in chat to cheer Bits, converted to lowercase. The full Cheermote string is the concatenation of {prefix} + {number of Bits}.
    
    For example, if the prefix is "cheer" and you want to cheer 100 Bits, the full Cheermote string is cheer100. When the Cheermote string is entered in chat, Twitch converts it to the image associated with the Bits tier that was cheered.
    event.message.fragments.cheermote.bitsInteger
    The amount of Bits cheered.
    event.message.fragments.cheermote.tierInteger
    The tier level of the cheermote.

Subscription Request Body Example

{
  "type": "channel.chat.user_message_hold",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat.user_message_hold",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat.user_message_hold",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
  "subscription": {
    "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
    "type": "channel.chat.user_message_hold",
    "version": "1",
    "status": "enabled",
    "cost": 0,
    "condition": {
      "broadcaster_user_id": "1337",
      "user_id": "9001"
    },
    "transport": {
      "method": "webhook",
      "callback": "https://example.com/webhooks/callback"
    },
    "created_at": "2023-04-11T10:11:12.123Z"
  },
  "event": {
    "broadcaster_user_id": "123",
    "broadcaster_user_login": "bob",
    "broadcaster_user_name": "Bob",
    "user_id": "456",
    "user_login": "tom",
    "user_name": "Tommy",
    "message_id": "789",
    "message": {
      "text": "hey world",
      "fragments": [
        {
          "type": "emote",
          "text": "hey world",
          "cheermote": null,
          "emote": {
            "id": "foo",
            "emote_set_id": "7"
          }
        },
        {
          "type": "cheermote",
          "text": "bye world",
          "cheermote": {
            "prefix": "prefix",
            "bits": 100,
            "tier": 1
          },
          "emote": null
        },
        {
          "type": "text",
          "text": "surprise",
          "cheermote": null,
          "emote": null
        }
      ]
    }
  }
}

Channel Chat User Message Update

The channel.chat.user_message_update subscription type notifies a user if their message's AutoMod status is updated.

Subscription

Type: channel.chat.user_message_update
Version: 1

Authorization

Requires one of the following:

A user access token that includes the user:read:chat scope.
An app access token.The application, through prior authorization, must have been granted:
- The user:read:chat, user:bot scopes for the user represented by the user_id event condition.

Subscription Request Body

typeStringRequired
The subscription type name: channel.chat.user_message_update.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  User ID of the channel to receive chat message events for.
- condition.user_idStringRequired
  The user ID to read chat as.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    User ID of the channel to receive chat message events for.
  - subscription.condition.user_idString
    The user ID to read chat as.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.broadcaster_user_idString
  The ID of the broadcaster specified in the request.
- event.broadcaster_user_loginString
  The login of the broadcaster specified in the request.
- event.broadcaster_user_nameString
  The user name of the broadcaster specified in the request.
- event.user_idString
  The User ID of the message sender.
- event.user_loginString
  The message sender's login.
- event.user_nameString
  The message sender's user name.
- event.statusString
  The message's status.
  Possible values
  - approved
  - denied
  - invalid
- event.message_idString
  The ID of the message that was flagged by automod.
- event.messageObject
  The body of the message.
  Hide child attributesShow child attributes
  - event.message.textString
    The contents of the message caught by automod.
  - event.message.fragmentsObject[]
    Ordered list of chat message fragments.
    Hide child attributesShow child attributes
    event.message.fragments.typeString
    The type of message fragment.
    Possible values
    text
    cheermote
    emote
    mention
    gif
    event.message.fragments.textString
    Message text in a fragment.
    event.message.fragments.emoteObjectNullable
    Metadata pertaining to the emote.
    Hide child attributesShow child attributes
    event.message.fragments.emote.idString
    An ID that uniquely identifies this emote.
    event.message.fragments.emote.emote_set_idString
    An ID that identifies the emote set that the emote belongs to.
    event.message.fragments.cheermoteObjectNullable
    Metadata pertaining to the cheermote.
    Hide child attributesShow child attributes
    event.message.fragments.cheermote.prefixString
    The name portion of the Cheermote string that you use in chat to cheer Bits, converted to lowercase. The full Cheermote string is the concatenation of {prefix} + {number of Bits}.
    
    For example, if the prefix is "cheer" and you want to cheer 100 Bits, the full Cheermote string is cheer100. When the Cheermote string is entered in chat, Twitch converts it to the image associated with the Bits tier that was cheered.
    event.message.fragments.cheermote.bitsInteger
    The amount of Bits cheered.
    event.message.fragments.cheermote.tierInteger
    The tier level of the cheermote.

Subscription Request Body Example

{
  "type": "channel.chat.user_message_update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.chat.user_message_update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.chat.user_message_update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1337",
    "user_id": "9001"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
    "subscription": {
        "id": "f1c2a387-161a-49f9-a165-0f21d7a4e1c4",
        "type": "channel.chat.user_message_update",
        "version": "1",
        "status": "enabled",
        "cost": 0,
        "condition": {
            "broadcaster_user_id": "1337",
            "user_id": "9001"
        },
         "transport": {
            "method": "webhook",
            "callback": "https://example.com/webhooks/callback"
        },
        "created_at": "2023-04-11T10:11:12.123Z"
    },
    "event": {
   "broadcaster_user_id": "123",
   "broadcaster_user_login": "bob",
   "broadcaster_user_name": "Bob",
   "user_id": "456",
   "user_login": "tom",
   "user_name": "Tommy",
   "status": "approved",
   "message_id": "789",
   "message": {
     "text": "hey world",
     "fragments": [
       {
         "type": "emote",
         "text": "hey world",
         "cheermote": null,
         "emote": {
             "id": "foo",
             "emote_set_id": "7"
         }
       },
       {
         "type": "cheermote",
         "text": "bye world",
         "cheermote": {
             "prefix": "prefix",
             "bits": 100,
             "tier": 1
         },
         "emote": null
       },
       {
         "type": "text",
         "text": "surprise",
         "cheermote": null,
         "emote": null
       }
     ]
   }
 }
}

Channel Shared Chat Session Begin

The channel.shared_chat.begin subscription type sends a notification when a channel becomes active in an active shared chat session.

Subscription

Type: channel.shared_chat.begin
Version: 1

Authorization

No authorization required.

Subscription Request Body

typeStringRequired
The subscription type name: channel.shared_chat.begin.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  The User ID of the channel to receive shared chat session begin events for.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    The User ID of the channel to receive shared chat session begin events for.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.session_idString
  The unique identifier for the shared chat session.
- event.broadcaster_user_idString
  The User ID of the channel in the subscription condition which is now active in the shared chat session.
- event.broadcaster_user_nameString
  The display name of the channel in the subscription condition which is now active in the shared chat session.
- event.broadcaster_user_loginString
  The user login of the channel in the subscription condition which is now active in the shared chat session.
- event.host_broadcaster_user_idString
  The User ID of the host channel.
- event.host_broadcaster_user_nameString
  The display name of the host channel.
- event.host_broadcaster_user_loginString
  The user login of the host channel.
- event.participantsObject[]
  The list of participants in the session.
  Hide child attributesShow child attributes
  - event.participants.broadcaster_user_idString
    The User ID of the participant channel.
  - event.participants.broadcaster_user_nameString
    The display name of the participant channel.
  - event.participants.broadcaster_user_loginString
    The user login of the participant channel.

Subscription Request Body Example

{
  "type": "channel.shared_chat.begin",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.shared_chat.begin",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.shared_chat.begin",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
  "subscription": {
    "id": "bf0602d2-5b39-4ece-b1a4-44191d52df6b",
    "status": "enabled",
    "type": "channel.shared_chat.begin",
    "version": "1",
    "condition": {
      "broadcaster_user_id": "1971641"
    },
    "transport": {
      "method": "websocket",
      "session_id": "AgoQOtgGkFvXRlSkij343CndhIGY2VsbC1h"
    },
    "created_at": "2023-10-06T18:04:38.807682738Z",
    "cost": 0
  },
  "event": {
    "session_id": "2b64a92a-dbb8-424e-b1c3-304423ba1b6f",
    "broadcaster_user_id": "1971641",
    "broadcaster_user_login": "streamer",
    "broadcaster_user_name": "streamer",
    "host_broadcaster_user_id": "1971641",
    "host_broadcaster_user_login": "streamer",
    "host_broadcaster_user_name": "streamer",
    "participants": [
      {
        "broadcaster_user_id": "1971641",
        "broadcaster_user_name": "streamer",
        "broadcaster_user_login": "streamer"
      },
      {
        "broadcaster_user_id": "112233",
        "broadcaster_user_name": "streamer33",
        "broadcaster_user_login": "streamer33"
      }
    ]
  }
}

Channel Shared Chat Session End

The channel.shared_chat.end subscription type sends a notification when a channel leaves a shared chat session or the session ends.

Subscription

Type: channel.shared_chat.end
Version: 1

Authorization

No authorization required.

Subscription Request Body

typeStringRequired
The subscription type name: channel.shared_chat.end.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  The User ID of the channel to receive shared chat session end events for.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    The User ID of the channel to receive shared chat session end events for.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.session_idString
  The unique identifier for the shared chat session.
- event.broadcaster_user_idString
  The User ID of the channel in the subscription condition which is no longer active in the shared chat session.
- event.broadcaster_user_nameString
  The display name of the channel in the subscription condition which is no longer active in the shared chat session.
- event.broadcaster_user_loginString
  The user login of the channel in the subscription condition which is no longer active in the shared chat session.
- event.host_broadcaster_user_idString
  The User ID of the host channel.
- event.host_broadcaster_user_nameString
  The display name of the host channel.
- event.host_broadcaster_user_loginString
  The user login of the host channel.

Subscription Request Body Example

{
  "type": "channel.shared_chat.end",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.shared_chat.end",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.shared_chat.end",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
  "subscription": {
    "id": "84a875f1-1dc0-43b2-8ed3-d7db4d650c37",
    "status": "enabled",
    "type": "channel.shared_chat.end",
    "version": "1",
    "condition": {
      "broadcaster_user_id": "112233"
    },
    "transport": {
      "method": "websocket",
      "session_id": "AgoQOtgGkFvXRlSkij343CndhIGY2VsbC1h"
    },
    "created_at": "2023-10-06T18:04:38.807682738Z",
    "cost": 0
  },
  "event": {
    "session_id": "2b64a92a-dbb8-424e-b1c3-304423ba1b6f",
    "broadcaster_user_id": "1971641",
    "broadcaster_user_login": "streamer",
    "broadcaster_user_name": "streamer",
    "host_broadcaster_user_id": "1971641",
    "host_broadcaster_user_login": "streamer",
    "host_broadcaster_user_name": "streamer"
  }
}

Channel Shared Chat Session Update

The channel.shared_chat.update subscription type sends a notification when the active shared chat session the channel is in changes.

Subscription

Type: channel.shared_chat.update
Version: 1

Authorization

No authorization required.

Subscription Request Body

typeStringRequired
The subscription type name: channel.shared_chat.update.
versionStringRequired
The subscription type version: 1.
conditionObjectRequired
Subscription-specific parameters.
Hide child attributesShow child attributes
- condition.broadcaster_user_idStringRequired
  The User ID of the channel to receive shared chat session update events for.
transportObjectRequired
Transport-specific parameters.
Hide child attributesShow child attributes
- transport.methodStringRequired
  The transport method for EventSub.
  Possible values
  - webhook
  - websocket
  - conduit
- transport.callbackString
  The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
  
  Specify this field only if method is set to webhook.
  
  NOTE: Redirects are not followed.
- transport.secretString
  The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
  
  Specify this field only if the method is set to webhook.
- transport.session_idString
  An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
  
  Specify this field only if the method is set to websocket.
- transport.conduit_idString
  An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
  
  Specify this field only if the method is set to conduit.

Event Payload

subscriptionObject
Metadata about the subscription.
Hide child attributesShow child attributes
- subscription.idString
  The Subscription ID of the subscription.
- subscription.typeString
  The notification's subscription type.
- subscription.versionString
  The version of the subscription.
- subscription.statusString
  The status of the subscription.
- subscription.costInteger
  How much the subscription counts against your limit. See Subscription Limits for more information.
- subscription.conditionObject
  Subscription-specific parameters.
  Hide child attributesShow child attributes
  - subscription.condition.broadcaster_user_idString
    The User ID of the channel to receive shared chat session update events for.
- subscription.created_atString
  The time the notification was created.
- subscription.transportObject
  Transport-specific parameters.
  Hide child attributesShow child attributes
  - subscription.transport.methodString
    The transport method for EventSub.
    Possible values
    webhook
    websocket
    conduit
  - subscription.transport.callbackString
    The callback URL where notifications are sent. The URL must use the HTTPS protocol and port 443. See Processing an Event.
    
    Specify this field only if method is set to webhook.
    
    NOTE: Redirects are not followed.
  - subscription.transport.secretString
    The secret used to verify the signature. The secret must be an ASCII string that's a minimum of 10 characters long and a maximum of 100 characters long. For information about how the secret is used, see Verifying the event message.
    
    Specify this field only if the method is set to webhook.
  - subscription.transport.session_idString
    An ID that identifies the WebSocket to send notifications to. When you connect to EventSub using WebSockets, the server returns the ID in the Welcome message.
    
    Specify this field only if the method is set to websocket.
  - subscription.transport.conduit_idString
    An ID that identifies the conduit to send this notification to. When you create a conduit, the server returns the ID in the API response.
    
    Specify this field only if the method is set to conduit.
eventObject
The event information.
Hide child attributesShow child attributes
- event.session_idString
  The unique identifier for the shared chat session.
- event.broadcaster_user_idString
  The User ID of the channel in the subscription condition.
- event.broadcaster_user_nameString
  The display name of the channel in the subscription condition.
- event.broadcaster_user_loginString
  The user login of the channel in the subscription condition.
- event.host_broadcaster_user_idString
  The User ID of the host channel.
- event.host_broadcaster_user_nameString
  The display name of the host channel.
- event.host_broadcaster_user_loginString
  The user login of the host channel.
- event.participantsObject[]
  The list of participants in the session.
  Hide child attributesShow child attributes
  - event.participants.broadcaster_user_idString
    The User ID of the participant channel.
  - event.participants.broadcaster_user_nameString
    The display name of the participant channel.
  - event.participants.broadcaster_user_loginString
    The user login of the participant channel.

Subscription Request Body Example

{
  "type": "channel.shared_chat.update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "webhook",
    "callback": "https://example.com/webhooks/callback",
    "secret": "s3cRe7"
  }
}

{
  "type": "channel.shared_chat.update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "websocket",
    "session_id": "AQoQexAWVYKSTIu4ec_2VAxyuhAB"
  }
}

{
  "type": "channel.shared_chat.update",
  "version": "1",
  "condition": {
    "broadcaster_user_id": "1971641"
  },
  "transport": {
    "method": "conduit",
    "conduit_id": "bfcfc993-26b1-b876-44d9-afe75a379dac"
  }
}

Event Payload Example

{
  "subscription": {
    "id": "5f65d0a7-0069-4f2b-944b-bc81b160ae49",
    "status": "enabled",
    "type": "channel.shared_chat.update",
    "version": "1",
    "condition": {
      "broadcaster_user_id": "1971641"
    },
    "transport": {
      "method": "websocket",
      "session_id": "AgoQOtgGkFvXRlSkij343CndhIGY2VsbC1h"
    },
    "created_at": "2023-10-06T18:04:38.807682738Z",
    "cost": 0
  },
  "event": {
    "session_id": "2b64a92a-dbb8-424e-b1c3-304423ba1b6f",
    "broadcaster_user_id": "1971641",
    "broadcaster_user_login": "streamer",
    "broadcaster_user_name": "streamer",
    "host_broadcaster_user_id": "1971641",
    "host_broadcaster_user_login": "streamer",
    "host_broadcaster_user_name": "streamer",
    "participants": [
      {
        "broadcaster_user_id": "1971641",
        "broadcaster_user_name": "streamer",
        "broadcaster_user_login": "streamer"
      },
      {
        "broadcaster_user_id": "112233",
        "broadcaster_user_name": "streamer33",
        "broadcaster_user_login": "streamer33"
      },
      {
        "broadcaster_user_id": "332211",
        "broadcaster_user_name": "streamer11",
        "broadcaster_user_login": "streamer11"
      }
    ]
  }
}