# README
THIS REPO IS ARCHIVED PLEASE SEE
https://github.com/seventv/seventv
for more info
7TV EventAPI
The Event API allows developers to receive real-time updates on 7TV data and implement instantaneous feedback in applications. This service is used primarily to push channel emote changes to clients without requiring a manual refresh and it powers systems such as personal emotes. To get started on using this service see the documentation below.
- 7TV EventAPI
Supported Protocols
- Server-Sent Events / HTTP
- WebSocket
- Webhooks (planned)
API Documentation
Versions
Base URL: https://events.7tv.io
| Name | Status |
|---|---|
| V3 | ✅ Supported |
| V2 | Skipped |
| V1 | ⚠️ Deprecated |
Opcodes
Operation codes are used to identify what kind of payload an event contains.
| Op | Name | Type | Description |
|---|---|---|---|
| 0 | Dispatch | ⬇️ | A standard event message, sent when a subscribed event is emitted |
| 1 | Hello | ⬇️ | Received upon connecting, presents info about the session |
| 2 | Heartbeat | ⬇️ | Ensures the connection is still alive |
| 4 | Reconnect | ⬇️ | Server wants the client to reconnect |
| 5 | Ack | ⬇️ | Server acknowledges an action by the client |
| 6 | Error | ⬇️ | An error occured, you should log this |
| 7 | End of Stream | ⬇️ | The server will send no further data and imminently end the connection |
| 33 | Identify | ⬆️ | Authenticate with an account |
| 34 | Resume | ⬆️ | Try to resume a previous session |
| 35 | Subscribe | ⬆️ | Watch for changes on specific objects or sources. Don't smash it! |
| 36 | Unsubscribe | ⬆️ | Stop listening for changes |
| 37 | Signal | ⬆️ |
Legends: ⬆️ sent by client, ⬇️ sent by server
Close codes
Close codes provide a reason for the closure of a connection to help clients understand what happened.
| Code | Name | Description | Reconnect? |
|---|---|---|---|
| 4000 | Server Error | an error occured on the server's end | Yes |
| 4001 | Unknown Operation | the client sent an unexpected opcode | No¹ |
| 4002 | Invalid Payload | the client sent a payload that couldn't be decoded | No¹ |
| 4003 | Auth Failure | the client unsucessfully tried to identify | No¹ |
| 4004 | Already Identified | the client wanted to identify again | No¹ |
| 4005 | Rate Limited | the client is being rate-limited | Maybe³ |
| 4006 | Restart | the server is restarting and the client should reconnect | Yes |
| 4007 | Maintenance | the server is in maintenance mode and not accepting connections | Yes² |
| 4008 | Timeout | the client was idle for too long | Yes |
| 4009 | Already Subscribed | the client tried to subscribe to an event twice | No¹ |
| 4010 | Not Subscribed | the client tried to unsubscribe from an event they weren't subscribing to | No¹ |
| 4011 | Insufficient Privilege | the client did something that they did not have permission for | Maybe³ |
¹ this code indicate a bad client implementation. you must log such error and fix the issue before reconnecting ² reconnect with significantly greater delay, i.e at least 5 minutes, including jitter ³ only reconnect if this was initiated by action of the end-user
Payloads
Dispatch (0)
| Key | Type | Description |
|---|---|---|
| type | EventType | the event type |
| body | ChangeMap | detailed changes |
ChangeMap
| Key | Type | Description |
|---|---|---|
| id | ObjectID | the object's ID |
| kind | int8 | the object kind |
| contextual? | bool | if true, this event represents a change local only to the current session |
| actor | User | the user responsible for these changes |
| added? | []ChangeField | a list of added fields |
| updated? | []ChangeField | a list of updated fields |
| removed? | []ChangeField | a list of removed fields |
| pushed? | []ChangeField | a list of items pushed to an array |
| pulled? | []ChangeField | a list of items pulled from an array |
ChangeField
| Key | Type | Description |
|---|---|---|
| key | string | the key in context |
| index | int? | if the field is an array, this is the index of the item within the array that was updated |
| nested¹ | bool | if true, this means the current value is nested deeper |
| old_value | object or nil | the previous value |
| value | object, []ChangeField or nil | the new value |
¹ the value field will always be []ChangeField when nested is true.
Hello (1)
| Key | Type | Description |
|---|---|---|
| heartbeat_interval | uint32 | interval in milliseconds between each heartbeat |
| session_id | string | unique token for this session, used for resuming and mutating the session |
| subscription_limit | int32 | the maximum amount of subscriptions this connection can initiate |
Heartbeat
| Key | Type | Description |
|---|---|---|
| count | uint64 | The amount of heartbeats so far |
Ack (5)
| Key | Type | Description |
|---|---|---|
| command | string | the acknowledged sent opcode in text form |
| data | echo | the data sent by the client |
Resume (34)
| Key | Type | Description |
|---|---|---|
| session_id | string | the id of the previous session |
Subscribe (35)
| Key | Type | Description |
|---|---|---|
| type | string | subscription type |
| condition | string map | filter messages by conditions |
Example
{
"op": 35,
"d": {
"type": "emote_set.update",
"condition": {
// valid fields in the condition depend on the subscription type
// though in most cases except creations, object_id is acceptable
// to filter for a specific object.
"object_id": "62cdd34e72a832540de95857"
}
}
}
Unsubscribe (36)
| Key | Type | Description |
|---|---|---|
| type | string | subscription type |
| condition? | string map | filter messages by conditions |
{
"op": 36,
"d": {
"type": "emote_set.update",
"condition": {
"object_id": "62cdd34e72a832540de95857"
}
}
}
End of Stream (7)
End of Stream events are sent when the connection is closed by the server.
The close code provided in the event indicates the reason for the disconnect and whether or not the client should reconnect.
| Key | Type | Description |
|---|---|---|
| code | uint16 | close code |
| message | string | a text message about the closure |
Subscription types
Subscription Types
| Type | Kind |
|---|---|
| System - Announcement | system.announcement |
| Create Emote | emote.create |
| Update Emote | emote.update |
| Delete Emote | emote.delete |
| Create Emote Set | emote_set.create |
| Update Emote Set | emote_set.update |
| Delete Emote Set | emote_set.delete |
| Create User | user.create |
| Update User | user.update |
| Delete User | user.delete |
| Add User Connection | user.add_connection |
| Update User Connection | user.update_connection |
| Delete User Connection | user.delete_connection |
| Create Cosmetic | cosmetic.create |
| Update Cosmetic | cosmetic.update |
| Delete Cosmetic | cosmetic.delete |
| Create Entitlement | entitlement.create |
| Update Entitlement | entitlement.update |
| Delete Entitlement | entitlement.delete |
If you'd like to receive all events about an object, it is also possible to use an asterisk symbol as a wildcard. For example, using the type emote.* will subscribe to each of emote.create, emote.update and emote.delete.
EventStream / Server-Sent Events (HTTP)
EventStream, or Server-Sent Events (SSE) is the recommended way to use the EventAPI. This is a one-way stream which operates via a regular HTTP connection rather than a different protocol such as WebSocket.
The EventStream access point is https://events.7tv.io/v3. The following sections will cover how to initiate and modify the connection.
Message Structure (EventStream)
In a browser environment, the EventSource interface exists to automatically handle an EventStream endpoint.
Otherwise, to read and parse this data refer to the spec for Server-Sent Events.
Opcodes are sent in their text form as the event's type, and the data will always be JSON.
Connection (EventStream)
Upon opening the connection, you will receive a [1] HELLO event.
Inline Event Subscriptions (EventStream)
It is possible to add subscriptions directly in the connection string, by appending a @ to the URL followed by a URL-encoded string with the following syntax,
{type}<{condition1}={value1};{condition2}={value2}>;...
where type is a subscription type, then wrapped between brackets (<...>) are a list of conditions.
Separate each subscription by a comma. The same type can be subscribed to multiple times with different conditions.
The entire inline subscription string must be URL-encoded.
Full examples
Subscribe to updates on a specific emote set
: GET https://events.7tv.io/v3@emote_set.update<object_id=62cdd34e72a832540de95857>
Subscribe to all entitlement and cosmetic events on a specific channel
: GET https://events.7tv.io/v3@entitlement.*<host_id=60867b015e01df61570ab900;connection_id=1234>,cosmetic.*<host_id=60867b015e01df61570ab900;connection_id=1234>
At this time, it is possible to subscribe with no conditions and effectively turn the connection into a Firehose, however this may be restricted in the future.
Managing subscriptions (EventStream)
Adding or removing a subscription is done by sending a request via a REST endpoint and passing your session ID to authenticate.
The endpoint for managing subscriptions is currently unavailable. You may use Inline Event Subscriptions in the meantime.
Acks (EventStream)
An ack will be sent when the session is mutated, such as when subscribing or unsubscribing. ACKs are also sent when using Inline Event Subscriptions immediately after the session becomes ready. This can be used to confirm the validity of the inline subscription string.
Handling ACKs is optional, but allows an implementation to confirm that the server accepted their input.
Dispatches (EventStream)
Once subscriptions are active, you will receive [0] DISPATCH events
WebSocket
For apps which must issue commands frequently, WebSocket may be a better choice.
The websocket access point is wss://events.7tv.io/v3. The following sections will cover how to maintain and modify the connection.
Message Structure (WebSocket)
WebSocket messages are sent in JSON format and are composed of three root properties, op is the opcode, t is the timestamp of the message's formation, and d is the data payload.
| Key | Type | Description |
|---|---|---|
| op | uint8 | message operation code |
| t | date | timestamp of the message's formation in unix millis |
| d | object | generic data payload |
Connection (WebSocket)
Upon establishing a connection, you will receive a [1] HELLO event.
Heartbeat (WebSocket)
The server will send periodic heartbeats at the interval specified in the Hello payload. If heartbeats are missed for 3 cycles, the connection can be considered dead (i.e due to an error or network issue) and you should reconnect.
Resuming (WebSocket)
When a connection is dropped with a non-normal, non-error closure, it is possible to resume the session to restore subscriptions and replay missed events.
To initiate a resume, send the opcode [34] RESUME and pass the session ID from the previous connection.
If successful, the server will acknowledge the resume with an [5] ACK. Previous subscriptions will be restored, and missed [0] DISPATCH events will replay in sequence.
Managing subscriptions (WebSocket)
A subscription consists of a type and a condition. This is where you can choose exactly what kind of data your application needs.
Valid subscription types can be found here.
Subscribing (WebSocket)
To set up a subscription, you may send the opcode [35] SUBSCRIBE and these fields
You are allowed to subscribe multiple times to the same type, however, duplicated conditions will result in a disconnect with code 4009 Already Subscribed.
Unsubscribing (WebSocket)
When an event source is no longer needed, you should unsubscribe from it to avoid receiving unnecessary data with [36] UNSUBSCRIBE.
It is also possible to unsubscribe from an entire event type at once by leaving the condition field empty.
Acks (WebSocket)
An ack will be sent when a command is successfully executed, such as subscribing or unsubscribing. Handling ACKs is optional, but allows an implementation to confirm that the server accepted their input.
Dispatches (WebSocket)
Once subscriptions are active, you may start receiving messages with the [0] DISPATCH opcode. These events notify of changes to an object and allow you to keep your state up to date.