indoona Open Platform API

Regardless of the programming language chosen for your Application, you can connect it to the indoona Open Platform via our RESTful API. All requests are authenticated via OAuth2.

Setting up your app

First you have to set up an app, if you didn’t it yet, and configure it. At the end of this process, you will obtain OAuth2 credentials to be used with the API.

Making requests

API requests can be made through:

https://api.indoona.com/tp/

For your own safety, every request involving your App's client secret in the parameter list should be made in HTTPS.

Rate limits

Each application ID is limited to 10M API calls per day. If a client ID exceeds the rate limit for a given endpoint, the indoona API will return an HTTP 429 "Too Many Requests" response code.

Scopes

name description
basic get the user unique ID; add, modify and remove contacts
user_phone get the user’s phone number

Getting started

In this section you will learn the basic steps to connect your application with the indoona Open Platform using the API. For a comprehensive explanation of the API, have a look at the API Reference.

Obtaining an Application Token

Once your application is created, you can obtain an OAuth token (app token) to perform requests towards the indoona API on behalf of the app itself.
To do so, you have to invoke the tp/token API with the following parameters:

  • grant_type: its value must be set to "client_credentials";
  • client_id: your application id, as received on successful App creation;
  • client_secret: your application secret, as received on successful App creation.

Example:


POST https://api.indoona.com/tp/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=5439096a1c67819660e732c54xaYnu&client_secret=aDKwNXjC7lWOFH0p

Response

{
	"access_token"	:	"t5411c918c304d9a226cbbe1c128c8164e19fe94",
	"expires_in"	: 	36000,
	"token_type"	: 	"Bearer",
	"scope"			: 	"basic"
}

With the app-level token you can invoke all API that prescind from a particular connected user (cfr. App-level API), as well as any API involving a specific user, provided that the corresponding user_id is specified.

Connecting users

You can connect an indoona user with your Application via standard OAuth2 procedures: on a successful user connection, a short-term refreshable access token (user token) is delivered to your application to perform requests on behalf of the connected user.

First, your application must obtain an authorization code for a user requesting to connect, by directing her to the indoona authorization server with the following parameters:

  • response_type: must have "code" as value
  • client_id: your application id, as received on successful App creation
  • state: an opaque value you can use to maintain state between request and callback
  • scope: a space-separated list of the authorization items that will be requested to a user in the connection process; this must be a subset of the corresponding values defined on App creation

Example:


https://api.indoona.com/tp/authorize?client_id=5439096a1c67819660e732c54xaYnu&response_type=code
&state=xyz&scope=basic+user_phone

An alternate version of the authorization call is available, where the 'scope' parameter is replaced by the 'otp' one:


https://api.indoona.com/tp/authorize?client_id=5439096a1c67819660e732c54xaYnu&response_type=code
&state=xyz&otp=received_otp

Such parameter carries a one-time password delivered by an indoona mobile or web client on the (optional) url specified at App Creation stage to let users connect to your application from the official application directory.

See App Submission for further details on the Application Directory.

If the authorization process succeeds the user-agent is sent to the redirect_uri defined at App creation, with the following parameters:

  • code: an OAuth2 authorization code to obtain an access token for the connected user: the authorization code can be used only once before its expiration;
  • state: the same opaque value specified by the application in the request.

Now the application can obtain an access token for the connected user; the corresponding request must contain the following parameters:

  • grant_type: its value must be set to "authorization_code";
  • code: the authorization code received from the indoona authorization server;
  • redirect_uri: same parameter as specified at App creation stage;
  • client_id: your application id, as received on successful App creation;
  • client_secret: your application secret, as received on successful App creation.

Example:


POST https://api.indoona.com/tp/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=c7f10f95913d8782a7b958c31485ac6bfd54a983&client_id=5439096a1c67819660e732c54xaYnu&client_secret=aDKwNXjC7lWOFH0p&redirect_uri=http://appdomain/indoona/redirect

