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.

Name	Type	Value	Notes
id	uint	The request ID, all responses to this request should contain the same ID value.	These are not guaranteed to be sequential or increasing.
code	string?	The identifier of the requested effect.	Only present on request types 0 (Test), 1(Start) and 2 (Stop).
message	string?	A secondary text value associated with the request.	Contains flavortext on effect requests but may also be used for login information.
parameters	object?[]?		This field contains any parameters the user has selected.
targets	Target?[]?	For packs on multiplayer servers, contains Target structures indicating which player should be targeted by an effect request.
duration	long?	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.
quantity	long?	The requested quantity of the effect, if applicable.
viewer	string?	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.
cost	int?	The price that the viewer(s) paid for the effect, in coins.
type	RequestType (int)	The type of message. See RequestType enum below.	Appears as an integer value.

Responses

Name	Type	Value	Notes
id	uint	The request ID, all responses to arequest should contain the same ID value.	This should be 0 for game-initiated messages.
code	string?	The identifier of the requested effect.
status	EffectStatus	Indicates the status of the effect request or class.
message	string?	A secondary text value associated with the request.	Used for login information, omitted otherwise.
timeRemaining	long?	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.
type	ResponseType (int)	Indicates the type of message. See ResponseType enum below.	Appears as an integer value.

RequestType Enumeration

Name	Type	Description	Notes
Test	0x00	Respond as with a normal request but don’t actually activate the effect.
Start	0x01	A standard effect request. A response (see above) is always required.
Stop	0x02	A request to stop all instances of the requested effect code.
PlayerInfo	0xE0	RESERVED This field will appear in a future release. Request information about the player.
Login	0xF0	Indicates that this is a login request or response.
KeepAlive	0xFF	Can be used in either direction to keep connections open or test connection status. Responses are neither expected nor given.

ResponseType Enumeration

Name	Type	Description	Notes
EffectRequest	0x00	A 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.
EffectStatus	0x01	A status update on a type of effect.	These messages concern the specified effect in general, not a specific instance.
Login	0xF0	Indicates that this is a login request or response.	Whether this represents a request or response depends on the value of AuthenticationMode (see below).
LoginSuccess	0xF1	Indicates the login was successful.
Disconnect	0xFE
KeepAlive	0xFF	Can 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

Name	Type	Description	Notes
Success	0x00	The effect executed successfully.
Failure	0x01	The effect failed to trigger, but is still available for use. Viewer(s) will be refunded.
Unavailable	0x02	Same as Failure but the effect is no longer available for use for the remainder of the game.
Retry	0x03	The effect cannot be triggered right now, try again in a few seconds.	This is the "normal" failure response.
Queue	0x04	The effect has been queued for execution after the current one ends.	INTERNAL USE ONLY
Running	0x05	The effect triggered successfully and is now active until it ends.	INTERNAL USE ONLY
Paused	0x06	The timed effect has been paused and is now waiting.
Resumed	0x07	The timed effect has been resumed and is counting down again.
Finished	0x08	The timed effect has finished.

Effect Class Messages

Name	Type	Description	Notes
Visible	0x80	The effect should be shown in the menu.
NotVisible	0x81	The effect should be hidden in the menu.
Selectable	0x82	The effect should be selectable in the menu.
NotSelectable	0x83	The effect should be unselectable in the menu.

System Status Messages

Name	Type	Description	Notes
NotReady	0xFF	The processor isn't ready to start or has shut down.
id	string?	The service identifier of the player/viewer.	This is always a string.
name	string?	The display name of the player/viewer.
login	string?	The login name of the player/viewer.	This field may not be available on all services.
avatar	string?	The avatar name of the player/viewer.	This field may not be available on all services.
service	ServiceType (int)	RESERVED	RESERVED This field will appear in a future release.Appears as an integer value. See RequestType enum below.

Target Structure

Name	Type	Value	Notes
id	string?	The service identifier of the player/viewer.	This is always a string.
name	string?	The display name of the player/viewer.
login	string?	The login name of the player/viewer.	This field may not be available on all services.
avatar	string?	The avatar name of the player/viewer.	This field may not be available on all services.
service	ServiceType (int)	RESERVED	RESERVED This field will appear in a future release.Appears as an integer value. See RequestType enum below.