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.

Input 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 and 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.

Example call

Let's make a sample call to this endpoint, setting a vacation period of seven days, starting from today. We can update the timezone parameter on line 15 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
headers = {
    'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
# Defining the vacation start and end dates
start = datetime.now()           # Getting the current date/time for the start date
end = start + timedelta(days=7)  # Setting the end date a week after the start date
parameters = {
    'broadcaster_id'        : '{{USER_ID}}',
    'is_vacation_enabled'   : True,
    'vacation_start_time'   : start.astimezone().isoformat(),
    'vacation_end_time'     : end.astimezone().isoformat(),
    'timezone'              : 'America/New_York'
}
response = requests.patch('https://api.twitch.tv/helix/schedule/settings',
                          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 indicating 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.

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

Example call

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 12 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
headers = {
    'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
parameters = {
    'broadcaster_id' : '{{USER_ID}}',
    'id'             : '{{SEGMENT_ID}}'
}
payload = {
    'title' : 'This title was changed by the API'
}
response = requests.patch('https://api.twitch.tv/helix/schedule/segment',
                          headers=headers, params=parameters, json=payload).json()
print(json.dumps(response, indent=4))

The response from this PATCH request is identical to the response we get upon sending 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.

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

Example call

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
headers = {
    'Authorization' : 'Bearer {{USER_ACCESS_TOKEN}}',
    'Client-Id'     : '{{CLIENT_ID}}'
}
parameters = {
    'broadcaster_id' : '{{USER_ID}}',
    'id'             : '{{SEGMENT_ID}}'
}
response = requests.delete('https://api.twitch.tv/helix/schedule/segment',
                           headers=headers, params=parameters)
print(response.status_code)

The response from this request is identical to the response we get from a PATCH request to the schedule settings endpoint.