New Shoutouts API and EventSub subscription types are now in open beta

Last year, Twitch launched shoutouts, a new feature for streamers and their moderators to support other streamers by sharing their follow button in chat with the /shoutout command. Streamers who receive shoutouts see a notification their activity feed with the number of viewers they were shouted out to. We immediately received UserVoice suggestions for both an API endpoint to create shoutouts and EventSub subscription types to track when shoutouts happen.

Today we’re excited to launch the open beta Twitch API endpoints and EventSub subscription types for this new feature!

New Twitch API Endpoint

New EventSub Subscription Types

New Scopes

  • moderator:read:shoutouts - Read a broadcaster’s shoutouts.
  • moderator:manage:shoutouts - Manage a broadcaster’s shoutouts.

How do I get started?

The new endpoints and subscriptions types are publicly available in an open beta. Visit the documentation links above to start implementing shoutout functionality today. Once all UserVoice feedback is considered during the open beta, this functionality will become “generally available,” meaning no further updates or changes can be expected unless formally announced here on the forums.

If you have any questions or want to share how you’ll use these endpoints, please feel free to comment below.


Appreciate the moderator scopes on this :+1:

Edit: .receive is correctly moderator scoped, but .create should not be. Example use case is: third-party chat applications like chatterino/chatty that would like normal users to be able to see outbound shoutouts. Now uservoiced @ Shoutout Create EventSub Subscription should not require moderator auth – Twitch UserVoice


The docs for ‘channel.shoutout.create’ and ‘channel.shoutout.receive’ EventSub subscriptions note ‘broadcaster_user_id’ as optional and ‘moderator_user_id’ as required in the ‘condition’, yet not setting the ‘broadcaster_user_id’ when trying to subscribe throws a validation error:

data {
  error: 'Bad Request',
  status: 400,
  message: "unknown validation error: Key: 'SubscriptionCondition.broadcaster_user_id' Error:Field validation for 'broadcaster_user_id' failed on the 'required' tag"
config {
  transitional: {
    silentJSONParsing: true,
    forcedJSONParsing: true,
    clarifyTimeoutError: false
  adapter: [ 'xhr', 'http' ],
  transformRequest: [ [Function: transformRequest] ],
  transformResponse: [ [Function: transformResponse] ],
  timeout: 0,
  xsrfCookieName: 'XSRF-TOKEN',
  xsrfHeaderName: 'X-XSRF-TOKEN',
  maxContentLength: -1,
  maxBodyLength: -1,
  env: {
    FormData: [Function: FormData] {
      LINE_BREAK: '\r\n',
      DEFAULT_CONTENT_TYPE: 'application/octet-stream'
    Blob: null
  validateStatus: [Function: validateStatus],
  headers: AxiosHeaders {
    Accept: 'application/json, text/plain, */*',
    'Content-Type': 'application/json',
    Authorization: '<redacted>',
    'Client-Id': '<redacted>',
    'User-Agent': 'axios/1.2.2',
    'Content-Length': '175',
    'Accept-Encoding': 'gzip, compress, deflate, br'
  method: 'post',
  url: '',
  data: '{"type":"channel.shoutout.create","version":"beta","condition":{"moderator_user_id":"<redacted>"},"transport":{"method":"websocket","session_id":"<redacted>"}}'

The same happens if only providing the ‘broadcaster_user_id’.
It only works when providing both at the moment.

Filed on github: Shoutout Create/Recieve - broadcaster_user_id not actually optional? · Issue #710 · twitchdev/issues · GitHub

Edit: oh I suspect it’s a documentation bug but we’ll need the powers that be to intervene

1 Like

Documentation bug! Both fields are required

Thanks for the quick feedback on this! We have updated the documentation today to reflect that broadcaster_user_id is required.

Regarding the EventSub events, I find it strange that:

  • channel.shoutout.create has to_broadcaster_user_id but, unlike other from/to events, there is no from_broadcaster_user_id (instead it is just named broadcaster_user_id)

  • channel.shoutout.receive has from_broadcaster_user_id, but unlike other from/to events, there is no to_broadcaster_user_id (instead it is just named broadcaster_user_id)

Essentially, this naming seems inconsistent with other eventsub subscription types… does this distinction exist because the condition object only has broadcaster_user_id (without an explicit from/to prefix)?

Would it not be better to follow the example of where there is only one subscription type & you either specify from_broadcaster_user_id or to_broadcaster_user_id?

Edit: the activity feed mess may be related to this distinction but I don’t understand why you need to tie yourself to that system if you have all the .create events