Skip to content

Requests

When a viewer purchases an effect on Crowd Control, an effect request is sent over the channel as a UTF-8 string containing a JSON payload.

NameTypeValueNotes
iduintThe request ID, all responses to this request should contain the same ID value.These are not guaranteed to be sequential or increasing.
codestring?The identifier of the requested effect.Only present on request types 0 (Test), 1(Start) and 2 (Stop).
messagestring?A secondary text value associated with the request.Contains flavortext on effect requests but may also be used for login information.
parametersobject?[]?This field contains any parameters the user has selected.
targetsTarget?[]?For packs on multiplayer servers, contains Target structures indicating which player should be targeted by an effect request.
durationlong?The requested duration of the effect, in milliseconds.An option to report this value as decimal seconds (double?) will be available in a future release.
quantitylong?The requested quantity of the effect, if applicable.
viewerstring?The displayable name of the viewer who requested the effect.Returns “the crowd” if multiple viewers are present.
viewers[]Target?[]?Contains Target structures indicating which viewer(s) requested the effect.
costint?The price that the viewer(s) paid for the effect, in coins.
typeRequestType (int)The type of message. See RequestType enum below.Appears as an integer value.

Responses

NameTypeValueNotes
iduintThe request ID, all responses to arequest should contain the same ID value.This should be 0 for game-initiated messages.
codestring?The identifier of the requested effect.
statusEffectStatusIndicates the status of the effect request or class.
messagestring?A secondary text value associated with the request.Used for login information, omitted otherwise.
timeRemaininglong?The requested duration of the effect, in milliseconds.An option to report this value as decimal seconds (double?) will be available in a future release.
typeResponseType (int)Indicates the type of message. See ResponseType enum below.Appears as an integer value.

RequestType Enumeration

NameTypeDescriptionNotes
Test0x00Respond as with a normal request but don’t actually activate the effect.
Start0x01A standard effect request. A response (see above) is always required.
Stop0x02A request to stop all instances of the requested effect code.
PlayerInfo0xE0RESERVED This field will appear in a future release. Request information about the player.
Login0xF0Indicates that this is a login request or response.
KeepAlive0xFFCan be used in either direction to keep connections open or test connection status. Responses are neither expected nor given.

ResponseType Enumeration

NameTypeDescriptionNotes
EffectRequest0x00A response to an effect request.The response ID should match the request ID. Multiple responses with the same ID are allowed in the case of timed effects.
EffectStatus0x01A status update on a type of effect.These messages concern the specified effect in general, not a specific instance.
Login0xF0Indicates that this is a login request or response.Whether this represents a request or response depends on the value of AuthenticationMode (see below).
LoginSuccess0xF1Indicates the login was successful.
Disconnect0xFE
KeepAlive0xFFCan be used in either direction to keep connections open or test connection status. Responses are neither expected nor given.Request ID will be 0.

EffectStatus Enumeration

Effect Instance Messages

NameTypeDescriptionNotes
Success0x00The effect executed successfully.
Failure0x01The effect failed to trigger, but is still available for use. Viewer(s) will be refunded.
Unavailable0x02Same as Failure but the effect is no longer available for use for the remainder of the game.
Retry0x03The effect cannot be triggered right now, try again in a few seconds.This is the "normal" failure response.
Queue0x04The effect has been queued for execution after the current one ends.INTERNAL USE ONLY
Running0x05The effect triggered successfully and is now active until it ends.INTERNAL USE ONLY
Paused0x06The timed effect has been paused and is now waiting.
Resumed0x07The timed effect has been resumed and is counting down again.
Finished0x08The timed effect has finished.

Effect Class Messages

NameTypeDescriptionNotes
Visible0x80The effect should be shown in the menu.
NotVisible0x81The effect should be hidden in the menu.
Selectable0x82The effect should be selectable in the menu.
NotSelectable0x83The effect should be unselectable in the menu.

System Status Messages

NameTypeDescriptionNotes
NotReady0xFFThe processor isn't ready to start or has shut down.
idstring?The service identifier of the player/viewer.This is always a string.
namestring?The display name of the player/viewer.
loginstring?The login name of the player/viewer.This field may not be available on all services.
avatarstring?The avatar name of the player/viewer.This field may not be available on all services.
serviceServiceType (int)RESERVEDRESERVED This field will appear in a future release.Appears as an integer value. See RequestType enum below.

Target Structure

NameTypeValueNotes
idstring?The service identifier of the player/viewer.This is always a string.
namestring?The display name of the player/viewer.
loginstring?The login name of the player/viewer.This field may not be available on all services.
avatarstring?The avatar name of the player/viewer.This field may not be available on all services.
serviceServiceType (int)RESERVEDRESERVED This field will appear in a future release.Appears as an integer value. See RequestType enum below.