Overview

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 under Receive 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

Send an SMS via the Hologram Cloud

Hologram’s SMS-over-IP feature offers a lower-cost alternative to sending SMS directly from cellular devices.

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 two newline characters

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 API

Note

This section describes sending messages to the Cloud Services Router via SMS. For sending SMS to Hologram- and non-hologram devices, see the Socket API's SMS-over-IP feature

Note

Sending SMS messages from your device on the Hologram network will incur fees at 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. 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