1. Home
  2. Docs
  3. SDK
  4. Push notifications

Push notifications

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 here. It’s a fully functional Java implementation, built around:

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