Developers
 Login

Push Notifications

Push Notifications is a feature of our Messaging Platform that can notify your applications of activity on your Account e.g. the arrival of new Messages in your Inbox or Notification that a Message has been delivered. It requires a publicly accessible web page or web service that you host which Esendex posts information about the Notification to.

Setting up Push Notifications

Step 1: Host a Push Notifications Handler on your web server

Our Push Notifications are delivered across the Internet as HTTP POST requests so you'll need to host your Push Notifications Handler code on a publicly accessible web server. This could be your own server or one provided by a hosting company. Our Quickstart page provides example code for setting up a Push Notification Handler.

In order to receive Notifications you will need to write a Handler to process the XML that is sent by Esendex and respond with an HTTP Status Code of 200. If an HTTP Status Code of 200 is not received (e.g. if your Handler is unavailable for any reason) then a Notification will be retried again for the next 72 hours. All Inbound Messages are delivered to the Account Inbox regardless of whether the Push Notification has been successfully handled by your Push Notifications Handler.

Step 2: Configure the Push Notifications Handler URL

To configure the public URL to access your Push Notifications Handler on your Account:

  • Log-in to Developer Tools
  • If you have more than one Account with us, select the Account you wish to configure the Notification for.
  • Decide which of the Notifications you wish to setup and click the corresponding Configure button
  • Enter the valid public URL for your Push Notifications handler
  • If you wish, you may enter optional Notes for the Notification you are setting up. These notes are for your reference and do not affect the way in which Push Notifications work.

Step 3: Test your Push Notifications Handler

You can test the three types of Push Notification in the following ways:

  • Message Received Push Notification
    • Send an SMS to your Esendex Account's Virtual Mobile Number. You'll be able to check that the Message arrives in your Inbox in Echo and that a Message Received Notification is pushed to your Push Notifications Handler.
  • Message Delivered Push Notification
    • Send a Message from your Esendex Account to a mobile phone that you have access to and is able to receive messages. Once the SMS has arrived at the mobile phone, the mobile phone networks inform us of the delivery of the message and you should receive a Message Delivered Push Notification.
  • Message Failed Push Notification
    • Send a Message from your Esendex Account to a known bad telephone number (like 1). The attempt to send will fail and you should receive a Message Failed Push Notification.

Note: Any outbound activity from Account, including failed Messages, will incur a Message charge

Types of Notification

Message Received

When an Account's Message Received Notification is setup with a valid public URL, Esendex will HTTP POST the following XML to your Push Notifications Handler:

URL
Your Push Notifications Handler URL as set in Developer Tools
HTTP Method
POST
Authentication
n/a
Request
Content Type: application/xml
Example Request
<InboundMessage>
 <Id>{push-notification-id}</Id>
 <MessageId>{inbound-message-id}</MessageId>
 <AccountId>{esendex-account-id}</AccountId>
 <MessageText>{Message text of inbound message}</MessageText>
 <From>{phone number of sender of the message}</From>
 <To>{Virtual Mobile Number of your Account}</To>
</InboundMessage>
Expected Response
HTTP Status Code: 200

Message Delivered

When an Account's Message Delivered Notification is setup with a valid public URL, Esendex will HTTP POST the following XML to your Push Notifications Handler:

URL
Your Push Notifications Handler URL as set in Developer Tools
HTTP Method
POST
Authentication
n/a
Request
Content Type: application/xml
Example Request
<MessageDelivered>
 <Id>{push-notification-id}</Id>
 <MessageId>{inbound-message-id}</MessageId>
 <AccountId>{esendex-account-id}</AccountId>
 <OccurredAt>
  {the UTC DateTime (yyyy-MM-ddThh:mm:ss) the message was delivered}
 </OccurredAt>
</MessageDelivered>
Expected Response
HTTP Status Code: 200

Message Failed

When an Account's Message Failed Notification is setup with a valid public URL, Esendex will HTTP POST the following XML to your Push Notifications Handler:

URL
Your Push Notifications Handler URL as set in Developer Tools
HTTP Method
POST
Authentication
n/a
Request
Content Type: application/xml
Example Request
<MessageFailed>
 <Id>{push-notification-id}</Id>
 <MessageId>{inbound-message-id}</MessageId>
 <AccountId>{esendex-account-id}</AccountId>
 <OccurredAt>
  {the UTC DateTime (yyyy-MM-ddThh:mm:ss) the message was delivered}
 </OccurredAt>
</MessageFailed>
Expected Response
HTTP Status Code: 200

Security

Our Messaging Platform supports, and we encourage the use of, SSL encrypted communication between it and your Push Notifications Handler through the use of a certificate certified by one of the well know Root Authorities, e.g. VeriSign, Thawte, etc.