Getting Started
WebSocket is a protocol that provides full-duplex communication channel between a client and a server over single TCP connection. We only use the secure connection protocol wss://, not the insecure ws:// protocol.
WebSocket Address
The WebSocket is exposed on ports 443 (standard WSS communication port) and on the unused port 40,000 for spacial cases.
wss://socket.fleetfreedom.com/ghostId wss://socket.fleetfreedom.com:40000/ghostId Establishing a connection
To establish a connection with the WebSocket server, the client must send a request to wss://socket.fleetfreedom.com/ghostId where ghostId is blank, or your session identifier (described below).
Using JavaScript, creating a connection is as simple as:
var socket = new WebSocket("wss://socket.fleetfreedom.com/ghostId");
However, the socket server is not ready for commands until you receive a connectionResponse message.
connectionResponse {
"errorCode": number, /* one of the ErrorCode values */
"message": string,
"serverTime": string, /* datetime format */
"ghostId": string,
"expiry": string, /* datetime format */
"user": { /* see User for details */ },
"sessionPolicy": { /* see SessionPolicy for details */ },
"passwordPolicy": { /* see PasswordPolicy for details */ }
}
Fields that are always returned:
- errorCode
- Code that is assigned to a specific error. Refer to list of Error Codes below.
- message
- Message that describes the error.
- serverTime
- The current time on the server
- ghostId
- Unique session identifier generated by the server.
- expiry
- String representation of the session expiration time.
Optional fields that are returned only if the user has logged-in:
- user
- An object that represents the current session user
- sessionPolicy
- An object that represents the session policy of the current user's company.
- passwordPolicy
- An object that represents the password policy of the current user's company.
Logging in
If you do not provide a valid ghostId when connecting, then after receivig the connectionResponse message, you need to send a login command.
socket.send("login " + JSON.stringify({
"reqId": 1,
"username": "email@address.com",
"password": "password",
"userAgent": "a short name to identify your application"
}));
When successful, the loginResponse message contains all the same important information as the connectionResponse, including your valid ghostId.
Sending commands
The client must wait for the connectionResponse message from the server, before sending any further messages.
All commands can optionally use the reqId key to associate requests with responses. In addition, each response message will always contain the keys errorCode, and message.
- All get<Type> and remove<Type> commands require the request object to contain a key of the type, with the value of a JSON object with the correct id.
- All merge<Type> commands require the request object to contain a key of the type, with the value of a JSON object with the correct id, and the correct v value.
- All messages sent to and from the server are strings with following format:
Request format
cmdName<space>{JSON}
Request example
getCompany {
"reqId": 1,
"company": {
"id": 42
}
} Response format
cmdNameResponse<space>{JSON}
Response example
getCompanyResponse {
"reqId": 1,
"errorCode": 0,
"message": "Company retrieved",
"company": Company
} Using JavaScript, sending a command is as simple as:
socket.send("getCompany " + JSON.stringify({ "reqId": 1, "company": { "id": 42 } }));
For a list of all supported commands, please see the command reference.
Synchronization messages
The client can receive a constant feed from the server by subscribing to any of the SubscriptionTypes for a particular company. These subscriptions are per-company, not global to all companies.
There are two types of synchronization messages sent from the server:
Merged messages
Sent when an object is changed by you, another user, a behaviour script, or by some other system.
Format
<type>Merged {JSON} Deleted messages
Sent when an object is deleted by you, another user, a behaviour script, or by some other system.
Format
<type>Deleted { "id": number, "company": number } To subscribe to specific synchronization message types, send a subscribe command. For example:
Request
subscribe {
"reqId": 2,
"company": {
"id": 42
},
"subscriptionTypes": [
"assetGeneral",
"assetAdvanced"
]
} Response
After you receive your subscribeResponse, you begin to receive synchronization messages for those subscriptions.
assetDeleted { "id": 123456, "company": 42 } assetGeneralMerged { /* AssetGeneral */ } assetAdvancedMerged { /* AssetAdvanced */ } For a list of all supported subscription types, please see the subscription reference.
You can also use the v property of all synchronized objects to see if the version you've received from the server is more recent than the version you have in your cache. In the case of complex objects like assets, providers, and users, the general version flag is always the first number in the v array, and the advanced is always the second. Companies follow the order: general, billing, directory, labels and tags, then policies.