Blocking Users

Learn to block and unblock users on Twitch.

We'll cover the following

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.

Request parameters

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 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
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/users/blocks");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Providing the ID of the user we want to block
const queryParameters = new URLSearchParams({
  target_user_id: "12826",    // Official Twitch account
});
const options = {
  method: "PUT",
  headers: headerParameters,
};
async function blockUser() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
blockUser();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the call using the target_user_id parameter.

  • Lines 15–18: We set the options for the API call, specifying the HTTP request type as PUT and providing the request headers.

  • Lines 20–28: We define a function called blockUser to make a call to the blocks endpoint.

    • Lines 21–25: Within a try block, we provide the query parameters, make a call to the endpoint, and print the response from the API.

    • Lines 25–27: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the blockUser function.

Response fields

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 the 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.

Request parameters

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
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/users/blocks");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Providing our ID as the broadcaster_id to fetch our block list
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
});
const options = {
  method: "GET",
  headers: headerParameters,
};
async function getBlockList() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
getBlockList();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the call using the broadcaster_id parameter.

  • Lines 15–18: We set the options for the API call, specifying the HTTP request type as GET and providing the request headers.

  • Lines 20–28: We define a function called getBlockList to make a call to the blocks endpoint.

    • Lines 21–25: Within a try block, we provide the query parameters, make a call to the endpoint, and print the response from the API.

    • Lines 25–27: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the getBlockList function.

Response fields

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 which 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.

Request parameters

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
import fetch from "node-fetch";
const endpointUrl = new URL("https://api.twitch.tv/helix/users/blocks");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Providing the ID of the user we want to unblock
const queryParameters = new URLSearchParams({
  target_user_id: "12826",   // Official Twitch account
});
const options = {
  method: "DELETE",
  headers: headerParameters,
};
async function unblockUser() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
unblockUser();

In the code above, we perform the following:

  • Lines 11–13: We define the query parameters for the call using the target_user_id parameter.

  • Lines 15–18: We set the options for the API call, specifying the HTTP request type as DELETE and providing the request headers.

  • Lines 20–28: We define a function called unblockUser to make a call to the blocks endpoint.

    • Lines 21–25: Within a try block, we provide the query parameters, make a call to the endpoint, and print the response from the API.

    • Lines 25–27: We catch any errors or exceptions within a catch block and print them to the console.

  • Line 30: We invoke the unblockUser function.

The response from this request only contains an HTTP status code, 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.