Documentation

How to get going with Insto...

Getting Started

Signing up

To be able to do anything with Insto, you need to sign-up. Signing up will register you with Insto, creating an API key for you to use in your applications.

API keys are tied to the host that you supply, so make sure you enter the correct one!

Once you are signed up, you need to sign-in to see your dashboard. From here you will be able to see all of the API keys that are registered against your user. At the current time, only one API key is allowed per email address.

You will also be able to track how many people are connected to Insto via your application, as well as see how many messages you are sending per day. Message totals are updated once per day, and only include messages that your users receive.

Initial Setup

We currently have two Insto Javascript libraries available, one for in-browser web apps and one for Node.js developers looking to add realtime features to their Node.js apps. Getting started with both libraries is extremely simple!

HTML5 logo

Javascript library - for your web apps

Configuring your application to use Insto is really simple. Just add the Insto Javascript API shown below into the <head> section of your HTML.

<script type="text/javascript" src="https://api.insto.co.uk:3000/lib/client.js"></script>

This is the only file you need to include into your HTML in order to get going with Insto on the web.

Node.js logo

Node.js library - for your Node apps

Check out our Node.js repository over on Github, all the instructions you need are there. The documentation below is transferable to the Node.js module.

Connecting to Insto

Once all of the necessary libraries are loaded, you need to connect to the Insto server, luckily, this is also really simple.

// user data
var userData = {
  userType: "example"
}

// user query
var userQuery = {
  userType: "example"
}

//connect to insto
i = new InstoClient('API_KEY', userData, userQuery, {
	
  onConnect: function(data) { ... },
  onConnectedUsers: function(data) { ... },
  onNotification: function(data) { ... },
  onQuery: function(data) { ... },
  onUserConnect: function(data) { ... },
  onUserDisconnect: function(data) { ... }
	
});

Lets quickly run through what the above is doing...

userData

userData is a Javascript object that describes the connecting user. This object is a series of key/value pairs that consist of all of the properties required to be able to identify this user in the future. There is no schema associated with this object and can contain anything you wish, for example, this is also a valid userData object:

// user data
var userData = {
  id: 123,
  name: Matt,
  age: 23
}

userQuery

userQuery is again a Javascript object that describe the kind of Insto user the connecting user would like to receive information about. This information comes in the form of connect and disconnect notifications.

Again, there is no schema associated with this object and it can be created in an identical manner to the userData.

Callback options

There are a number of options available to help you deal with any incoming notifications, and they are accessible via the callback options parameter. These are all functions that accept one parameter which contains the notification data.

  • onConnect: this is fired when you connect to the server and contains your unique ID
  • onConnectedUsers: this contains all of the other connected users that match your userQuery
  • onNotification: fired whenever a notification is received from another connected user
  • onQuery: contains the results of a query API call
  • onUserConnect: fired whenever a new user connects, and contains their userData
  • onUserDisconnect: fired whenever a new user disconnects, and contains their userData

Websocket API

The Websocket API is used to send and receive notifications between connected clients in realtime.

Notifications

Notifications can be sent and received by any connected InstoClient, and when they are received they are passed to the appropriate callback function for the developer to handle as required.

There are six types of notification, with the related callback shown below.

onConnect

Fired when an InstoClient has successfully connected to the Insto server

{
  _id: "kjghdfgosdkfj-65"
}

onConnectedUsers

Fired after connection if any currently connected Insto clients match the supplied userQuery. Provides an array of matching clients userData objects.

{
  users: [
    {
      _id: "hhgjjudnySDF-34",
      name: "John Smith",
      department: "sales"
    },
    {
      _id: "jhdfsSDFsh-34",
      name: "Fiona Clarke",
      department: "finance"
    } 
  ]
}

onNotification

Fired every time an InstoClient receives a notification from another InstoClient, either via a broadcast message or matching a userQuery on a direct message.

insto.send({department: "sales"}, { foo: "Bar" }); // send notification to all users in the sales department

