Modify Stream Schedules

Learn to update your Twitch stream schedule.

We'll cover the following

Set vacation details

The Twitch API allows us to update the settings of stream schedules. We send a PATCH request to the schedule settings endpoint of the API and set vacation details for our channel. We can set vacation details to specify a vacation period where all scheduled streams will be automatically canceled.

The URL for this endpoint is as follows:

https://api.twitch.tv/helix/schedule/settings

All calls to this endpoint must be authenticated with a user access token that has the channel:manage:schedule scope.

Request parameters

This endpoint requires a single query parameter with a few other optional parameters. The table below gives an overview of these parameters:

Parameter

Type

Category

Description

broadcaster_id

String

Required

This is the ID of the user for whom we want to update the schedule settings. It must be of the same user who is authenticated with the access token.

is_vacation_enabled

Boolean

Optional

We set this to true if we're adding vacation details. We set it to false if we're removing already defined vacations.

vacation_start_time

String

Optional

This is an RFC3339 timestamp for the starting date of the vacation period. This parameter is required if is_vacation_enabled is set to true.

vacation_end_time

String

Optional

This is an RFC3339 timestamp for the ending date of the vacation period. This parameter is required if is_vacation_enabled is set to true.

timezone

String

Optional

This is the timezone in the IANA time zone database format. This parameter is required if is_vacation_enabled is set to true.

Let's make a sample call to this endpoint, setting a seven-day vacation period starting today. We can update the timezone parameter on line 16 to our timezone.

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/schedule/settings");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
// Defining the query parameters required to set vacation details
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
  is_vacation_enabled: true,
  vacation_start_time: new Date().toISOString(),
  vacation_end_time: new Date().addDays(7).toISOString(),
  timezone: "America/New_York",
});
const options = {
  method: "PATCH",
  headers: headerParameters,
};
async function setVacation() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
setVacation();

In the code above, we perform the following:

  • Lines 11–17: We define the query parameters for the request using the broadcaster_id, is_vacation_enabled, vacation_start_time, vacation_end_time, and timezone parameters.

  • Lines 19–22: We set the options for the API call, specifying the HTTP request type as PATCH and providing the request headers.

  • Lines 24–32: We define a function called setVacation to make a call to the schedule settings endpoint.

    • Lines 25–29: We make a call to the endpoint within a try block and print the response from the API.

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

  • Line 34: We invoke the setVacation 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 these status codes:

Status Code

Description

204

This is a success code indicating that the schedule settings were successfully updated.

400

This is an error code indicating that the request was invalid due to missing or invalid parameters.

401

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

Update scheduled streams

What if we've already scheduled a stream and now want to change some of its details, such as the game we're playing or the stream title? To do so, we can send a PATCH request to the schedule segments endpoint.

All PATCH requests to this endpoint must be authenticated with a user access token that has the channel:manage:schedule scope.

Request parameters

We must provide a couple of required query parameters and some optional body parameters to make a successful request. The table below discusses the details of these parameters:

Parameter

Parameter Type

Type

Category

Description

broadcaster_id

Query

String

Required

This is the ID of the user for whom we want to update the schedule settings. It must be of the same user who is authenticated with the access token.

id

Query

String

Required

This is the ID of the segment we want to update.

start_time

Body

String

Optional

This is an RFC3339 timestamp for the starting time of the stream.

timezone

Body

String

Optional

This is the timezone in the IANA time zone database format.

is_canceled

Body

Boolean

Optional

This determines whether the scheduled stream is canceled.

duration

Body

Integer

Optional

This is the duration of the stream in minutes.

category_id

Body

String

Optional

This is the ID of the game the streamer will play during the stream.

title

Body

String

Optional

This is the title of the stream. Its length cannot exceed 140 characters.

Let's make a request to this endpoint to update the segment we've previously defined. We can try changing the value of the title parameter on line 18 or add other parameters as per our liking.

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/schedule/segment");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
  "Content-Type": "application/json",
};
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
  id: "{{SEGMENT_ID}}",
});
// Updating the title of the schedule segment
const bodyParameters = JSON.stringify({
  title: "This title was updated through the Twitch API",
});
const options = {
  method: "PATCH",
  headers: headerParameters,
  body: bodyParameters,
};
async function updateScheduleSegment() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
updateScheduleSegment();

In the code above, we perform the following:

  • Lines 5–9: We define the headers for the request, specifying the content type as application/json.

  • Lines 11–14: We define the query parameters for the request using the broadcaster_id and id parameters.

  • Lines 17–19: We define the body parameters for the request using the title parameter.

  • Lines 21–25: We set the options for the API call, specifying the HTTP request type as PATCH and providing the request headers and body.

  • Lines 27–35: We define a function called updateScheduleSegment to make a call to the schedule segments endpoint.

    • Lines 28–32: We make a call to the endpoint within a try block and print the response from the API.

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

  • Line 37: We invoke the updateScheduleSegment function.

The response from this PATCH request is identical to the response we get when we send a POST request to the schedule segments endpoint.

Delete scheduled streams

Twitch also allows us to delete scheduled segments using the API. To do so, we can send a DELETE request to the schedule segments endpoint. The request must be authenticated with a user access token that has the channel:manage:broadcast scope.

Request parameters

This request requires only two query parameters that are discussed in the table below:

Parameter

Parameter Type

Type

Category

Description

broadcaster_id

Query

String

Required

This is the ID of the user for whom we want to update the schedule settings. It must be of the same user who is authenticated with the access token.

id

Query

String

Required

This is the ID of the segment we want to delete.

Let's make a sample request to delete the segment we defined 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/schedule/segment");
const headerParameters = {
  Authorization: "Bearer {{USER_ACCESS_TOKEN}}",
  "Client-Id": "{{CLIENT_ID}}",
};
const queryParameters = new URLSearchParams({
  broadcaster_id: "{{USER_ID}}",
  id: "{{SEGMENT_ID}}",
});
const options = {
  method: "DELETE",
  headers: headerParameters,
};
async function deleteScheduleSegment() {
  try {
    endpointUrl.search = queryParameters;
    const response = await fetch(endpointUrl, options);
    printResponse(response);
  } catch (error) {
    printError(error);
  }
}
deleteScheduleSegment();

In the code above, we perform the following:

  • Lines 10–13: We define the query parameters for the request using the broadcaster_id and id parameters.

  • 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 deleteScheduleSegment to make a call to the schedule segments endpoint.

    • Lines 21–25: We make a call to the endpoint within a try block 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 deleteScheduleSegment function.

Response fields

The response from this request is identical to the response we get from a PATCH request to the schedule settings endpoint. The table below gives a summary of the response status codes:

Status Code

Description

204

This is a success code indicating that the schedule settings were successfully updated.

400

This is an error code indicating that the request was invalid due to missing or invalid parameters.

401

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