One of the biggest moments of excitement for me every Christmas as I grew up was waiting to hear if Santa had delivered our presents. Every Christmas morning my Dad would go through to the room with the Christmas tree to check if "Santa had been" before we were allowed to run to see our presents.
Now, as a Dad, the responsibility of checking for Santa's delivery is mine.
I've heard of some families getting up at 4am in the morning to open presents! This means that Santa can deliver to some homes pretty early in the morning. So, what am I to do? Am I expected to get out of bed and check under the tree every 30 minutes? As somebody who previously proclaimed to be a "Real-Time Web Evangelist" I'm not keen on the thought of what is effectively the physical version of HTTP Polling. No, no, that won't do. So I decided to build a Santa Delivery Notification system using the Nexmo Dispatch API with Facebook Messenger as the primary notification channel with fallback to SMS because I don't want to miss that notification.
In this post I'm going to walk through the components used and how they come together to offer a Santa Delivery Notification solution. Details of the code won't be covered, but you can find all the code on GitHub along with instructions for running your own instance of the app.
How it Works
The app uses a combination of a Node.JS application, the Nexmo Dispatch API to send the Facebook Messenger message with SMS fallback if the message isn't read, a Santa API written by Steve Crow for his Tracking Santa with SMS and Java blog post, a Facebook Page and associated Facebook Application.
Logging into Facebook
The first part of the application asks the user to log in to Facebook.
Get the Users' Location
Whether Santa has delivered is determined using a combination of:
- Where the user is located
- Where Santa is on his delivery route
The user's location is determined using the browser Geolocation API. This returns just the coordinates of the user as a best-guess.
The coordinates are sent to the Node.JS back-end that uses the API that was created for the Tracking Santa with SMS app to find the nearest city for the coordinates.
Get user's phone number for SMS fallback
Now that the application knows where the user is located we need to know how to deliver notifications. If the Facebook Messenger message remains unread, the Nexmo Dispatch API will fallback to also delivering the message via SMS. So, we need the user's phone number for that fallback.
The user is to enter their phone number and click the "Go" button. Upon clicking the phone number is sent to the Node.JS back-end and the phone number stored for that user.
An enhancement to the current functionality here would be to use the Nexmo Number Insight API to ensure the phone number was valid and Verify API to confirm ownership of that phone number by the user.
Subscribe for Facebook Messenger "Santa Delivery Notifications"
Probably the trickiest part of the whole application was being able to send messages to the user without having them first send a message to our Facebook page.
Eventually, I came across the Send to Messenger plugin that seems to be set up for this. However, it does add some additional requirements around setting up a Facebook application and an "opt_in" webhook.
When the user clicks the "Send to Messenger" button (which you can configure to say instead "Subscribe") it will trigger the configured "opt_in" webhook from Facebook. The webhook payload contains the all-important Page Scoped User ID which is a unique ID for the user associated with a Facebook Page.
At this point, we save an official subscription within a database. This application uses a MongoDB instance managed by MLab.
With this ID the application can now send messages to the user using the Nexmo Dispatch API. To confirm the subscription a message is sent informing them that they have subscribed and their location.
Check Santa's Location and Send Notifications
With the subscription saved all that's left to do is monitor Santa's location using the previously mentioned Santa API.
The application uses the user's coordinates with the API, and when the API indicates that Santa is moving
away from the user's location, we know that Santa must have delivered. Thus, a Santa Delivery Notification is sent via Facebook Messenger using the Nexmo Dispatch API. If the message is not read within a configurable amount of time (see
expiry_time in the API reference) an SMS notification is also sent.
In this post, we've covered how a Santa Delivery Notification using Facebook Messenger with SMS fallback can be built using the Nexmo Dispatch API. Please take a look at the code on GitHub or raise an issue (or a pull request) if you've any ideas on making the application better (also see "Where next" below) or if you have any questions.
Now parents and guardians around the world can sleep easy knowing that they only need get out of bed to check if Santa has delivered once they've received that Santa Delivery notification.
- Try out the Dispatch API standalone
- Add the Number Insight API to the application to check the number format or even that the phone number is located in the same place as the geolocation API indicated
- Use the Verify API to ensure the that user owns the phone number they are registering
- Let us know what you think by tweeting at @NexmoDev