Blocking Users

Learn to block and unblock users on Twitch.

Sometimes on social media platforms, we may find ourselves in situations where we’re forced to block another user.

Twitch allows us to block users from both the console and the API. The API also gives us the capability to unblock users, as well as to view the list of blocked users.

The API provides a blocks endpoint for these purposes. The URL for this endpoint is as follows:

https://api.twitch.tv/helix/users/blocks

Block a user

To block a user through the blocks endpoint, we need to send a PUT request authorized with a user access token that has the user:manage:blocked_users scope.

To make a successful request, we need to provide the ID of a user to be blocked as a required query parameter. If we want, we can also use a few optional query parameters. The table below gives an overview of these parameters:

Parameter

Type

Category

Description

target_user_id

String

Required

This is the ID of the user we want to block.

source_context

String

Optional

This is the source from where the user is being blocked from on the Twitch console. Its accepted values are "chat" and "whisper".

reason

String

Optional

This represents the reason for blocking the user. Its accepted values are "spam", "harassment", and "other".

Let's make a sample request to block the official Twitch account.

Note: If your token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
headers = {
'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
'Client-Id' : '{{CLIENT_ID}}'
}
parameters = {
'target_user_id' : '12826' # Official Twitch account
}
response = requests.put('https://api.twitch.tv/helix/users/blocks',
headers=headers, params=parameters)
print(response.status_code)

The response from this request contains only an HTTP status code. If the API responds with 204, the request is successful. If the request fails, it returns an error code instead. The table below gives a summary of these status codes:

Status Code

Description

204

This is a success code that indicates that the user was blocked successfully.

400

This error code indicates that the request was invalid due to incorrect or missing parameters.

401

This error code indicates that the API failed to authorize the request due to a missing bearer token or scopes.

Fetch the list of blocked users

Next, let's learn to fetch our list of blocked users from the API. We can do so by sending a GET request to the blocks endpoint. This call needs to be authorized with a user access token that has the user:read:blocked_users scope.

To make a successful request, we need to provide the ID of the user we want to retrieve the list for as a required query parameter. There are also a couple of optional parameters we can use. The table below gives an overview of all these parameters:

Parameter

Type

Category

Description

broadcaster_id

String

Required

This is the ID of the user for which we want to retrieve the list of blocked users. It must be the same as that of the user authenticated with the access token.

after

String

Optional

This is a cursor value for forward pagination. Each response from this endpoint that has multiple pages returns a cursor value. We can provide this value in the after parameter to return the page of results after the page specified by the cursor.

first

Integer

Optional

This is the number of results to be returned per page, with a maximum of 100 results per page. Its default value is 20.

Let's make a GET request to the blocks endpoint now.

Note: If your token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
headers = {
'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
'Client-Id' : '{{CLIENT_ID}}'
}
parameters = {
'broadcaster_id' : '{{USER_ID}}'
}
response = requests.get('https://api.twitch.tv/helix/users/blocks',
headers=headers, params=parameters).json()
print(json.dumps(response, indent=4))

The JSON response from this request has two top-level properties—data and pagination. The results are stored in the data property in the form of an array of objects. Each of these objects represents a blocked user. The details of this object are discussed in the table below:

Property

Type

Description

user_id

String

This is the ID of the blocked user.

user_login

String

This is the login name of the blocked user.

display_name

String

This is the display name of the blocked user.

Unblock a user

We might also find ourselves wanting to unblock a user on Twitch. We can send a DELETE request to the blocks endpoint to unblock a user we had previously blocked. This request must be authenticated with a user access token that has the user:manage:blocked_users scope.

We must provide a single required query parameter with this request to succeed. The table below gives an overview of this parameter:

Parameter

Type

Category

Description

target_user_id

String

Required

This is the ID of the user we want to unblock.

Let's make a DELETE request to this endpoint, unblocking the Twitch account we blocked earlier.

Note: If your token has expired, return to this lesson and follow the steps to generate a new one.

Press + to interact
headers = {
'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
'Client-Id' : '{{CLIENT_ID}}'
}
parameters = {
'target_user_id' : '12826'
}
response = requests.delete('https://api.twitch.tv/helix/users/blocks',
headers=headers, params=parameters)
print(response.status_code)

The response from this request only contains an HTTP status code, which is identical to the status codes received when blocking users.

Now that we've unblocked the official Twitch account, let’s fetch the blocked list once again. If all goes smoothly, the official Twitch account will no longer be on the list.