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. | |
| Visible | 0x80 | The effect should be shown in the menu. |
Effect Class Messages
| Name | Type | Description | Notes |
|---|---|---|---|
| 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. |