Response
{
	"access_token"	:	"f66907b18c304d9a226cbbe1c128c8164e19ff01",
	"expires_in"	: 	36000,
	"token_type"	: 	"Bearer",
	"scope"			: 	"basic user_phone",
	"refresh_token"	: 	"b256ba34db4d1dcbeb4080ecac7fde3eb4601caa",
	"user_id"		: 	"1i7qr9t0dxc0kiw8u4fmzx69f"
}

The obtained access_token must be included in any user-related API request by adding an "Authorization" header formatted as follows:


Authorization : token_type access_token

Among other data, the JSON response contains:

  • refresh_token: the OAuth2 token to renew the (possibly expired) user token;
  • user_id: a unique identifier for the connected user.

Note:
Semantically, performing a user-related API request specifying either a user token, or the app token together with the corresponding user_id, is equivalent; yet there are useful tips that it's worth considering: see our Guidelines to gain more insight into this matter.
In any case, please keep in mind that both kind of tokens will expire or may be invalidated, so be prepared to properly handle refresh procedures.

Managing the connection

In many cases, you will need to give users a way to manage their connection with your application. This may be about letting users tune their notification preferences or select contents you make available from your service, and so on.
To this purpose indoona Open Platform allows you to specify a management url in the developer dashboard, to be invoked from within the indoona mobile or web client. Typically you will make the same management url available from your website as well, provided that you properly handle different window sizes.

When the management url is called from a mobile or web client, it comes with two parameters:

  • otp: a one-time password associated to the requesting user, generated as from the previous paragraph;
  • fromapp: a boolean value that tells you whether the page was requested by an indoona mobile client, e.g. to decide about showing a button for disconnection (show the button when fromapp = 'false','0' or not given)

You should always validate a one time password received on the management url, to ensure that the requesting user is a valid one, possibly checking it against an existing web session.
Verification is carried out by invoking the following API, that returns the users's unique identifier:


POST https://api.indoona.com/tp/otp/verify.json
Content-Type: application/x-www-form-urlencoded

otp = received_otp

Response
{
	"user_id"	:	"ksd3847jkefkh3dsds9"
}

Since this API is called on behalf ot the app itself, it must be performed with the app-level token in the Authorization header.

Get user information

Your application can obtain information about a connected indoona user at any time according to the granted scopes, via the ‘me’ API:


GET /tp/me.json
Authorization: Bearer f66907b18c304d9a226cbbe1c128c8164e19ff01

Response
{
	"id"		:"7dsahi190x3ha2pprv1gztml3",
	"profile"	:	{
		"name"			:	"John",
		"surname" 		:	"Doe",
		"avatar_url"	:	"https://www.indoona.com/resource/johndoe.png"
	},
	"lang"		: "it",
	"msisdn"	:"+393709999720"
}

Bring your entities into indoona

An important point of strenght of the indoona Open Platform is the possibility to bring any kind of entities from your domain into indoona, mapping them onto contacts that connected users will find in their indoona address book.

You may add contacts acting on behalf of your Application (e.g. a customer care contact available to all users), or let each connected user decide what to import on the management web page you declared in your App's detail page.

When you bring a new contact into indoona, you must provide display name and (optional) avatar url for that contact: these data will typically match corresponding ones in your domain, if existing, but you can decide otherwise.

In addition, for each contact you can specify a set of capabilities:

  • group_add: the contact can be invited into indoona groups
  • interactive: the contact can process incoming messages (other than group notifications, that are always forwarded to your service)

Example:


POST tp/contact/add
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer f66907b18c304d9a226cbbe1c128c8164e19ff01

contact_id=unique_numeric_id&display_name=Smart+Lamp&avatar_url=https://appdomain/avatar/smartlamp.jpg&capabilities=group_add+share

Response
{
	"contact_id"	:	"unique_numeric_id",
	"display_name"	:	"Smart Lamp",
	"avatar_url" 	:	"https://appdomain/avatar/smartlamp.jpg",
	"capabilities" 	:	"group_add interactive"
}

The contact/add API can also be used to modify existing contacts, while the contact/remove API is used for contact removal (see API Reference).

