Messages

Push messages

Whispir allows you to send push notifications to any iOS and Android-based apps. Sending push notifications is done via the /messages endpoint in the REST API, and the recipient is usually a Whispir contact MRI.

Setting up the platform to handle push notifications involves some one-time steps and some periodically repeated steps (updating push tokens). See Apps to get a clear understanding of the related steps and endpoints. Whispir doesn't support sending push notifications to device tokens directly. Read more in Contact devices about how to register the device tokens under contacts.

The following fields are required:

  • To: The Whispir Contact MRI value.
  • Subject: The first line or the badge header text in the push notification.
  • Body: The remainder of the push content.
  • appId: The ID given by Whispir on your app registration at the \apps endpoint. See Apps.

High-level request elements

to

String

Specifies the MRI value of the contact whose devices needs to receive the push.

subject

String

Specifies the first line or the badge header text in the push notification.

Body

String

Specifies the text that goes into the ‘alert’/‘data’ section of push structure.

appId

String

Specifies the appId of the registered app in Whispir.

So what happens in the background?

  • Whispir looks for the contact based on the MRI value in the given workspace (only).
  • It loads all the devices under that contact.
  • It filters them down to the device(s) that has the same appId as passed in the message payload or set in the template.
  • It sends a push to all the device(s) matched in the previous step.

Note: There is NO option to specifically pick a single device. If you need to do that, just register 1 device for that contact.

  • If Whispir doesn't find any devices under a contact, the message status will be ‘PENDING’ and the info will be ‘No valid recipients found for this message’.

Notes:

  • You must register your app with Whispir under the /apps endpoint. See Apps.
  • You must register the device token generated by your app with Whispir as a contact’s device. Refer to Contact devices.
  • You must send the push to a contact MRI only. Go to Contacts to get the MRI value.
  • The maximum push notification content length is 256 bytes for both iOS and Android devices. This includes the payload structure as well.
  • Whispir allows you to send custom message attributes with the payload. However, these are not available by default, and needs to be configured for you by Whispir.
  • There is support for other mobile app platforms. (Windows is provided on request via a separate Whispir enablement process.)
  • JSON
  • XML

{{codeStart}}

HTTP 1.1 POST https://api.<region>.whispir.com/workspaces/{:wid}/messages?apikey=[your_api_key]

Authorization: Basic am9obi5zbWl0aDpteXBhc3N3b3Jk

x-api-key: your_api_key  

Content-Type: application/vnd.whispir.message-v1+json

Accept: application/vnd.whispir.message-v1+json

{

"to" : "contact-mri-value",

"subject" : "Test push message",

"body" : "This is the body of my test push message",

"features" : {

"pushOptions" : {

"notifications" : "enabled",

"appId" : "{appId}"

}

}

}

 

Response: 202 Accepted

Location: https://api.<region>.whispir.com/workspaces/{:wid}/messages/{:mid}?apikey=[your_api_key]

{{codeEnd}}

 

Alternatively, if you have a template that has the correct content in the Mobile channel, the required features have been set, with the appId, and with notifications set to enabled, you can do this:

{{codeStart}}

{

"to" : "contact-mri-value",

"messageTemplateName" : "Name-Of-the-Template-Goes-Here"

}

{{codeEnd}}