{
  _id: "ksjhdfjkksdf-45", //the unique ID of the sender
  foo: "bar"
}

insto.broadcast({ hello: "World" }); //send notification to ALL connected users

{
  _id: "ksjhdfjkksdf-45", //the unique ID of the sender
  hello: "World"
}

onUserConnect

Fired when another Insto client connects to the server and matches the supplied userQuery. Provides this clients userData object.

{
  _id: "hhgjjudnySDF-34",
  name: "John Smith",
  department: "sales"
}

onUserDisconnect

Fired when another Insto client disconnects from the server and matches the supplied userQuery. Provides this clients userData object.

{
  _id: "hhgjjudnySDF-34",
  name: "John Smith",
  department: "sales"
}

Query

Fired as a response from the query method (insto.query()). Provides an array of other connected users that match the supplied query.

insto.query({department: "sales"}); // find all connected users in the sales department

{
  users: [
    {
      _id: "hhgjjudnySDF-34",
      name: "John Smith",
      department: "sales"
    },
    {
      _id: "jhdfsSDFsh-34",
      name: "Fiona Clarke",
      department: "sales"
    } 
  ]
}

Methods

.send( userQuery, messageData, sendToSelf )

Use the .send() method to send a message via Insto.

userQuery

REQUIRED

Javascript object that describes the user who will receive the message.

messageData

REQUIRED

Javascript object that will be sent to the receiving users.

sendToSelf

DEFAULT: false
ACCEPTS: true, false

Determine if the sending user will also receive the message, if they match the supplied userQuery.

Example

The below example sends the messageData to all Insto users that have a 'name' property that equals 'Matt',, who will receive a notification of type 'notification'.

// user query
var userQuery = {
  name: "Matt"
}

// message
var messageData = {
  sendingUser: "Steven",
  message: "This is an example"
}

// send
i.send(userQuery, messagedata, false);

.broadcast( messageData )

Use the .broadcast() method to send a message to all connected clients.

messageData

REQUIRED

Javascript object that will be sent to the receiving users.

Example

The below example sends the messageData to all Insto users, who will receive a notification of type 'notification'.


// message
var messageData = {
  sendingUser: "Steven",
  message: "This is an example broadcast"
}

// send
i.broadcast(messagedata);

.query( userQuery )

Use the .query() method to find other connected users.

userQuery

REQUIRED

Javascript object that describes the users to be returned.

Example

The below example will find all other connected users with a name of 'Matt'. These users will be returned via a notification of type 'query'.

// user query
var userQuery = {
  name: "Matt"
}

// send
i.query(userQuery);

RESTful API

Send

The RESTful API allows messages to be sent to connected users that match a certain parameter, the URL structure is as shown:

https://api.insto.co.uk:3000/<API_KEY>/message/to/<PARAMETER>/<VALUE>?param1=value1&paramN=valueN

Responses are in JSON format, consisting of a success boolean parameter.

Example

https://api.insto.co.uk:3000/<API_KEY>/message/to/userId/1234?message=hi&sender=Matt

{
  success: true
}

Broadcast

The RESTful API allows messages to be sent to all connected users.

https://api.insto.co.uk:3000/<API_KEY>/message/all?param1=value1&paramN=valueN

Responses are in JSON format, consisting of a success boolean parameter.

Example

https://api.insto.co.uk:3000/<API_KEY>/message/all?message=hi&sender=Matt

{
  success: true
}

Query

The RESTful API allows users to search for connected users.

https://api.insto.co.uk:3000/<API_KEY>/query?param1=value1&paramN=valueN

Responses are in JSON format, consisting of a success boolean parameter and an array of matched users.

Example

https://api.insto.co.uk:3000/<API_KEY>/query?userType=chat

{
  "msg": [
    {
      "userType": "chat",
      "name": "Matt"
    },
    {
      "userType": "chat",
      "name": "Steven"
    },
    {
      "userType": "chat",
      "name": "Dave"
    }
  ],
  "success": true
}