ewoudtm / feelapp-api

FeelApp API documentation

FeelApp REST API

RESTfull API provides access to the following resources:

• Applications
• Tips

API endpoints

Partner resource

All requests to do tips must be signed with partner token. Partner token is a string that must be obtained via the following API.

Get partner token

GET /api/v1/partner/<partner-key>/token?user=<user-id>

Parameters

URL parameter:

• <partner-key> is a secret key generated by FeelApp admin via admin interface. Please contact us to obtain the key.
• user-id - optional parameter, string, up to 1000 chars long. If this parameter is specified, requests signed with this key can be only executed for the given user. If this parameter is omited, the token can be used to manipulate any user.

Security note.

If the token is exposed to users (e.g. is used with Feel App JavaScript library), then it's strongly recommended to provide user id parameter, otherwiser this token can be used to send signals to ANY user.

Response (JSON)

{
  partner_token: 'partner-token'
}

The token is valid for 24 hours. Please note that each subsequent request can return a different partner token. Multiple tokens obtained this way can be valid at the same time as long as they are not expired.

For security reason, to avoid partner key exposure we recommend to perform such requests from server side only, not from the client side.

User resource

Represents external users (users registered on partners' websites)

Get user status

GET /api/v1/user/<user-id>/status?partner_token=<partner-token>

Parameters

URL parameter

• partner_token - partner token previously returned by /api/v1/partner/<partner-key>/token request
• user-id - performer user id on the partner website, string, up to 1000 chars long.

Response (JSON)

{ user_id: 'user-id', authenticated: true | false, online: true | false devices: , rooms: }

• user_id - performer user id, same as provided in request
• authenticated - true if user is known to FeelApp
• online - true if user is known and has the performer app running
• devices is a list of devices which are connected to the app (e.g. ['PEARL', 'ONYX'])
• rooms is a list of rooms user currently joined. Each room contains following fields:
  • room_id - unique room id
  • read - flag indicating if user can read from this room
  • write - flag indicating if user can write to this room Note: currently user cannot join more than one room. You have to kick the user out of the old room in order to join them to another one.

Getting notified about user status (beta)

Partners can be notified about user status change via http callback (web hook call). In order to do that the partner must implement a webhook endpoint web page which will be called by Feel platform each time user status is changed.

This webhook endpoint web page should be published somewhere on the internet and Feel platform should be notified about endpoint URL. This URL will be stored in the Feel platform database. Every time the status of any user has changed, Feel platform will send an HTTP request to the webhook endpoint.

Partners can use following script to submit URL of your webhook endpoint page to Feel platform: https://github.com/dulta/feelapp-api/blob/master/examples/webhook.php

Please download the script, change $PARTNER_KEY variable, upload it to your local web server and open in your browser.

You can also contact us so we change this URL in our database manually.

Each user status change will initiate a POST request to your webhook endpoint page. User status will be provided in POST variables:

• user_id - performer user id
• authenticated - true if user is has scanned a QR code with Feel app, false otherwise
• online - true if user is known and has the Feel app running, false otherwise
• devices is a list of devices which are connected to the app (e.g. ['PEARL', 'ONYX'])
• rooms is a list of rooms user currently joined. Each room contains following fields:
  • room_id - unique room id
  • read - flag indicating if user can read from this room
  • write - flag indicating if user can write to this room

Request user authorization

GET /api/v1/user/<user-id>/auth?partner_token=<partner-token>

Parameters

URL parameter

• partner_token - partner token previously returned by /api/v1/partner/<partner-key>/token request
• user-id - performer user id on the partner website, string, up to 1000 chars long.

Response (JSON)

{ auth_token: 'auth-token' }

This request returns auth token which should be displayed as the QR code.

Possible errors

• 401 NOT AUTHORIZED - partner token is invalid or is not authorized for the user.

Send a tip to the user

POST /api/v1/user/<user-id>/tip?partner_token=<partner-token>

Parameters

URL parameters:

• user-id - performer user id on the partner website
• partner_token - partner token previously returned by /api/v1/partner/<partner-key>/token request

POST parameters:

• sender - username of the person who sent the tip, string (e.g. John Doe)
• amount - tip amount, string (e.g. 10 coins)
• duration - tip (vibration) duration in seconds, floating point number (e.g. 2.5)
• strength - tip (vibration) strength in percents, integer (e.g. 50)
• customText - custom text, string. If specified, the mobile app will only show this text, sender and amount will be ignored and not displayed in the app.

Possible errors

• 404 NOT FOUND - user is offline or is not known to the FeelApp system. You should use /api/v1/user/<user-id>/status to see the reason why the tip cannot be sent.
• 401 NOT AUTHORIZED - partner token is invalid or is not authorized for the user.

Controlling user device(s)

POST /api/v1/user/<user-id>/device_speed?partner_token=<partner-token>

Parameters

URL parameters:

• user-id - user id on the partner website
• partner_token - partner token previously returned by /api/v1/partner/<partner-key>/token request

POST parameters:

• strength - Device(s) movement/vibration strength in percents, integer (e.g. 50). Send 0 to stop device(s) movement/vibration.

Possible errors

• 404 NOT FOUND - user is offline or is not known to the FeelApp system. You should use /api/v1/user/<user-id>/status to see the reason why the command cannot be sent.
• 401 NOT AUTHORIZED - partner token is invalid or is not authorized for the user.

Room resource

Add user to the room

POST /api/v1/room/<room-id>/users?partner_token=<partner-token>

NOTE

User cannot be added to more than one room at the same time. If the user has already joined another room, this call will return error.

Parameters

URL parameters:

• partner_token - partner token previously returned by /api/v1/partner/<partner-key>/token request
• room-id - room id to add user to. If room does not exist, it will be created.

POST parameters:

• user - user id on the partner website
• read - 0 or 1, indicating if user can read data from the room
• write - 0 or 1, indicating if user can write data to the room

Response (JSON)

Returns {} in case of success

ERRORS

• 404 NOT FOUND - user is not known to the FeelApp system.
• 401 NOT AUTHORIZED - partner token is invalid or is not authorized for the user.
• 409 CONFLICT - user is already in other room. Please remove user from that room first.

Delete user from the room

DELETE /api/v1/room/<room-id>/users/<user-id>?partner_token=<partner-token>

Parameters

URL parameters:

• partner_token - partner token previously returned by /api/v1/partner/<partner-key>/token request
• user-id - user id on the partner website

Response (JSON)

Returns {} in case of success

ERRORS

• 404 NOT FOUND - user is not known to the FeelApp system or not in the room.
• 401 NOT AUTHORIZED - partner token is invalid or is not authorized for the user.

Supported device models

Feel Platform provides the list of all supported bluetooth device models via the following endpoint:

GET /api/v1/device_models

No authorization is required to access this endpoint.

The endpoint returns a list of device records. Each record has following fields:

• product - Bluetooth device model name, e.g. Pearl
• type - Bluetooth device type, can be Vibrator or Masturbator
• manufacturer - Bluetooth device manufacturer, e.g. Kiiroo

• Note. This list is not about to be changed often. Please cache the returned value for a reasonable amount of time in order to decrease Feel Platform load.