Websockets
The Tyro Connect websocket API is intended for use by integrations that require Tyro Connect to deliver the message to the individual location. If possible please consider using the webhooks integration method as it is more flexible and reliable.
To open a websocket connection you must know the Tyro Connect locationId of the location where the socket is being opened. Websockets are intended to represent a single location and will only receive the events for that single location.
The uri for opening a web socket is: wss://api.tyro.com/connect/pos/notifications/*locationId*
Make sure to indicate the data format and protocol version in the Accept header. Currently this header must be set to application/vnd.tyro.connect+json;protocol=2.0
Protocol v2.0 - Hello Message
Before the connection becomes operable you are required to send a Hello Message to Tyro Connect. Your Hello Message must contain your software version along with a list of Tyro Connect API versions supported by your software. Please see the schema below for details. If you fail to send the Hello Message within the first 30 seconds after the connection has been established, Tyro Connect will close the connection again. Please see below for how we send error messages to you.
Legacy Protocol Versions
In older versions of the Websocket protocol the hello message was not required. However, the use of protocol version 2.0 is now mandatory.
Make sure you send your JWT token as an Authorization header as well the Accept header.
url: 'wss://api.tyro.com/connect/pos/notifications/{locationId}'
method: get
headers:
Accept: application/vnd.tyro.connect+json;protocol=2.0
Authorization: Bearer '{{bearer}}'| type required | string Value: "HELLO" | ||||
| posVersion required | string | ||||
required | Array of objects | ||||
Array
| |||||
{
"type": "HELLO",
"posVersion": "12.20.05",
"supportedApis": [
{
"name": "FOOD_ORDERING",
"version": "1.0"
},
{
"name": "BOOKING",
"version": "1.1"
}
]
}Message Payload
Tyro Connect will send any message events over the websocket connection. It will be a json encoded string message that contains an array of all new messages, that looks like this:
| type required | string | ||||||
required | object | ||||||
| |||||||
[
{
"type": "ORDER_CREATED",
"data": {
"resource": "order",
"id": "abcxyz123-2c32-4a0d-a0dd-f766e965235e",
"uri": "https://api.tyro.com/connect/orders/abcxyz123-2c32-4a0d-a0dd-f766e965235e"
}
}
]Confirming message has been received
Once an event has been received, the POS needs to send a reply via the websocket to inform Tyro Connect that the event has been received:
| type required | string Value: "MessageReceived" |
| id required | string |
{
"type": "MessageReceived",
"id": "event-1234"
}When new connection is established
When a new connection is established, Tyro Connect will send messages about all the orders that have not been marked as MessageReceived by the POS at the time of the connection. This will make sure that you don't lose an order even if the websocket connection is broken or closed.
Keeping the Connection Open
To ensure that the connection is still alive and to improve the performance of orders delivery to the POS location, please send a PING message every 20s and verify the PONG response.
If we do not receive a PING message for 45 seconds the server will close the websocket.
Tyro Connect follows the RFC standard protocol when it comes to websocket implementation: https://tools.ietf.org/html/rfc6455#section-5.5.2
Duplicated messages
Duplicate, Unknown or Out of Order Events
Please ensure your implementation ignores the following occurrences:
- Duplicate Events: Please make sure that your system can handle duplicate events i.e a message with an identical
typeandid. If you receive an message about an event you have already received please ignore it. This should be an uncommon occurrence but can occur if Tyro Connect encounters an error and we are not sure we delivered the message to you. - Out of Order Events: Rare network issues could potentially result in out-of-order events. If you receive a message about an event that appears to be outdated, please ignore it as this is most likely an out-of-order event.
- Unknown Events: It is also possible that Tyro Connect publishes events with a
typethat you do not support. When this happens please ensure that your implementation ignores the event.
Error Handling
When Tyro Connect detects a problem with the connection (for example a non-conformant or missing Hello Message) it will send an object to you containing an error property which specifies the error. Right after sending this mesage, Tyro Connect will close the connection.