The Hologram Socket API provides a low-level TCP socket interface for embedded devices to communicate with the Hologram Cloud.
The Hologram REST API offers much of the same functionality, but the Socket API is preferable in bandwidth-constrained environments.
Connect and Authenticate
Establish a TCP connection to the following host and port and send an API message followed by two newline characters. The API server will close connections after a few seconds of inactivity.
-
Host:
cloudsocket.hologram.io -
Port:
9999
Socket API credentials are associated with a Hologram device. From a device's dashboard page, generate or view the Cloud Services Router credentials underReceive from Device.
The credentials consist of a 8-byte device key.
Note: Use unique Device Credentials for each device.
Send a Message to the Hologram Cloud
Send a JSON message with the following fields. Field names have two forms: a full word for better readability, and an abbreviated key for minimizing data usage.
-
devicekey(k) – String. Eight-character Device Key used for authentication -
data(d) – String. Message payload -
tags(t) – String or array of strings. Topic or topics (formerly tags) to attach to the message. The server automatically adds the device's unique topic string (_DEVICE_XXXXX_), and potentially other system topics. Topics should be less than 32 characters and contain only alphanumeric characters, hyphens, underscores or slashes. No spaces.
Note: You may not mix and match full and abbreviated keys within a single JSON message. In other words, you must use either the full keywords or abbreviated keys for all fields in a JSON message.
On success, the server will return the text [0,0] and then close the connection. On error, the server will return a different message, or it may close the connection with no response.
Response codes
The server responds with an array of two numbers. The first describes any errors, and the second is currently always set to zero. The first digit maps to the following response codes:
-
0– Send successful, no error -
1– Connection was closed so we couldn't read enough -
2– Couldn't parse the message -
3– Auth section of message was invalid -
4– Payload type was invalid -
5– Protocol type was invalid -
6– An internal error occurred -
7– Metadata section of message was formatted incorrectly -
8– Topic contained invalid characters or was too long
For example, a response of [0,0] indicates success, and a response of [3,0] indicates invalid authentication.
Examples
Using the Unix netcat command, send "Hello, World!" authenticating as the device with device key ABCDWXYZ:
$ echo '{"k":"ABCDWXYZ","d":"Hello, World!","t":"TOPIC1"}' | nc -i1 cloudsocket.hologram.io 9999
[0,0] # Success response
Or, with full-word JSON keys and an array of topics:
$ echo {"devicekey":"ABCDWXYZ", "data":"Hello, World!", "tags":["TOPIC1", "TOPIC2"]} | nc -i1 cloudsocket.hologram.io 9999
[0,0] # Success response
Sending SMS-over-IP via the Hologram Cloud
Note: SMS-over-IP is no longer supported and requests will receive an error from the Hologram Cloud endpoint. For device-originated outbound SMS, customers may continue to use circuit switched SMS with Hologram IoT SIMs.
Send a string composed of the following fields:
- Procedure name – The letter S (capitalized)
- Device Key – Eight-character device key used for authentication
- Destination number – '+', country code, and telephone number, e.g. +13125551212
- Message – Text of the SMS message. Separated from the destination number with a space and terminated with a newline character. To insert a new line into the SMS message itself, insert the two characters \n and not an actual newline character.
The server will respond with a two-digit code and then close the connection. The first digit has the same semantics as the cloud messaging response codes above. For example, on success the server will return the text 00.
Note that the "From Number" on the SMS will be one of Hologram's cloud phone numbers unless you purchased a phone number for the device.
The server attaches the _SMSOVERIP_ topic to messages sent through this method.
Example
Using the Unix netcat command, send the SMS message "Hello, SMS!" to +1-312-555-1212. Authenticate as the device with device key ABCDWXYZ:
$ echo 'SABCDWXYZ+13125551212 Hello, SMS!' | nc -i1 cloudsocket.hologram.io 9999
00 # Success response
SMS Inbox API
Note: Sending SMS messages from your device on the Hologram network will incur fees at outbound SMS rates, which are typically more costly than data rates. Unless you require sending for integration purposes, you should probably use the TCP API, which is billed at standard data rates.
SMS-capable devices on Hologram's cellular network can send messages to the Cloud Services Router via standard circuit-switched SMS message to Hologram's SMS inbox. You don't need to specify API credentials, as Hologram can authenticate devices by their SIM cards. Send your data payload as an SMS to the following number:
- SMS Long Code: 310000202
Example SMS body
Hello, World!
Example resulting message in the Cloud Services Router
{
"body": "SGVsbG8sIFdvcmxkIQ==",
"status": "delivered",
"direction": "DO",
"received": "2016-09-22 01:02:44",
"destination": "310000202",
"type": "T",
"id": 262706444
}
- Hello, World! is the SMS body in standard SMS format
- SGVsbG8sIFdvcmxkIQ== is the Base64-encoded version of the Hello, World! SMS message body
- 2016-09-22 01:02:44 is the timestamp (in UTC) when the carrier received the SMS
- 262706444 is an identifier for the SMS message