Introduction

With the integration of an Instaply SDK in third party mobile apps, comes the need to send push notifications to the end-users. This document aims to specify the Instaply Push Notification System (IPNS). In short, you need to provide a REST endpoint that will be notified by Instaply servers when a new push notification is ready. Instaply will send a generic JSON message, that can then be mapped to a push notification for any device. The following describes the specification for the REST endpoint.

Endpoint service contract

Push notification request

The proxy must implement an endpoint accepting POST requests with an application/json body type. The URL remains at your discretion. Instaply servers will send push notifications to that endpoint. From the Instaply end, a push notification is considered delivered as soon as the endpoint returns an HTTP 200 status.

Request

{
  "type": "message",
  "unreadMessagesCount": 123,
  "date": "2015-05-01T14:26:39.546Z",
  "customer": {
    "id": "CUST-123"
  },
  "message": {
    "from": {
      "organization": {
        "name": "Instaply",
        "picture": "https://api.instaply.com/files/xxxx"
      },
      "user": {
        "firstName": "John",
        "lastName": "Doe",
        "picture": "https://api.instaply.com/users/9999/icon",
      }
    },
    "text": "hello sdk",
    "attachment": {
      "name": "instaply-logo.png",
      "contentType": "image/png",
      "thumbnails": {
        "_50x50": "https://api.instaply.com/files/yyyy"
      }
    }
  }
}

where:

Field	Optional	Description
from.user	yes	The user sending the message.
from.user.firstName	no	The first name of the message author.
from.user.lastName	yes	The last name of the message author. The field is not present if no last name was set in the user Instaply profile.
from.user.picture	yes	A link to the picture of the message author. The field is not present if no picture was set in the user’s Instaply profile.
organization	yes	The organization the message sender belongs to.
organization.name	no	The name of the organization as defined in Instaply.
organization.picture	yes	A link to the picture of the organization the message sender belongs to. The field is not present if no picture was defined for the organization.
organization.picture	yes	A link to the picture of the organization the message sender belongs to. The field is not present if no picture was defined for the organization. text
text	yes	The content of the message. The field is only optional if the message contains an attachment.
attachment	yes	The attachment posted with the message. The field is only optional if the message contains a non empty text.
attachment.name	no	The attachment file name.
attachment.contentType	no	The attachment mime type.
attachment.thumbnails	yes	Links to attachment thumbnails. This is currently only set for image attachments.
attachment.thumbnails._50x50	no	a link to a 50×50 pixel thumbnail

####Response

The response HTTP status could be one of the following:

HTTP status	Description
200	The proxy acknowledges the receipt of the push notification request.
400	An error occurred while processing the request. Typically, the request body was found to be invalid.
401	Authentication required
403	Forbidden
500	Unexpected server error.

Success response body

A successful processing of the push notification request does not require any response body.

Error handling

Any error on the proxy side should return the appropriate HTTP status and a comprehensive message. Example of validation error:

{
  "uuid": "bee07e99-63c1-47ca-b997-2e5203481900",
  "code": "40001",
  "errors": [
    {
      "field": "message.from.user.firstName",
      "message": "may not be empty"
    },
    {
      "field": "message",
      "message": "text and attachment cannot be both null"
    }
  ],
  "message": "Illegal argument"
}

where:

Field	Optional	Description
uuid	no	A unique identifier for the error. This should be displayed in the proxy error log so we can easily locate the stack trace.
code	no	An error code. The value is up to you, it will be mentioned for debugging purposes.
errors	yes	A collection of validation errors. Mention the field in error and a meaningful description.
message	no	A meaningful description of the error.

Versioning

The versioning information for the push notification request will be included as a HTTP header: ipns-version. The only version currently supported is ‘1’.

Monitoring

To allow a basic monitoring of the proxy server, an endpoint accepting the GET method must be provided. It must be available at the same URL as the endpoint receiving the push notification requests (e.g. if you receive push notification at POST /instaply-notifications, the monitoring endpoint must be GET /instaply-notifications). This monitoring endpoint must not expect any parameter and must return a 200 HTTP status. The response body is optional, but we recommend a JSON message, including a timestamp of some sort and the version of implemented IPNS specification.

Security

The push notification proxy must be secured and clearly identify Instaply servers as the origin of a push notification request. In order to keep things as simple as possible, we currently only support basic HTTP authentication.

Reference implementation

A reference implementation is available. It’s a fully functional Java implementation, built around:

JDK 8
Spring Boot
Spring MVC (for the REST controller)
SDK Push Notifications Specification –

reference implementation ipns Download