/
TwitchHelix.java
2374 lines (2253 loc) · 124 KB
/
TwitchHelix.java
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
package com.github.twitch4j.helix;
import com.github.twitch4j.common.annotation.Unofficial;
import com.github.twitch4j.common.feign.JsonStringExpander;
import com.github.twitch4j.common.feign.ObjectToJsonExpander;
import com.github.twitch4j.eventsub.EventSubSubscription;
import com.github.twitch4j.eventsub.EventSubSubscriptionStatus;
import com.github.twitch4j.eventsub.domain.RedemptionStatus;
import com.github.twitch4j.helix.domain.*;
import com.github.twitch4j.helix.webhooks.domain.WebhookRequest;
import com.netflix.hystrix.HystrixCommand;
import feign.*;
import org.apache.commons.io.IOUtils;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.time.Instant;
import java.util.Collection;
import java.util.Collections;
import java.util.List;
import java.util.UUID;
import java.util.function.Supplier;
/**
* Twitch - Helix API
*/
public interface TwitchHelix {
/**
* The default baseUrl to pass to {@link #getIngestServers(URI)}.
*/
URI INGESTS_BASE_URL = ((Supplier<URI>) () -> {
// Not pretty but needed for "Overriding the Request Line" - see: https://github.com/OpenFeign/feign/blob/master/README.md#interface-annotations
try {
return new URI("https://ingest.twitch.tv/");
} catch (Exception e) {
return null;
}
}).get();
/**
* Gets a URL that extension developers can use to download analytics reports (CSV files) for their extensions. The URL is valid for 5 minutes.
* <p>
* For detail about analytics and the fields returned, see the Insights and Analytics guide.
*
* @param authToken Auth Token
* @param after Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
* @param limit Maximum number of objects to return. Maximum: 100. Default: 20.
* @param extensionId Client ID value assigned to the extension when it is created. If this is specified, the returned URL points to an analytics report for just the specified extension.
* @param type Type of analytics report that is returned. If this is specified, the response includes one URL, for the specified report type. If this is not specified, the response includes multiple URLs (paginated), one for each report type available for the authenticated user’s Extensions. Limit: 1. Valid values: "overview_v1", "overview_v2".
* @param startedAt Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z.
* @param endedAt Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z.
* @return ExtensionAnalyticsList
*/
@RequestLine("GET /analytics/extensions?after={after}&ended_at={ended_at}&first={first}&extension_id={extension_id}&started_at={started_at}&type={type}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ExtensionAnalyticsList> getExtensionAnalyticUrl(
@Param("token") String authToken,
@Param("after") String after,
@Param("first") Integer limit,
@Param("extension_id") String extensionId,
@Param("type") String type,
@Param("started_at") String startedAt,
@Param("ended_at") String endedAt
);
/**
* Gets a URL that game developers can use to download analytics reports (CSV files) for their games. The URL is valid for 5 minutes.
* <p>
* For detail about analytics and the fields returned, see the Insights and Analytics guide.
*
* @param authToken Auth Token
* @param after Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response.
* @param limit Maximum number of objects to return. Maximum: 100. Default: 20.
* @param gameId Game ID. If this is specified, the returned URL points to an analytics report for just the specified game.
* @param type Type of analytics report that is returned. If this is specified, the response includes one URL, for the specified report type. If this is not specified, the response includes multiple URLs (paginated), one for each report type available for the authenticated user’s Extensions. Limit: 1. Valid values: "overview_v1", "overview_v2".
* @param startedAt Starting date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z.
* @param endedAt Ending date/time for returned reports, in RFC3339 format with the hours, minutes, and seconds zeroed out and the UTC timezone: YYYY-MM-DDT00:00:00Z.
* @return GameAnalyticsList
*/
@RequestLine("GET /analytics/games?after={after}&ended_at={ended_at}&first={first}&game_id={game_id}&started_at={started_at}&type={type}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<GameAnalyticsList> getGameAnalyticUrl(
@Param("token") String authToken,
@Param("after") String after,
@Param("first") Integer limit,
@Param("game_id") String gameId,
@Param("type") String type,
@Param("started_at") String startedAt,
@Param("ended_at") String endedAt
);
/**
* Retrieves the list of available Cheermotes, animated emotes to which viewers can assign Bits, to cheer in chat
*
* @param authToken Auth Token
* @param broadcasterId ID for the broadcaster who might own specialized Cheermotes (optional)
* @return CheermoteList
*/
@RequestLine("GET /bits/cheermotes?broadcaster_id={broadcaster_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<CheermoteList> getCheermotes(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId
);
/**
* Gets a list of Bits products that belongs to an Extension.
*
* @param authToken App Access Token associated with the Extension client ID
* @param includeAll Optional: Whether Bits products that are disabled/expired should be included in the response. Default: false
* @return ExtensionBitsProductList
*/
@RequestLine("GET /bits/extensions?should_include_all={should_include_all}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ExtensionBitsProductList> getExtensionBitsProducts(
@Param("token") String authToken,
@Param("should_include_all") Boolean includeAll
);
/**
* Add or update a Bits products that belongs to an Extension.
* <p>
* Required body fields: sku, cost.amount, cost.type, display_name.
* Optional fields: in_development, expiration, is_broadcast.
*
* @param authToken App Access Token associated with the Extension client ID
* @param product The extension bits product to add or update
* @return ExtensionBitsProductList
*/
@RequestLine("PUT /bits/extensions")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
HystrixCommand<ExtensionBitsProductList> updateExtensionBitsProduct(
@Param("token") String authToken,
ExtensionBitsProduct product
);
/**
* Gets a ranked list of Bits leaderboard information for an authorized broadcaster.
*
* @param authToken Auth Token
* @param count Number of results to be returned. Maximum: 100. Default: 10.
* @param period Time period over which data is aggregated (PST time zone). This parameter interacts with started_at. Valid values are given below. Default: "all".
* @param startedAt Timestamp for the period over which the returned data is aggregated. Must be in RFC 3339 format. If this is not provided, data is aggregated over the current period; e.g., the current day/week/month/year. This value is ignored if period is "all".
* @param userId ID of the user whose results are returned; i.e., the person who paid for the Bits.
* @return BitsLeaderboard
*/
@RequestLine("GET /bits/leaderboard?count={count}&period={period}&started_at={started_at}&user_id={user_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<BitsLeaderboard> getBitsLeaderboard(
@Param("token") String authToken,
@Param("count") Integer count,
@Param("period") String period,
@Param("started_at") String startedAt,
@Param("user_id") String userId
);
/**
* Gets a ranked list of Bits leaderboard information for an authorized broadcaster.
*
* @param authToken Auth Token
* @param count Number of results to be returned. Maximum: 100. Default: 10.
* @param period Time period over which data is aggregated (PST time zone). This parameter interacts with started_at. Valid values are given below. Default: "all".
* @param startedAt Timestamp for the period over which the returned data is aggregated. Must be in RFC 3339 format. If this is not provided, data is aggregated over the current period; e.g., the current day/week/month/year. This value is ignored if period is "all".
* @param userId ID of the user whose results are returned; i.e., the person who paid for the Bits.
* @return BitsLeaderboard
* @deprecated utilize getBitsLeaderboard where count is an Integer
*/
@Deprecated
default HystrixCommand<BitsLeaderboard> getBitsLeaderboard(
String authToken,
String count,
String period,
String startedAt,
String userId
) {
return getBitsLeaderboard(authToken, count == null || count.isEmpty() ? null : Integer.parseInt(count), period, startedAt, userId);
}
/**
* Creates a Custom Reward on a channel.
* <p>
* Query parameter broadcaster_id must match the user_id in the User-Access token.
*
* @param authToken User access token for the broadcaster (scope: channel:manage:redemptions).
* @param broadcasterId The id of the target channel, which must match the token user id.
* @param newReward The Custom Reward to be created.
* @return CustomRewardList
*/
@RequestLine("POST /channel_points/custom_rewards?broadcaster_id={broadcaster_id}")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
HystrixCommand<CustomRewardList> createCustomReward(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
CustomReward newReward
);
/**
* Deletes a Custom Reward on a channel.
* <p>
* Only rewards created programmatically by the same client_id can be deleted.
* Any UNFULFILLED Custom Reward Redemptions of the deleted Custom Reward will be updated to the FULFILLED status.
*
* @param authToken User access token for the broadcaster (scope: channel:manage:redemptions).
* @param broadcasterId The id of the target channel, which must match the token user id.
* @param rewardId ID of the Custom Reward to delete, must match a Custom Reward on broadcaster_id’s channel.
* @return 204 No Content upon a successful deletion
*/
@RequestLine("DELETE /channel_points/custom_rewards?broadcaster_id={broadcaster_id}&id={id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<Void> deleteCustomReward(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("id") String rewardId
);
/**
* Returns a list of Custom Reward objects for the Custom Rewards on a channel.
* <p>
* Developers only have access to update and delete rewards that were created programmatically by the same/calling client_id.
* <p>
* There is a limit of 50 Custom Rewards on a channel at a time. This includes both enabled and disabled Custom Rewards.
*
* @param authToken User access token for the broadcaster (scope: channel:manage:redemptions).
* @param broadcasterId Required: The id of the target channel, which must match the token user id.
* @param rewardIds Optional: Filters the results to only returns reward objects for the Custom Rewards with matching ID. Maximum: 50.
* @param onlyManageableRewards Optional: When set to true, only returns custom rewards that the calling client_id can manage. Default: false.
* @return CustomRewardList
*/
@RequestLine("GET /channel_points/custom_rewards?broadcaster_id={broadcaster_id}&id={id}&only_manageable_rewards={only_manageable_rewards}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<CustomRewardList> getCustomRewards(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("id") Collection<String> rewardIds,
@Param("only_manageable_rewards") Boolean onlyManageableRewards
);
/**
* Returns Custom Reward Redemption objects for a Custom Reward on a channel that was created by the same client_id.
* <p>
* Developers only have access to get and update redemptions for the rewards created programmatically by the same client_id.
*
* @param authToken User access token for the broadcaster (scope: channel:manage:redemptions).
* @param broadcasterId The id of the target channel, which must match the token user id.
* @param rewardId When ID is not provided, this parameter returns paginated Custom Reward Redemption objects for redemptions of the Custom Reward with ID reward_id.
* @param redemptionIds When used, this param filters the results and only returns Custom Reward Redemption objects for the redemptions with matching ID. Maximum: 50.
* @param status When id is not provided, this param is required and filters the paginated Custom Reward Redemption objects for redemptions with the matching status.
* @param sort Sort order of redemptions returned when getting the paginated Custom Reward Redemption objects for a reward. One of: OLDEST, NEWEST. Default: OLDEST.
* @param after Cursor for forward pagination: tells the server where to start fetching the next set of results, in a multi-page response. This applies only to queries without ID.
* @param limit Number of results to be returned when getting the paginated Custom Reward Redemption objects for a reward. Maximum: 50. Default: 20.
* @return CustomRewardRedemptionList
*/
@RequestLine("GET /channel_points/custom_rewards/redemptions?broadcaster_id={broadcaster_id}&reward_id={reward_id}&id={id}&status={status}&sort={sort}&after={after}&first={first}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<CustomRewardRedemptionList> getCustomRewardRedemption(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("reward_id") String rewardId,
@Param("id") Collection<String> redemptionIds,
@Param("status") RedemptionStatus status,
@Param("sort") String sort,
@Param("after") String after,
@Param("first") Integer limit
);
/**
* Updates a Custom Reward created on a channel.
* <p>
* Only rewards created programmatically by the same client_id can be updated.
*
* @param authToken User access token for the broadcaster (scope: channel:manage:redemptions).
* @param broadcasterId The id of the target channel, which must match the token user id.
* @param rewardId ID of the Custom Reward to delete, must match a Custom Reward on broadcaster_id’s channel.
* @param updatedReward A CustomReward object with specific field(s) updated.
* @return CustomRewardList
*/
@RequestLine("PATCH /channel_points/custom_rewards?broadcaster_id={broadcaster_id}&id={id}")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
HystrixCommand<CustomRewardList> updateCustomReward(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("id") String rewardId,
CustomReward updatedReward
);
/**
* Updates the status of Custom Reward Redemption objects on a channel that are in the UNFULFILLED status.
* <p>
* Only redemptions for a reward created programmatically by the same client_id as attached to the access token can be updated.
*
* @param authToken User access token for the broadcaster (scope: channel:manage:redemptions).
* @param broadcasterId The id of the target channel, which must match the token user id.
* @param rewardId ID of the Custom Reward the redemptions to be updated are for.
* @param redemptionIds ID of the Custom Reward Redemption to update, must match a Custom Reward Redemption on broadcaster_id’s channel. Max: 50.
* @param newStatus The new status to set redemptions to. Can be either FULFILLED or CANCELED. Updating to CANCELED will refund the user their points.
* @return CustomRewardRedemptionList
*/
@RequestLine("PATCH /channel_points/custom_rewards/redemptions?broadcaster_id={broadcaster_id}&reward_id={reward_id}&id={id}")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
@Body("%7B\"status\":\"{status}\"%7D")
HystrixCommand<CustomRewardRedemptionList> updateRedemptionStatus(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("reward_id") String rewardId,
@Param("id") Collection<String> redemptionIds,
@Param("status") RedemptionStatus newStatus
);
/**
* Gets a list of custom chat badges that can be used in chat for the specified channel.
* This includes <a href="https://help.twitch.tv/s/article/subscriber-badge-guide">subscriber badges</a> and <a href="https://help.twitch.tv/s/article/custom-bit-badges-guide">Bit badges</a>.
*
* @param authToken User OAuth Token from the broadcaster.
* @param broadcasterId The id of the broadcaster whose chat badges are being requested. Provided broadcaster_id must match the user_id in the user OAuth token.
* @return ChatBadgeSetList
*/
@RequestLine("GET /chat/badges?broadcaster_id={broadcaster_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ChatBadgeSetList> getChannelChatBadges(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId
);
/**
* Gets a list of chat badges that can be used in chat for any channel.
*
* @param authToken User OAuth Token or App Access Token.
* @return ChatBadgeSetList
*/
@RequestLine("GET /chat/badges/global")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ChatBadgeSetList> getGlobalChatBadges(
@Param("token") String authToken
);
/**
* Gets all custom emotes for a specific Twitch channel including subscriber emotes, Bits tier emotes, and follower emotes.
* <p>
* Custom channel emotes are custom emoticons that viewers may use in Twitch chat once they are subscribed to, cheered in, or followed the channel that owns the emotes.
*
* @param authToken Any User OAuth Token or App Access Token.
* @param broadcasterId The broadcaster whose emotes are being requested.
* @return EmoteList
*/
@RequestLine("GET /chat/emotes?broadcaster_id={broadcaster_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<EmoteList> getChannelEmotes(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId
);
/**
* Gets all global emotes.
* <p>
* Global emotes are Twitch-specific emoticons that every user can use in Twitch chat.
*
* @param authToken Any User OAuth Token or App Access Token.
* @return EmoteList
*/
@RequestLine("GET /chat/emotes/global")
@Headers("Authorization: Bearer {token}")
HystrixCommand<EmoteList> getGlobalEmotes(
@Param("token") String authToken
);
/**
* Gets all Twitch emotes for one or more specific emote sets.
*
* @param authToken Any User OAuth Token or App Access Token.
* @param ids IDs of the emote sets. Minimum: 1. Maximum: 25. Warning: at the time of writing, the enforced maximum is actually 10.
* @return EmoteList
*/
@RequestLine("GET /chat/emotes/set?emote_set_id={emote_set_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<EmoteList> getEmoteSets(
@Param("token") String authToken,
@Param("emote_set_id") Collection<String> ids
);
/**
* Gets the broadcaster’s chat settings.
*
* @param authToken Required: OAuth access token. To read the non-moderator chat delay, a moderator's user access token must be specified with the moderator:read:chat_settings scope.
* @param broadcasterId Required: The ID of the broadcaster whose chat settings you want to get.
* @param moderatorId Optional: The ID of a user that has permission to moderate the broadcaster’s chat room. Required only to access non moderator chat delay fields.
* @return ChatSettingsWrapper
* @see com.github.twitch4j.auth.domain.TwitchScopes#HELIX_CHAT_SETTINGS_READ
*/
@RequestLine("GET /chat/settings?broadcaster_id={broadcaster_id}&moderator_id={moderator_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ChatSettingsWrapper> getChatSettings(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("moderator_id") String moderatorId
);
/**
* Updates the broadcaster’s chat settings.
*
* @param authToken Required: User access token (of the broadcaster or a moderator) with scope set to moderator:manage:chat_settings, associated with moderatorId.
* @param broadcasterId Required: The ID of the broadcaster whose chat settings you want to update.
* @param moderatorId Required: The ID of a user that has permission to moderate the broadcaster’s chat room. Set this to the same value as broadcasterId if a broadcaster token is being used.
* @param chatSettings Required: The chat settings that you want to update.
* @return ChatSettingsWrapper
* @see com.github.twitch4j.auth.domain.TwitchScopes#HELIX_CHAT_SETTINGS_MANAGE
*/
@RequestLine("PATCH /chat/settings?broadcaster_id={broadcaster_id}&moderator_id={moderator_id}")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
HystrixCommand<ChatSettingsWrapper> updateChatSettings(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("moderator_id") String moderatorId,
ChatSettings chatSettings
);
/**
* Gets the status of one or more provided codes.
* <p>
* The API is throttled to one request per second per authenticated user.
*
* @param authToken App access token. The client ID associated with the app access token must be approved by Twitch as part of a contracted arrangement.
* @param code The code to get the status of. 1-20 code parameters are allowed.
* @param userId Represents a numeric Twitch user ID. The user account which is going to receive the entitlement associated with the code.
* @return CodeStatusList
*/
@RequestLine("GET /entitlements/codes?code={code}&user_id={user_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<CodeStatusList> getCodeStatus(
@Param("token") String authToken,
@Param("code") List<String> code,
@Param("user_id") Integer userId
);
/**
* Redeems one or more provided codes to the authenticated Twitch user.
* <p>
* The API is throttled to one request per second per authenticated user.
*
* @param authToken App access token. The client ID associated with the app access token must be one approved by Twitch.
* @param code The code to redeem to the authenticated user’s account. 1-20 code parameters are allowed.
* @param userId Represents a numeric Twitch user ID. The user account which is going to receive the entitlement associated with the code.
* @return CodeStatusList
*/
@RequestLine("POST /entitlements/codes?code={code}&user_id={user_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<CodeStatusList> redeemCode(
@Param("token") String authToken,
@Param("code") List<String> code,
@Param("user_id") Integer userId
);
/**
* Gets a list of entitlements for a given organization that have been granted to a game, user, or both.
* <p>
* Valid combinations of requests are:
* <ul>
* <li>No fields - All entitlements with benefits owned by your organization.</li>
* <li>Only userId - All entitlements for a user with benefits owned by your organization.</li>
* <li>Only gameId - All entitlements for all users for a game. Your organization must own the game.</li>
* <li>Both userId and gameId - All entitlements for the game granted to a user. Your organization must own the game.</li>
* </ul>
* <p>
* Pagination support: Forward only
*
* @param authToken Required: App Access OAuth Token. OAuth Token Client ID must have ownership of Game: Client ID {@literal >} RBAC Organization ID {@literal >} Game ID.
* @param id Optional: Unique Identifier of the entitlement.
* @param userId Optional: A Twitch User ID.
* @param gameId Optional: A Twitch Game ID.
* @param status Optional: Fulfillment status used to filter entitlements.
* @param after Optional: The cursor used to fetch the next page of data.
* @param limit Optional: Maximum number of entitlements to return. Default: 20. Max: 1000.
* @return DropsEntitlementList
*/
@RequestLine("GET /entitlements/drops?id={id}&user_id={user_id}&game_id={game_id}&fulfillment_status={fulfillment_status}&after={after}&first={first}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<DropsEntitlementList> getDropsEntitlements(
@Param("token") String authToken,
@Param("id") String id,
@Param("user_id") String userId,
@Param("game_id") String gameId,
@Param("fulfillment_status") DropFulfillmentStatus status,
@Param("after") String after,
@Param("first") Integer limit
);
@Deprecated
default HystrixCommand<DropsEntitlementList> getDropsEntitlements(
@Param("token") String authToken,
@Param("id") String id,
@Param("user_id") String userId,
@Param("game_id") String gameId,
@Param("after") String after,
@Param("first") Integer limit
) {
return getDropsEntitlements(authToken, id, userId, gameId, null, after, limit);
}
/**
* Updates the fulfillment status on a set of Drops entitlements, specified by their entitlement IDs.
*
* @param authToken User OAuth Token or App Access Token where the client ID associated with the access token must have ownership of the game.
* @param input The fulfillment_status to assign to each of the entitlement_ids.
* @return UpdatedDropEntitlementsList
*/
@RequestLine("PATCH /entitlements/drops")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
HystrixCommand<UpdatedDropEntitlementsList> updateDropsEntitlements(
@Param("token") String authToken,
UpdateDropEntitlementInput input
);
/**
* Creates an EventSub subscription.
*
* @param authToken Required: App access token.
* @param subscription Required: The subscription that is being created. Must include type, version, condition, and transport.
* @return EventSubSubscriptionList
*/
@RequestLine("POST /eventsub/subscriptions")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
HystrixCommand<EventSubSubscriptionList> createEventSubSubscription(
@Param("token") String authToken,
EventSubSubscription subscription
);
/**
* Delete an EventSub subscription.
*
* @param authToken Required: App Access Token.
* @param subscriptionId Required: The subscription ID for the subscription you want to delete.
* @return 204 No Content upon a successful deletion
*/
@RequestLine("DELETE /eventsub/subscriptions?id={id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<Void> deleteEventSubSubscription(
@Param("token") String authToken,
@Param("id") String subscriptionId
);
/**
* Get a list of your EventSub subscriptions.
*
* @param authToken Required: App Access Token.
* @param status Optional: Include this parameter to filter subscriptions by their status.
* @param after Optional: Cursor for forward pagination.
* @param limit Optional: Maximum number of objects to return. Maximum: 100. Minimum: 10.
* @return EventSubSubscriptionList
*/
@RequestLine("GET /eventsub/subscriptions?status={status}&after={after}&first={first}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<EventSubSubscriptionList> getEventSubSubscriptions(
@Param("token") String authToken,
@Param("status") EventSubSubscriptionStatus status,
@Param("after") String after,
@Param("first") Integer limit
);
/**
* Gets information about your Extensions; either the current version or a specified version.
*
* @param jwtToken Signed JWT with role set to "external".
* @param extensionId ID of the Extension.
* @param extensionVersion The specific version of the Extension to return. If not provided, the current version is returned.
* @return ReleasedExtensionList
*/
@RequestLine("GET /extensions?extension_id={extension_id}&extension_version={extension_version}")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}"
})
HystrixCommand<ReleasedExtensionList> getExtensions(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId,
@Param("extension_version") String extensionVersion
);
/**
* Sends a specified chat message to a specified channel.
* <p>
* The message will appear in the channel’s chat as a normal message.
* The “username” of the message is the Extension name.
* <p>
* There is a limit of 12 messages per minute, per channel.
*
* @param jwtToken Signed JWT with user_id and role (set to "external").
* @param extensionId Client ID associated with the Extension.
* @param extensionVersion Version of the Extension sending this message.
* @param broadcasterId User ID of the broadcaster whose channel has the Extension activated.
* @param text Message for Twitch chat. Maximum: 280 characters.
* @return 204 No Content upon a successful request
*/
@RequestLine("POST /extensions/chat?broadcaster_id={broadcaster_id}")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}",
"Content-Type: application/json"
})
@Body("%7B\"extension_id\":\"{extension_id}\",\"extension_version\":\"{extension_version}\",\"text\":\"{text}\"%7D")
HystrixCommand<Void> sendExtensionChatMessage(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId,
@Param("extension_version") String extensionVersion,
@Param("broadcaster_id") String broadcasterId,
@Param("text") String text
);
/**
* Gets the specified configuration segment from the specified extension.
* <p>
* You can retrieve each segment a maximum of 20 times per minute.
* If you exceed the limit, the request returns HTTP status code 429.
*
* @param jwtToken Signed JWT with exp, user_id, and role (set to "external").
* @param extensionId The ID of the extension that contains the configuration segment you want to get.
* @param segment The type of configuration segment to get.
* @param broadcasterId The ID of the broadcaster for the configuration returned. This parameter is required if you set the segment parameter to broadcaster or developer. Do not specify this parameter if you set segment to global.
* @return ExtensionConfigurationSegmentList
*/
@RequestLine("GET /extensions/configurations?broadcaster_id={broadcaster_id}&extension_id={extension_id}&segment={segment}")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}"
})
HystrixCommand<ExtensionConfigurationSegmentList> getExtensionConfigurationSegment(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId,
@Param("segment") List<ExtensionSegment> segment,
@Param("broadcaster_id") String broadcasterId
);
/**
* Sets a single configuration segment of any type.
* <p>
* Each segment is limited to 5 KB and can be set at most 20 times per minute.
* Updates to this data are not delivered to Extensions that have already been rendered.
*
* @param jwtToken Signed JWT with exp, user_id, and role (set to "external").
* @param extensionId ID for the Extension which the configuration is for.
* @param input Segment configuration info.
* @return 204 No Content upon a successful request.
*/
@RequestLine("PUT /extensions/configurations")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}",
"Content-Type: application/json"
})
HystrixCommand<Void> setExtensionConfigurationSegment(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId,
ExtensionConfigurationSegmentInput input
);
/**
* Retrieves a specified Extension’s secret data consisting of a version and an array of secret objects.
* <p>
* Each secret object contains a base64-encoded secret, a UTC timestamp when the secret becomes active, and a timestamp when the secret expires.
* <p>
* Signed JWT created by an Extension Backend Service (EBS), following the requirements documented in Signing the JWT.
* A signed JWT must include the exp, user_id, and role fields documented in JWT Schema, and role must be set to "external".
*
* @param jwtToken Signed JWT with exp, user_id, and role (set to "external").
* @param extensionId The Client ID associated with the extension.
* @return ExtensionSecretsList
*/
@RequestLine("GET /extensions/jwt/secrets?extension_id={extension_id}")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}"
})
HystrixCommand<ExtensionSecretsList> getExtensionSecrets(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId
);
/**
* Creates a JWT signing secret for a specific Extension.
* <p>
* Also rotates any current secrets out of service, with enough time for instances of the Extension to gracefully switch over to the new secret.
* Use this function only when you are ready to install the new secret it returns.
*
* @param jwtToken Signed JWT with exp, user_id, and role (set to "external").
* @param extensionId The Client ID associated with the extension.
* @param delay Optional: JWT signing activation delay for the newly created secret in seconds. Minimum: 300. Default: 300.
* @return ExtensionSecretsList
*/
@RequestLine("POST /extensions/jwt/secrets?extension_id={extension_id}&delay={delay}")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}"
})
HystrixCommand<ExtensionSecretsList> createExtensionSecret(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId,
@Param("delay") Integer delay
);
/**
* Returns one page of live channels that have installed or activated a specific Extension,
* identified by a client ID value assigned to the Extension when it is created.
* <p>
* A channel that recently went live may take a few minutes to appear in this list,
* and a channel may continue to appear on this list for a few minutes after it stops broadcasting.
*
* @param authToken User OAuth Token or App Access Token
* @param extensionId ID of the Extension to search for.
* @param limit Maximum number of objects to return. Maximum: 100. Default: 20.
* @param after The cursor used to fetch the next page of data.
* @return ExtensionLiveChannelsList
*/
@RequestLine("GET /extensions/live?extension_id={extension_id}&first={first}&after={after}&cursor={after}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ExtensionLiveChannelsList> getExtensionLiveChannels(
@Param("token") String authToken,
@Param("extension_id") String extensionId,
@Param("first") Integer limit,
@Param("after") String after
);
/**
* Twitch provides a publish-subscribe system for your EBS to communicate with both the broadcaster and viewers.
* Calling this endpoint forwards your message using the same mechanism as the send JavaScript helper function.
* <p>
* A message can be sent to either a specified channel or globally (all channels on which your extension is active).
* <p>
* Extension PubSub has a rate limit of 100 requests per minute for a combination of Extension client ID and broadcaster ID.
* <p>
* A signed JWT must include the channel_id and pubsub_perms fields documented in JWT Schema.
*
* @param jwtToken Signed JWT with exp, user_id, role, channel_id, pubsub_perms.send
* @param extensionId Client ID associated with the Extension.
* @param input Details on the message to be sent and its targets.
* @return 204 No Content upon a successful request.
*/
@RequestLine("POST /extensions/pubsub")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}",
"Content-Type: application/json"
})
HystrixCommand<Void> sendExtensionPubSubMessage(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId,
SendPubSubMessageInput input
);
/**
* Gets information about a released Extension; either the current version or a specified version.
*
* @param authToken User OAuth Token or App Access Token
* @param extensionId ID of the Extension.
* @param extensionVersion The specific version of the Extension to return. If not provided, the current version is returned.
* @return ReleasedExtensionList
*/
@RequestLine("GET /extensions/released?extension_id={extension_id}&extension_version={extension_version}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ReleasedExtensionList> getReleasedExtensions(
@Param("token") String authToken,
@Param("extension_id") String extensionId,
@Param("extension_version") String extensionVersion
);
/**
* Enable activation of a specified Extension, after any required broadcaster configuration is correct.
* <p>
* This is for Extensions that require broadcaster configuration before activation.
* Use this if, in Extension Capabilities, you select Custom/My Own Service.
* <p>
* You enforce required broadcaster configuration with a required_configuration string in the Extension manifest. The contents of this string can be whatever you want.
* Once your EBS determines that the Extension is correctly configured on a channel, use this endpoint to provide that same configuration string, which enables activation on the channel.
* The endpoint URL includes the channel ID of the page where the Extension is iframe embedded.
* <p>
* If a future version of the Extension requires a different configuration, change the required_configuration string in your manifest.
* When the new version is released, broadcasters will be required to re-configure that new version.
*
* @param jwtToken Signed JWT with exp, user_id, and role (set to "external").
* @param extensionId ID for the Extension to activate.
* @param extensionVersion The version fo the Extension to release.
* @param configurationVersion The version of the configuration to use with the Extension.
* @param broadcasterId User ID of the broadcaster who has activated the specified Extension on their channel.
* @return 204 No Content upon a successful request.
*/
@RequestLine("PUT /extensions/required_configuration?broadcaster_id={broadcaster_id}")
@Headers({
"Authorization: Bearer {token}",
"Client-Id: {extension_id}",
"Content-Type: application/json"
})
@Body("%7B\"extension_id\":\"{extension_id}\",\"extension_version\":\"{extension_version}\",\"required_configuration\":\"{configuration_version}\",\"configuration_version\":\"{configuration_version}\"%7D")
HystrixCommand<Void> setExtensionRequiredConfiguration(
@Param("token") String jwtToken,
@Param("extension_id") String extensionId,
@Param("extension_version") String extensionVersion,
@Param("configuration_version") String configurationVersion,
@Param("broadcaster_id") String broadcasterId
);
/**
* Get Extension Transactions allows extension back end servers to fetch a list of transactions that have occurred for their extension across all of Twitch.
*
* @param authToken App Access OAuth Token
* @param extensionId ID of the extension to list transactions for.
* @param transactionIds Transaction IDs to look up. Can include multiple to fetch multiple transactions in a single request. Maximum: 100
* @param after The cursor used to fetch the next page of data. This only applies to queries without ID. If an ID is specified, it supersedes the cursor.
* @param limit Maximum number of objects to return. Maximum: 100 Default: 20
* @return ExtensionTransactionList
*/
@RequestLine("GET /extensions/transactions?after={after}&extension_id={extension_id}&first={first}&id={id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ExtensionTransactionList> getExtensionTransactions(
@Param("token") String authToken,
@Param("extension_id") String extensionId,
@Param("id") List<String> transactionIds,
@Param("after") String after,
@Param("first") Integer limit
);
/**
* Returns a list of games or categories that match the query via name either entirely or partially
*
* @param authToken Auth Token
* @param query the search query
* @param limit Maximum number of objects to return. Maximum: 100. Default: 20.
* @param after Cursor for forward pagination
* @return CategorySearchList
*/
@RequestLine("GET /search/categories?after={after}&first={first}&query={query}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<CategorySearchList> searchCategories(
@Param("token") String authToken,
@Param("query") String query,
@Param("first") Integer limit,
@Param("after") String after
);
/**
* Gets channel information for users
*
* @param authToken Auth Token
* @param broadcasterIds IDs of the channels to be retrieved (up to 100)
* @return ChannelInformationList
*/
@RequestLine("GET /channels?broadcaster_id={broadcaster_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ChannelInformationList> getChannelInformation(
@Param("token") String authToken,
@Param("broadcaster_id") List<String> broadcasterIds
);
/**
* Modifies channel information for users
*
* @param authToken Auth Token (scope: channel:manage:broadcast or user:edit:broadcast)
* @param broadcasterId ID of the channel to be updated (required)
* @param channelInformation {@link ChannelInformation} (at least one parameter must be provided)
* @return 204 No Content upon a successful update
*/
@RequestLine("PATCH /channels?broadcaster_id={broadcaster_id}")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
HystrixCommand<Void> updateChannelInformation(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
ChannelInformation channelInformation
);
/**
* Returns a list of channels (those that have streamed within the past 6 months) that match the query either entirely or partially
*
* @param authToken Auth Token
* @param query the search query
* @param limit Maximum number of objects to return. Maximum: 100. Default: 20.
* @param after Cursor for forward pagination
* @param liveOnly Filter results for live streams only. Default: false
* @return ChannelSearchList
*/
@RequestLine("GET /search/channels?after={after}&first={first}&live_only={live_only}&query={query}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ChannelSearchList> searchChannels(
@Param("token") String authToken,
@Param("query") String query,
@Param("first") Integer limit,
@Param("after") String after,
@Param("live_only") Boolean liveOnly
);
/**
* Gets the Soundtrack track that the broadcaster is playing.
* <p>
* If the broadcaster is not playing a track, the endpoint returns HTTP status code 404 Not Found.
*
* @param authToken App access token or User access token.
* @param broadcasterId The ID of the broadcaster that’s playing a Soundtrack track.
* @return SoundtrackCurrentTrackWrapper
*/
@Unofficial // beta
@RequestLine("GET /soundtrack/current_track?broadcaster_id={broadcaster_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<SoundtrackCurrentTrackWrapper> getSoundtrackCurrentTrack(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId
);
/**
* Gets a Soundtrack playlist, which includes its list of tracks.
*
* @param authToken App access token or User access token.
* @param id The ASIN of the Soundtrack playlist to get.
* @return SoundtrackPlaylistTracksWrapper
*/
@Unofficial // beta
@RequestLine("GET /soundtrack/playlist?id={id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<SoundtrackPlaylistTracksWrapper> getSoundtrackPlaylist(
@Param("token") String authToken,
@Param("id") String id
);
/**
* Gets a list of Soundtrack playlists.
*
* @param authToken App access token or User access token.
* @return SoundtrackPlaylistMetadataList
*/
@Unofficial // beta
@RequestLine("GET /soundtrack/playlists")
@Headers("Authorization: Bearer {token}")
HystrixCommand<SoundtrackPlaylistMetadataList> getSoundtrackPlaylists(
@Param("token") String authToken
);
/**
* Starts a commercial on a specified channel
*
* @param authToken Auth Token (scope: channel:edit:commercial)
* @param broadcasterId ID of the channel requesting a commercial
* @param length Desired length of the commercial in seconds. Valid options are 30, 60, 90, 120, 150, 180.
* @return CommercialList
*/
@RequestLine("POST /channels/commercial")
@Headers({
"Authorization: Bearer {token}",
"Content-Type: application/json"
})
@Body("%7B\"broadcaster_id\":\"{broadcaster_id}\",\"length\":{length}%7D")
HystrixCommand<CommercialList> startCommercial(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId,
@Param("length") Integer length
);
/**
* Gets a list of users who have editor permissions for a specific channel.
*
* @param authToken Required: User access token of the broadcaster with the channel:read:editors scope.
* @param broadcasterId Required: Broadcaster’s user ID associated with the channel.
* @return ChannelEditorList
* @see com.github.twitch4j.auth.domain.TwitchScopes#HELIX_CHANNEL_EDITORS_READ
*/
@RequestLine("GET /channels/editors?broadcaster_id={broadcaster_id}")
@Headers("Authorization: Bearer {token}")
HystrixCommand<ChannelEditorList> getChannelEditors(
@Param("token") String authToken,
@Param("broadcaster_id") String broadcasterId
);
/**
* Creates a clip programmatically. This returns both an ID and an edit URL for the new clip.
*
* @param authToken Auth Token
* @param broadcasterId ID of the stream from which the clip will be made.
* @param hasDelay If false, the clip is captured from the live stream when the API is called; otherwise, a delay is added before the clip is captured (to account for the brief delay between the broadcaster’s stream and the viewer’s experience of that stream). Default: false.
* @return CreateClip
*/
@RequestLine("POST /clips?broadcaster_id={broadcaster_id}&has_delay={has_delay}")