Push notifications (IPNS)

With the Instaply mobile SDK, you need a way to notify end users when new messages arrive. IPNS (Instaply Push Notification System) means you expose an HTTP endpoint that Instaply calls with JSON; your server maps that payload to Apple/Google (or other) pushes.

Endpoint contract

Your server must accept:

• POST with Content-Type: application/json for the push payload
• GET on the same URL for a health check (no parameters, return 200)

Instaply treats a push as delivered when your endpoint returns HTTP 200 for the POST.

Version header

Instaply sends:

ipns-version: 1

The only supported value today is 1.

POST — request body

Example payload:

{
  "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"
      }
    }
  }
}

Field reference

Field	Optional	Description
from.user	yes	Message author
from.user.firstName	no	Author first name
from.user.lastName	yes	Author last name (omitted if unset in Instaply)
from.user.picture	yes	Author avatar URL (omitted if unset)
from.organization	yes	Sender’s organization
from.organization.name	no	Organization name in Instaply
from.organization.picture	yes	Organization image URL (omitted if unset)
message.text	yes*	Message text (*required unless attachment is present)
message.attachment	yes*	Attachment (*required unless text is non-empty)
message.attachment.name	no	File name
message.attachment.contentType	no	MIME type
message.attachment.thumbnails	yes	Thumbnail URLs (images)
message.attachment.thumbnails._50x50	no	50×50 thumbnail URL when thumbnails are present

POST — response

HTTP status	Meaning
200	Proxy acknowledged the notification
400	Invalid body / validation error
401	Authentication required
403	Forbidden
500	Unexpected error

A successful POST does not require a response body.

Error body (example)

{
  "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"
}

Field	Optional	Description
uuid	no	Correlates to your server logs
code	no	Your application error code (for debugging)
errors	yes	Field-level validation errors
message	no	Human-readable summary

GET — monitoring

Expose GET on the same path as POST (example: if POST is /instaply-notifications, GET must be /instaply-notifications). Return 200. A small JSON body with a timestamp and implemented IPNS version is recommended.

Security

The legacy specification states that the proxy may be secured with HTTP Basic Authentication so Instaply can authenticate to your endpoint.

Reference implementation

• ipns.zip — Java reference (JDK 8, Spring Boot / MVC per legacy description)

Provide one URL per organization to Instaply when you onboard push delivery.

See Mobile SDK overview for the high-level flow.