N.B.: your Application is endowed by default with a supercontact, named after your application, that is allowed to send messages to any connected user.

Follow our Guidelines to learn about best practices in working with contacts.

Send your first message

After you added one or more contacts to a user’s indoona address book, you can start sending messages to that user on behalf of your contacts, using the message/send API.

You can send text messages, as well as stickers, locations, pictures, movies, audio notes and generic files (see API Reference for complete specifications). Common parameters to send messages of any type are:

  • contact_id : unique identifier of the sender contact;
  • resource_id: recipient resource identifier (user id or room id);
  • msg_type: message type, can be "text", "sticker", "location", etc..

Example:


POST /tp/message/send.json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer f66907b18c304d9a226cbbe1c128c8164e19ff01

resource_id=1i7qr9t0dxc0kiw8u4fmzx69f&contact_id=smart_lamp_id&msg_type=text&text=Hello+from+your+lamp!&no_push=true

Response:

{
	"id"		:	"21kj3h12oh3o",
	"type" 		:	"text",
	"timestamp" :	"1434613275796",
	"sender" 	:	"smart_lamp_id@yourdomain",
	"owner" 	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona",
	"recipient 	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona",
	"data" 		:	{
						"body"	:	"Hello from your lamp!"
					}
}

Receive messages

Besides sending messages, your App can also receive messages from indoona. In order to enable message reception you must declare a valid endpoint URL, as specified in App Creation.
A message is delivered to your endpoint over a POST request with Content-Type set to application/x-www-form-urlencoded: the "data" parameter carries a JSON representation of the actual message; "signature" and "signature_method" parameters allow you to verifiy the (optional) message signature, according to the algorithms described in Message Reference.

Talk in groups!

Every contact featured with the ‘group_add’ capability can be added to indoona groups by every user who owns it. Notice that contacts can be owned by more than one connected user, to reflect scenarios in which the corresponding entity in your domain is shared among multiple users.

When a contact is invited to a group, on the endpoint URL you will get a JSON message structured as follows:


{
	"id"		:	"21kj3h12oh3o",
	"type"		:	"group-invite",
	"timestamp"	:	"1434613275796",
	"sender"	:	"aewd558asta9c4sot4fkfj34l@indoona",
	"room"		:	"dcsurakhg9x4a1rlqxjuawazq",
	"owner"		:	"aewd558asta9c4sot4fkfj34l@indoona",
	"recipient	:	"333@appdomain",
	"data"		:	{
						"subject" : "My group",
						"avatar": "http://myavatar.com/my-group-avatar.jpg",
						"occupants": [
							{"id"	: "aewd558asta9c4sot4fkfj34l@indoona"},
							{"id"	: "333@appdomain"},
							{"id"	: "15@anotherappdomain"}
						],
						"policy": "open"
        			}
}

The "room" value is the unique group’s identifier, while the "owner" value is the identifier of the inviting user, among the ones who own the contact. Similar messages are delivered to your service in correspondence of all events regarding that group (e.g. join/leave of other participants).

Now you are able to send your first message to the group on behalf of the contact just invited:


POST /tp/message/send.json
Content-Type: application/x-www-form-urlencoded
Authorization: Bearer f66907b18c304d9a226cbbe1c128c8164e19ff01

resource_id=dcsurakhg9x4a1rlqxjuawazq&contact_id=smart_lamp_id&msg_type=text&text=Hello+everybody+from+John’s+lamp!

Response:

{
	"id" 		:	"21kj3h12oh3o",
	"type" 		:	"text",
	"timestamp" :	"1434613275796",
	"sender" 	:	"smart_lamp_id@yourdomain",
	"room" 		:	"dcsurakhg9x4a1rlqxjuawazq",
	"owner" 	:	"1i7qr9t0dxc0kiw8u4fmzx69f@indoona",
	"recipient 	:	"dcsurakhg9x4a1rlqxjuawazq@indoona",
	"data" 		:	{
						"body"	:	"Hello everybody from John’s lamp!"
					}
}

Follow our Guidelines to learn about best practices in working with messages.