See Hipmob in action on iOS with Wanderplayer and Android with Wanderplayer
Sign Up Here
Hipmob Server API
Overview
Hipmob provides hosted live chat for mobile applications. You sign up with us, we give you a code, you download our library, you integrate it into your app, and you can then talk to your users, figure out what they want and what problems they are having, and make them happy. No servers, no extra steps or code to write, wherever the users are, you get to focus on what you do well. Hipmob provides a server API to allow admins to manage their applications' settings and obtain device information. This is the documentation for version 1 of the Hipmob API.
Changes
Hipmob reserves the right to extend the API (by adding fields to responses, or adding new endpoints) without advance notice. Major content or structural changes (such as removing endpoints, removing fields or altering the structure of API responses) will only occur when new API versions are released: we will continue to support the previous API version for a minimum of 3 months.
Security
All API communication occurs over SSL: the API will send a redirect if it receives a request over HTTP.
Authentication
API Key
Authorization against the API is performed using HTTP basic authentication: it requires an account name and an API key. To obtain your API key log into your account and from the dropdown select the Account page.
Figure 1: the Account page
The 4th section on the page will display your API key. You will use this with your username to validate all requests made to the API.
Figure 2: the API key
Authentication Errors
If no HTTP basic authentication headers are provided then a
401 Authentication Required response will be returned. If an unknown account name or incorrect API key are provided in the HTTP basic authentication headers then a 401 Unauthorized response will be returned. The responses and errors described below require successful authorization.Communication Details
Headers
The Hipmob API returns specific
Content-Type headers for various responses: generally these headers include both format information AND version numbers. An example is application/vnd.com.hipmob.App-list+json; version=1.0, which is returned in response to a GET request to the Application endpoint. This header indicates that the response is formatted as a version 1.0 com.hipmob.App-list JSON document. The endpoint documentation below describes all the supported formats in detail.
Requests
The Hipmob server API uses standard HTTP requests and follows REST principles: GET requests are used to retrieve information, POST requests to create new entries (with required data passed in request parameters), PUT requests to replace existing entries and DELETE requests to remove them. All parameters are passed in using the
Content-Type header set to either application/x-www-form-urlencoded or multipart/form-data: the individual endpoint sections below describe the required Content-Type header values.
Responses
All responses from the API are either plain text (with the
Content-Type response header set to text/plain) or application specific JSON (with an appropriately set Content-Type response header value). Response formats are specific to this version of the API: the Content-Type header values will include version information as shown in the Headers section above. Success/errors are also returned using standard HTTP status code values: 200 or 300 range values when an operation successfully completes and 400 or 500 range values when an error occurs. The HTTP reason phrase is used to provide additional meaning: to provide support for environments where the reason phrase is not easily available in the default HTTP client implementation (such as NodeJS) the reason is also provided using the X-Hipmob-Reason response header. The individual endpoint sections below describe the specific responses in greater detail.
Application
List Applications
Description
Lists all the applications associated with the authenticated Hipmob account.
URL Structure
https://api.hipmob.com/apps
Request Method
GET
Since
1.0
Response Content-Type
application/vnd.com.hipmob.App-list+json; version=1.0
Returns
A list of the applications associated with the authenticated Hipmob account.
Example Response
{"count": 2, "values":[{"id":"fedcba0987654321fedcba0987654321","name":"Hipmob Testing","url":"hipmobtest.com","created":"2012-06-26T18:06:27.893Z","modified":"2012-07-31T18:39:07.476Z"},{"id":"1234567890abcdef1234567890abcdef","name":"Testing 3","url":"https://manage.hipmob.com/","created":"2012-07-31T06:41:26.985Z","modified":"2012-07-31T06:41:26.985Z"}]}Field Values
| Field | Type | Description |
|---|---|---|
| count | int | The number of apps associated with the authenticated Hipmob account. |
| values | array | The available information about each app associated with the authenticated Hipmob account. Each entry in the array is a JSON object identical to that returned by the Get Application Details endpoint. |
Errors
402
The request failed despite valid authentication.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
$apps = $hipmob->get_applications();
print_r($apps);
# install Hipmob using "pip install hipmob", then set the required environment variables import sys, os, hipmob if 'hipmob_username' not in os.environ: print "Please provide the username as an environment variable."; sys.exit() if 'hipmob_apikey' not in os.environ: print "Please provide the API key as an environment variable."; sys.exit() if 'hipmob_app' not in os.environ: print "Please provide the application mobile key as an environment variable."; sys.exit() hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']); res = hipmob.get_applications() if res == None: print "No applications were found." else: for x in res: print x
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
handle.get_applications(function(err, apps){
if(apps && 'length' in apps){
var i, len = apps.length;
console.log(len + " apps were found.");
for(i=0;i<len;i++){
console.log((i+1)+": "+apps[i]);
}
}else{
console.log('No apps were available.');
}
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Get Application Details
Description
Returns the application details for a specific application associated with the authenticated Hipmob account. The API identifies the requested application by its internal Hipmob ID, which is identical to the application's mobile key.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}Request Method
GET
Since
1.0
Response Content-Type
application/vnd.com.hipmob.App+json; version=1.0
Returns
The application details for the specified application associated with the authenticated Hipmob account.
Example Request URL
https://api.hipmob.com/apps/fedcba0987654321fedcba0987654321
Example Response
{"id":"fedcba0987654321fedcba0987654321","name":"Hipmob Testing","url":"hipmobtest.com","created":"2012-06-26T18:06:27.893Z","modified":"2012-07-31T18:39:07.476Z"}Field Values
| Field | Type | Description |
|---|---|---|
| id | string | The mobile key for this app. |
| name | string | The application's name. |
| url | string | The application's URL as specified when the app was created. |
| created | string | The UTC timestamp (in ISO8601 format) when the application was created. |
| modified | string | The UTC timestamp (in ISO8601 format) when the application was last modified. May not be available if the application has never been modified. |
Errors
400
No application was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
$app = $hipmob->get_application($_SERVER['hipmob_app']);
print_r($app);
# install Hipmob using "pip install hipmob", then set the required environment variables import sys, os, hipmob if 'hipmob_username' not in os.environ: print "Please provide the username as an environment variable."; sys.exit() if 'hipmob_apikey' not in os.environ: print "Please provide the API key as an environment variable."; sys.exit() if 'hipmob_app' not in os.environ: print "Please provide the application mobile key as an environment variable."; sys.exit() hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']); res = hipmob.get_application(os.environ['hipmob_app']) if res == None: print "No application was found for ["+os.environ['hipmob_app']+"]" else: print res
// install Hipmob using 'npm install hipmob', then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var callback = function(err, app){ console.log('--->['+app+']'); };
handle.get_application(process.env.hipmob_app, callback);
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Device
Check if Device Exists
Description
Checks to see if the device running the specified application and using the specified host application identifier has connected to the Hipmob communication network.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}Request Method
HEAD
Since
1.0
Returns
200
A device running the specified application and using the specified host application identifier has connected to the Hipmob communication network.
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
Example Code
PHP code sample coming soon!
# install Hipmob using "pip install hipmob", then set the required environment variables import sys, os, hipmob if 'hipmob_username' not in os.environ: print "Please provide the username as an environment variable."; sys.exit() if 'hipmob_apikey' not in os.environ: print "Please provide the API key as an environment variable."; sys.exit() if 'hipmob_app' not in os.environ: print "Please provide the application mobile key as an environment variable."; sys.exit() hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']); try: res = hipmob.get_device(os.environ['hipmob_app'], '123', verify=True) print res except ValueError, e: print "There is no device for app "+os.environ['hipmob_app']+" with id '123'"
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
// this just quickly retrieves a handle to a device without checking if it exists
var dev = handle.get_device(process.env.hipmob_app, '123', false);
// this will verify: if a device does not exist, you'll get a [Error: Device not found]
// if it exists, you'll get the string representation of the device
handle.get_device(process.env.hipmob_app, '123', true, function(err, dev){
if(!err){
console.log(dev);
}else{
console.log(err);
}
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Check Device Status
Description
Checks to see if the device running the specified application and using the specified host application identifier is currently online.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/statusRequest Method
GET
Since
1.2
Response Content-Type
application/vnd.com.hipmob.Device.status+json; version=1.0
Returns
true if the device running the specified application and using the specified host application identifier is currently online, false otherwise..Example Request URL
https://api.hipmob.com/apps/fedcba0987654321fedcba0987654321/devices/AACA914E-B948-4d5f-BF8B-0BDB5CF77B61/status
Example Response
{"online": true}
Field Values
| Field | Type | Description |
|---|---|---|
| online | boolean | true if the device is online, false otherwise. |
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
Notes
The Hipmob API will return an online status of
false for devices that have not yet connected to the Hipmob communication network.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
if($device->check_device_status()) echo "Device Online? yes";
else echo "Device Online? no";
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
print "Device Online? "+str(res.check_device_status())
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
dev.check_device_status(function(err, status){
if(!err){ console.log("Device Online? "+status); }else{ console.log(err); }
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Get Device Details
Description
Retrieves the details saved for the device running the specified application and using the specified host application identifier that has connected to the Hipmob communication network.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}Request Method
GET
Since
1.0
Response Content-Type
application/vnd.com.hipmob.Device+json; version=1.0
Returns
The device details for the device running the specified application with the specified host application identifier.
Example Request URL
https://api.hipmob.com/apps/fedcba0987654321fedcba0987654321/devices/AACA914E-B948-4d5f-BF8B-0BDB5CF77B61
Example Response
{"id":"AACA914E-B948-4d5f-BF8B-0BDB5CF77B61","platform":"android","version":"8","created":"2012-07-29T18:44:44.300Z","modified":"2012-07-29T23:43:49.952Z","userdata":{"locale":"US","lastcontext":"On the Carrier","name":"Jack Hawksmoor","email":"jack.hawksmoor@theauthority.com"}}Field Values
| Field | Type | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| id | string | The host application identifier for this device. | ||||||||||||||
| platform | string | The device's platform. This will currently be either android or iOS. |
||||||||||||||
| version | string | The device's platform version string. | ||||||||||||||
| created | string | The UTC timestamp (in ISO8601 format) when the device first connected to the Hipmob communication network. | ||||||||||||||
| modified | string | The UTC timestamp (in ISO8601 format) when the device most recently connected to the Hipmob communication network. May not be available if the device only connected once. | ||||||||||||||
| userdata | object | The user data provided by the application: all fields are strings. The following fields may be available.
|
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid);
print_r($device);
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
res.load()
print res
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
dev.load(function(err, devres){
if(!err){ console.log(devres+": ["+devres.created()+"]"); }else{ console.log(err); }
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Get Device Message Count
Description
Retrieves the number of undelivered messages that have been sent to the device running the specified application and using the specified host application identifier.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/messagecountRequest Method
GET
Since
1.0
Response Content-Type
application/vnd.com.hipmob.Device.pendingmessagecount+json; version=1.0
Returns
The number of undelivered messages that have been sent to the device running the specified application and using the specified host application identifier.
Example Request URL
https://api.hipmob.com/apps/fedcba0987654321fedcba0987654321/devices/AACA914E-B948-4d5f-BF8B-0BDB5CF77B61/messagecount
Example Response
{"count": 0}
Field Values
| Field | Type | Description |
|---|---|---|
| count | int | The number of available messages. |
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
Notes
The Hipmob API handles queueing messages for devices that have not yet connected to the Hipmob communication network: the messages are preserved until the device actually connects.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->available_message_count());
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
print "Available messages: "+str(res.get_available_message_count())
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
dev.available_message_count(function(err, count){
if(!err){ console.log("Available messages: "+count); }else{ console.log(err); }
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Send Text Message
Description
Sends a text message to the specified device.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/messagesRequest Method
POST
Since
1.1
Request Content-Type
application/x-www-form-urlencoded
Parameters
| Name | Required | Quantity | Description |
|---|---|---|---|
| text | Yes | Exactly 1 | The text of the message to be sent. |
| autocreate | No | Exactly 1 | The text true if the message should be sent regardless of whether or not the target host application identifier has been seen yet. |
Returns
200
Message sent.
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
Invalid message specified.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
Notes
The Hipmob API handles queueing messages for devices that have not yet connected to the Hipmob communication network: the messages are preserved until the device actually connects. To ensure mistakes aren't made when specifying the target host identifier, the autocreate request parameter must be provided if the target host identifier may not have been in contact with the Hipmob communication network yet. If this parameter is not provided and the device has not been seen a 404 error will be returned, otherwise the message will be queued and delivered whenever the device connects.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->send_text_message("Hi Jack: the Carrier is now back in action!"));
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
print "Sending message: "+str(res.send_text_message("This is from Python!"))+"."
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
// will not call back: do this if you don't care if the call succeeds or not
dev.send_text_message("Message 1.");
// do this to receive a notification when the call completes
dev.send_text_message("Message 2.", function(err){
if(!err){ console.log("Message sent."); }else{ console.log(err); }
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Send Picture Message
Description
Sends a picture message to the specified device.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/messagesRequest Method
POST
Since
1.1
Request Content-Type
image/png, image/jpeg, image/gif
Request Headers
| Name | Required | Quantity | Description |
|---|---|---|---|
| Content-Length | Yes | Exactly Once | The size of the picture to be sent, in bytes. |
| X-Hipmob-Autocreate | No | At most once | The text true if the message should be sent regardless of whether or not the target host application identifier has been seen yet. |
Post Body
The binary data (NOT base64-encoded) of the picture to send.
Returns
200
Message sent.
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
No content length specified.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
415
Content-type not supported on that device.
Notes
The Hipmob API handles queueing messages for devices that have not yet connected to the Hipmob communication network: the messages are preserved until the device actually connects. To ensure mistakes aren't made when specifying the target host identifier, the X-Hipmob-Autocreate request header must be provided if the target host identifier may not have been in contact with the Hipmob communication network yet. If this header is not provided and the device has not been seen a 404 error will be returned, otherwise the message will be queued and delivered whenever the device connects.
Depending on the device's configuration the device may not provide support for picture messaging: if that information is available the API will reject the request with a
Depending on the device's configuration the device may not provide support for picture messaging: if that information is available the API will reject the request with a
415 error.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
// set this to the path of the PNG, GIF or JPEG image to be sent
$picture = "{picture file path}";
// specify the image mime type: acceptable values are image/jpeg,
// image/gif and image/png
$picture_mime_type = "image/jpeg";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->send_picture_message($picture, $picture_mime_type));
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
# set this to the path of the PNG, GIF or JPEG image to be sent
picture = "{picture file path}";
# specify the image mime type: acceptable values are image/jpeg,
# image/gif and image/png
picture_mime_type = "image/jpeg";
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
print "Sending message: "+str(res.send_picture_message(picture, picture_mime_type))+"."
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
// set this to the name of the file to send
var image = "/home/me/funnypicture.png";
// you can pass it either a file or a Buffer: it can not be a stream because we must know
// the Content-Length to successfully send the file.
dev.send_picture_message(image, "image/png", function(err){
if(!err){ console.log("Message sent."); }else{ console.log(err); }
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Send Audio Message
Description
Sends an audio message to the specified device.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/messagesRequest Method
POST
Since
1.1
Request Content-Type
audio/mp3
Request Headers
| Name | Required | Quantity | Description |
|---|---|---|---|
| Content-Length | Yes | Exactly Once | The size of the audio file to be sent, in bytes. |
| X-Hipmob-Autocreate | No | At most once | The text true if the message should be sent regardless of whether or not the target host application identifier has been seen yet. |
Post Body
The binary data (NOT base64-encoded) of the audio file to send.
Returns
200
Message sent.
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
No content length specified.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
415
Content-type not supported on that device.
Notes
The Hipmob API handles queueing messages for devices that have not yet connected to the Hipmob communication network: the messages are preserved until the device actually connects. To ensure mistakes aren't made when specifying the target host identifier, the X-Hipmob-Autocreate request header must be provided if the target host identifier may not have been in contact with the Hipmob communication network yet. If this header is not provided and the device has not been seen a 404 error will be returned, otherwise the message will be queued and delivered whenever the device connects.
Depending on the device's configuration the device may not provide support for picture messaging: if that information is available the API will reject the request with a
Depending on the device's configuration the device may not provide support for picture messaging: if that information is available the API will reject the request with a
415 error.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
// set this to the path of the MP3 audio file to be sent
$audio = "{audio file path}";
// specify the audio mime type: the only acceptable value is audio/mp3
$audio_mime_type = "audio/mp3";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->send_audio_message($audio, $audio_mime_type));
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
# set this to the path of the MP3 audio file to be sent
audio = "{audio file path}";
# specify the audio mime type: the only acceptable value is audio/mp3
audio_mime_type = "audio/mp3";
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
print "Sending message: "+str(res.send_audio_message(audio, audio_mime_type))+"."
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
// set this to the name of the file to send
var voicemail = "/home/me/voicemail.mp3";
// you can pass it either a file or a Buffer: it can not be a stream because we must know
// the Content-Length to successfully send the file.
dev.send_audio_message(voicemail, "audio/mp3", function(err){
if(!err){ console.log("Message sent."); }else{ console.log(err); }
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Send JSON Message
Description
Sends a JSON message to the specified device. This can be used to communicate structured data to the device.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/messagesRequest Method
POST
Since
1.2
Request Content-Type
application/json
Request Headers
| Name | Required | Quantity | Description |
|---|---|---|---|
| Content-Length | No | Exactly Once | The size of the JSON data to be sent, in bytes. |
| X-Hipmob-Autocreate | No | At most once | The text true if the message should be sent regardless of whether or not the target host application identifier has been seen yet. |
Post Body
The JSON data of the message to send.
Returns
200
Message sent.
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
Invalid message specified.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
Notes
The Hipmob API handles queueing messages for devices that have not yet connected to the Hipmob communication network: the messages are preserved until the device actually connects. To ensure mistakes aren't made when specifying the target host identifier, the autocreate request parameter must be provided if the target host identifier may not have been in contact with the Hipmob communication network yet. If this parameter is not provided and the device has not been seen a 404 error will be returned, otherwise the message will be queued and delivered whenever the device connects.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
$msg = array("property1" : 1, "property2": "value 2", "property3": array(1, 2, 3));
print_r($device->send_json_message($msg);
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
print "Sending message: "+str(res.send_json_message({ "property1": 1, "property2": "value 2", "property3": [1, 2, 3] }))+"."
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
// will not call back: do this if you don't care if the call succeeds or not
dev.send_text_message({ "property1": 1, "property2": "value 2", "property3": [1, 2, 3] });
// do this to receive a notification when the call completes
dev.send_text_message({ "property1": 1, "property2": "value 2", "property3": [1, 2, 3] }, function(err){
if(!err){ console.log("Message sent."); }else{ console.log(err); }
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Send Binary Message
Description
Sends a binary message to the specified device. This is best used for small amounts (< 16K) of binary data. The data will be base64-encoded and then sent.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/messagesRequest Method
POST
Since
1.2
Request Content-Type
application/octet-stream
Request Headers
| Name | Required | Quantity | Description |
|---|---|---|---|
| Content-Length | No | Exactly Once | The size of the JSON data to be sent, in bytes. |
| X-Hipmob-Autocreate | No | At most once | The text true if the message should be sent regardless of whether or not the target host application identifier has been seen yet. |
Post Body
The binary data (NOT base64-encoded) of the message to send.
Returns
200
Message sent.
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
Invalid message specified.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
Notes
The Hipmob API handles queueing messages for devices that have not yet connected to the Hipmob communication network: the messages are preserved until the device actually connects. To ensure mistakes aren't made when specifying the target host identifier, the autocreate request parameter must be provided if the target host identifier may not have been in contact with the Hipmob communication network yet. If this parameter is not provided and the device has not been seen a 404 error will be returned, otherwise the message will be queued and delivered whenever the device connects.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->send_binary_message(file_get_contents("{message file}")));
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
# pass any object that implements the read() method
msg = open("{message file}", "rb")
hipmob = hipmob.Hipmob(os.environ['hipmob_username'],
os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
print "Sending message: "+str(res.send_binary_message(msg))+"."
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username,
process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
// you can pass it a Buffer: it can be a stream
var fs = require('fs');
fs.readFile("{message file}", function(err, data){
if(!err){
dev.send_binary_message(data, function(err){
if(!err){
console.log("Message sent.");
}else{
console.log(err);
}
});
}
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Get Device Friends
Description
Retrieves the host application identifiers of all devices that are considered friends of the specified device: these are the devices that can send messages to this device, or receive messages from this device.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/friendsRequest Method
GET
Since
1.0
Response Content-Type
application/vnd.com.hipmob.DeviceFriends+json; version=1.0
Returns
A list of the host application identifiers of the friends of this device.
Example Request URL
https://api.hipmob.com/apps/fedcba0987654321fedcba0987654321/devices/AACA914E-B948-4d5f-BF8B-0BDB5CF77B61/friends
Example Response
{"index": 0, "pagesize": 2,"total": 2,"friends":["9d26cbc2-35d2-4b03-9a2d-3b4d8a64e611","5813cd68-402f-4836-8f9e-acf1aaaf937d"]}
Field Values
| Field | Type | Description |
|---|---|---|
| index | int | The position within the friend list of the first friend in this response. |
| pagesize | int | The number of results in this response. If the friend list is empty then this will be zero. |
| total | int | The number of friends in this list. It is a number always greater than or equal to the pagesize. If the friend list is empty then this will be zero. |
| friends | array[string] | The list of host application identifiers of the friends of this device. |
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
Notes
The Hipmob API manages friend lists for devices that have not yet connected to the Hipmob communication network: if you request the friend list for a device that has never connected and has never had friends added via the API then you will receive a response with the
total field set to zero.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->list_friends());
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
resp = res.list_friends()
if len(resp) == 0:
print "Device friends: No friends were found."
else:
print "Device friends:"
for x in resp:
print x
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
// get the friend list
dev.list_friends(function(err, friends){
if(!err){
if(friends && 'length' in friends){
var i, len = friends.length;
console.log(len + " friends were found.");
for(i=0;i<len;i++){
console.log((i+1)+": "+friends[i]);
}
friendlist = friends;
}else{
console.log(dev+" has no friends :-(.");
}
}else{
console.log(err);
}
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Add Device Friends
Description
Adds friends to the friends list of a specific device: these friends will now be able to send messages to this device, or receive messages from this device.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/friendsRequest Method
POST
Since
1.0
Request Content-Type
application/x-www-form-urlencoded
Parameters
| Name | Required | Quantity | Description |
|---|---|---|---|
| friend | Yes | 1 or more | The host application identifiers of the friends to add. Accepts 1 or more values. |
Returns
200
Friend list updated (
(
{count} friends added).({count} will be the number of friends added).
200
No changes made.
(if all the specified friends were already in the friend list).
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
No friends were specified in the request parameters.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
Notes
The Hipmob API will add friends that have not yet connected to the Hipmob communication network: if you specify a device that has never connected the information will be stored and available whenever the device actually connects.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
// this will be the friend we'll add to the list
$frienddeviceid = "{friend's device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->add_friend($hipmob->get_device($_SERVER['hipmob_app'], $frienddeviceid, false)));
// alternatively, you can add multiple friends at once
$frienddeviceid2 = "{friend 2's device id}";
$frienddeviceid3 = "{friend 3's device id}";
print_r($device->add_friends(array($hipmob->get_device($_SERVER['hipmob_app'], $frienddeviceid2, false),
$hipmob->get_device($_SERVER['hipmob_app'], $frienddeviceid3, false))));
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
# this will be the friend we'll add to the list
frienddeviceid = "{friend's device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
# add a single friend
resp = res.add_friend(hm.get_device(os.environ['hipmob_app'], frienddeviceid))
print "Add friend: "+str(resp)
# and you can also add multiple friends: this will still only require a single network roundtrip
frienddeviceid2 = "{friend 2's device id}";
frienddeviceid3 = "{friend 3's device id}";
resp = res.add_friends([hm.get_device(os.environ['hipmob_app'], frienddeviceid2),
hm.get_device(os.environ['hipmob_app'], frienddeviceid3)])
print "Add friends: "+str(resp)
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var app = process.env.hipmob_app;
var dev = handle.get_device(app, deviceid, false);
// add a single friend
var friend = handle.get_device(app, "4322A04D-D292-4b76-8158-781F77FCE7DB", false);
dev.add_friend(friend, function(err, count){
if(err) console.log(err)
else if(count > 0) console.log(friend + " added.");
else console.log("No changes made (friend must already be in friend list).");
});
// you can also add multiple friends: this will still only require a single network roundtrip
var friend1 = handle.get_device(app, "89A84E7A-1F2B-4d80-8F4F-C4A9DDBB486D", false);
var friend2 = handle.get_device(app, "8D5F7113-78C8-45c8-8BF4-95DC95759017", false);
dev.add_friends([friend1, friend2], function(err, count){
if(err) console.log(err)
else console.log("Added " + count + " friends.");
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Remove Device Friend
Description
Removes a specific friend from the friend list of the specified device: this friend will no longer be able to send messages to this device, or receive messages from this device.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/friends/{friend host application identifier}Request Method
DELETE
Since
1.0
Returns
200
Friend removed.
(if the friend was found and was successfully removed).
200
No friends removed.
(if the friend was not found in the friends list).
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
No friend host application identifier was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
// this will be the friend we'll add to the list
$frienddeviceid = "{friend's device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->remove_friend($hipmob->get_device($_SERVER['hipmob_app'], $frienddeviceid, false)));
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
# this will be the friend we'll remove from the list
frienddeviceid = "{friend's device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
# this will remove a single friend
resp = res.remove_friend(hm.get_device(os.environ['hipmob_app'], frienddeviceid))
print "Removing friend: "+str(resp)
# and for convenience, you can pass an array
# the library will handle the repeated calls (note that there will be one API call for
# each friend removed, so for bulk changes it may make more sense to call remove_all_friends
# and then follow that wil a call to set_friends
frienddeviceid2 = "{friend 2's device id}";
frienddeviceid3 = "{friend 3's device id}";
resp = res.remove_friends([hm.get_device(os.environ['hipmob_app'], frienddeviceid2),
hm.get_device(os.environ['hipmob_app'], frienddeviceid3)])
print "Removing friends: "+str(resp)
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var app = process.env.hipmob_app;
var dev = handle.get_device(app, deviceid, false);
// this will remove a single friend
var friend = handle.get_device(app, "8D5F7113-78C8-45c8-8BF4-95DC95759017", false);
dev.remove_friend(friend, function(err, count){
if(err) console.log(err)
else if(count == 1) console.log("Removed "+friend);
else console.log("No changes made.");
});
// and for convenience, you can pass an array
// the library will handle the repeated calls (note that there will be one API call for
// each friend removed, so for bulk changes it may make more sense to call remove_all_friends
// and then follow that wil a call to set_friends
var friend1 = handle.get_device(app, "89A84E7A-1F2B-4d80-8F4F-C4A9DDBB486D", false);
var friend2 = handle.get_device(app, "4322A04D-D292-4b76-8158-781F77FCE7DB", false);
dev.remove_friends([friend1, friend2], function(err, count){
if(err) console.log(err)
else console.log("Removed "+count+" friends.");
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Remove Device Friends
Description
Clears the friend list of the specified device: the device will no longer be able to send messages to any other devices, or receive messages from any other devices.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/friendsRequest Method
DELETE
Since
1.0
Returns
200
Friend list cleared (
(
{count} friends removed).({count} will be the number of friends removed).
200
No changes made.
(if the friend list was empty).
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
No friend host application identifier was specified in the URL.
402
The request failed despite valid authentication.
404
The specified application could not be found.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->remove_all_friends());
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
resp = res.remove_all_friends()
print "Removing all friends: "+str(resp)
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var dev = handle.get_device(process.env.hipmob_app, deviceid, false);
// remove all the device's friends
dev.remove_all_friends(function(err, count){
if(err) console.log(err)
else console.log("Removed "+count+" friends.");
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Set Device Friends
Description
Clears the friends list, and then adds the specified friends to the friends list of a specific device. Equivalent to calling Remove All Device Friends followed by Add Device Friends.
URL Structure
https://api.hipmob.com/apps/
{app mobile key}/devices/{host application identifier}/friendsRequest Method
PUT
Since
1.0
Request Content-Type
application/x-www-form-urlencoded
Parameters
| Name | Required | Quantity | Description |
|---|---|---|---|
| friend | Yes | 1 or more | The host application identifiers of the friends to add. Accepts 1 or more values. |
Returns
200
Friend list updated (
(
{count} friends added).({count} will be the number of friends added).
Errors
400
No application was specified in the URL.
400
No host application identifier was specified in the URL.
400
No friends were specified in the request parameters.
402
The request failed despite valid authentication.
404
The specified application could not be found.
404
No device with the specified host application identifier could be found.
Notes
The Hipmob API will add friends that have not yet connected to the Hipmob communication network: if you specify a device that has never connected the information will be stored and available whenever the device actually connects.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_app'])){
echo "Please provide the application mobile key as an environment variable.\r\n";
return;
}
// update this variable to be the host application identifier you're interested in
$deviceid = "{specific device id}";
// these will be the new set of friends we should use
$frienddeviceid1 = "{friend 1's device id}";
$frienddeviceid2 = "{friend 2's device id}";
$frienddeviceid3 = "{friend 3's device id}";
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
// passing false for the third parameter prevents the library from hitting the server
// to verify that the device exists: if you're certain the device exists then this
// is more efficient
$device = $hipmob->get_device($_SERVER['hipmob_app'], $deviceid, false);
print_r($device->set_friends(array($hipmob->get_device($_SERVER['hipmob_app'], $frienddeviceid1, false),
$hipmob->get_device($_SERVER['hipmob_app'], $frienddeviceid2, false),
$hipmob->get_device($_SERVER['hipmob_app'], $frienddeviceid3, false))));
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
if 'hipmob_app' not in os.environ:
print "Please provide the application mobile key as an environment variable.";
sys.exit()
# update this variable to be the host application identifier you're interested in
deviceid = "{specific device id}"
# these will be the friends we'll set
frienddeviceid = "{friend's device id}"
frienddeviceid2 = "{friend 2's device id}";
frienddeviceid3 = "{friend 3's device id}";
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_device(os.environ['hipmob_app'], deviceid)
resp = res.set_friends([hm.get_device(os.environ['hipmob_app'], frienddeviceid),
hm.get_device(os.environ['hipmob_app'], frienddeviceid2),
hm.get_device(os.environ['hipmob_app'], frienddeviceid3)])
print "Set friends: "+str(resp)
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
if(!('hipmob_app' in process.env)){
console.log("Please provide the application mobile key as an environment variable.");
return;
}
// update this variable to be the host application identifier you're interested in
var deviceid = "{specific device id}";
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var app = process.env.hipmob_app;
var dev = handle.get_device(app, deviceid, false);
// create a list of friends, and set it with a single call
var friendlist = [];
friendlist.push(handle.get_device(app, "5813cd68-402f-4836-8f9e-acf1aaaf937d", false));
friendlist.push(handle.get_device(app, "9177CBAF-81C0-4b73-9C2F-F04481D32F98", false));
friendlist.push(handle.get_device(app, "23275FF9-8511-42a3-A981-F438BEBDB5AB", false));
friendlist.push(handle.get_device(app, "97E27C77-C050-4990-A915-100AEBE856B4d", false));
dev.set_friends(friendlist, function(err, count){
if(err) console.log(err)
else console.log("Set " + count + " friends.");
});
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
User
Get User Details
Description
Returns the details for a specific user. The API identifies the user by its internal Hipmob username.
URL Structure
https://api.hipmob.com/user/
{username}Request Method
GET
Since
1.3
Response Content-Type
application/vnd.com.hipmob.User+json; version=1.0
Returns
The user's details for the specified username.
Example Request URL
https://api.hipmob.com/user/femi
Example Response
{"username":"femi", "first_name":"Femi", "last_name":"Omojola", "status": "online" }
Field Values
| Field | Type | Description |
|---|---|---|
| username | string | The username for the selected user. |
| first_name | string | The selected user's first name. |
| last_name | string | The selected user's last name. |
| status | string | The user's current availability status. Currently this is one of the following 4 values: online, offline, hours, usestatus. |
Errors
400
No user was specified in the URL.
402
The request failed despite valid authentication.
404
The specified user could not be found.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
$user = $hipmob->get_user($_SERVER['hipmob_username']);
print_r($user);
# install Hipmob using "pip install hipmob", then set the required environment variables import sys, os, hipmob if 'hipmob_username' not in os.environ: print "Please provide the username as an environment variable."; sys.exit() if 'hipmob_apikey' not in os.environ: print "Please provide the API key as an environment variable."; sys.exit() hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']); res = hipmob.get_user(os.environ['hipmob_username']) if res == None: print "No user information was found for ["+os.environ['hipmob_username']+"]" else: print res
// install Hipmob using 'npm install hipmob', then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var callback = function(err, user){ console.log('--->['+user+']'); };
handle.get_user(process.env.hipmob_username, callback);
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
Set User Status
Description
Sets the availability status of the authenticated user.
URL Structure
https://api.hipmob.com/user/
{username}/statusRequest Method
POST
Since
1.3
Request Content-Type
application/x-www-form-urlencoded
Parameters
| Name | Required | Quantity | Description |
|---|---|---|---|
| status | Yes | Exactly 1 | The user's new availability status. Currently this is one of the following 4 values: online, offline, hours, usestatus. |
Returns
200
[
username] status updated to "new status"Errors
400
No user was specified in the URL.
400
No status was specified in the request body.
400
Invalid status was specified.
401
You can only change your own status.
402
The request failed despite valid authentication.
Example Code
// copy the lib folder from the PHP library into the current directory, then set the required
// environment variables
if(!isset($_SERVER['hipmob_username'])){
echo "Please provide the username as an environment variable.\r\n";
return;
}
if(!isset($_SERVER['hipmob_apikey'])){
echo "Please provide the API key as an environment variable.\r\n";
return;
}
require_once(dirname(__FILE__) . 'lib/Hipmob.php');
$hipmob = new Hipmob($_SERVER['hipmob_username'], $_SERVER['hipmob_apikey']);
$user = $hipmob->get_user($_SERVER['hipmob_username']);
$user->set_status('online');
# install Hipmob using "pip install hipmob", then set the required environment variables
import sys, os, hipmob
if 'hipmob_username' not in os.environ:
print "Please provide the username as an environment variable.";
sys.exit()
if 'hipmob_apikey' not in os.environ:
print "Please provide the API key as an environment variable.";
sys.exit()
hipmob = hipmob.Hipmob(os.environ['hipmob_username'], os.environ['hipmob_apikey']);
res = hipmob.get_user(os.environ['hipmob_username'])
if res == None:
print "No user information was found for ["+os.environ['hipmob_username']+"]"
else:
res.set_status('online')
// install Hipmob using "npm install hipmob", then set the required environment variables
if(!('hipmob_username' in process.env)){
console.log("Please provide the username as an environment variable.");
return;
}
if(!('hipmob_apikey' in process.env)){
console.log("Please provide the API key as an environment variable.");
return;
}
var hipmob = require("hipmob");
var handle = hipmob(process.env.hipmob_username, process.env.hipmob_password);
var callback = function(err, user){ if(user) user.set_status('online'); };
handle.get_user(process.env.hipmob_username, callback);
Ruby code sample coming soon!
Java code sample coming soon!
C# code sample coming soon!
