Skip to content

Gateway

The Gateway is the connector for all Utilbot Applications, such as the Bot itself or the Website. The communication takes place over secure WebSockets. The Gateway should only be used via our official Applications, but you can implement your own client, if you want.

Gateway Versions

VersionStatusDefault
1Default

Payloads

Payload Structure

FieldTypeDescription
opintegerPayload Opcode
d?objectData
e?integerError Code
t?stringEvent Name
m?stringAdditional Message

? --> Field is optional.

Connecting

The Gateway is reachable via wss://gateway.utilbot.co. You can connect via a normal websocket. You must convert everything you send into a JSON String to send it to the Server. Data, that is not in the json format, will be truncated.

URL Params

FieldTypeDescriptionAccepted values
vintegerGateway Versionsee gateway versions
compression?stringThe (optional) compression of packets’zlib’

Example Connection strings: wss://gateway.utilbot.co/?v=1 or wss://gateway.utilbot.co/?v=1&compression=zlib

When the connection was successful, you should recieve the Hello Opcode 5 paylod, with the heartbeat interval:

Example Hello

{
"op": 5,
"d": {
"hearbeat": 60000
}
}

Heartbeating

After recieving the Hello, you must start sending the Heartbeat Opcode 10 every heartbeat milliseconds. When the Gateway recieves this Heartbeat, it will send you an ACK via the ACK Opcode 11. If you stop recieving this ACK, you must reconnect to the Gateway.

When the Gateway doesn’t recieve a Heartbeat when the next one should be sent, it closes the Connection with the Error Code 4006.

Example Heartbeat ACK

{
"op": 11
}

Identifying

After you started sending the Hearbeats, you must send the Identify Event. This is done via the Event Send Opcode 1. Any data you send before Identifying will be ignored and never answered.

Example Identify

{
"op": 1,
"d": {
"type": "bot",
"key": "my_key"
},
"t": "identify"
}

When everything is valid, you will get a response with the Connection Success Event