Learn About Local Indigenous Groups with Native Land Digital's API and Twilio WhatsApp

Time to read: 3 minutes

November 01, 2022
Written by
Dainyl Cua
Twilion
Reviewed by
Dhruv Patel
Twilion

Tutorial Header

While stories of indigenous people were shared in my classrooms growing up, I never truly understood just how many groups inhabited (and currently inhabit) the land we now know as the United States of America. Curious about the scale of things, I took a look at Native Land Digital and their API and was amazed at how many recognized territories there were across not only North America, but across the entire world.

In honor of Indigenous Peoples’ Month, I built a simple mobile app that takes your mobile device’s geolocation and gives you details about the indigenous groups and territories that have been established near you. In this tutorial, you’ll learn how I built the app using Twilio’s WhatsApp API so you can discover indigenous groups and territories near you!

Prerequisites

For this tutorial, you will need:

Set up your Twilio Function

Unlike some APIs, the Native Land Digital API does not require any authentication to perform API calls. You can go straight into creating your Twilio Function!

From your Twilio Console, click the Explore Products label on the left-hand sidebar. Then, click on Developer tools in the menu on the left, and then click on the Function and Assets card label. Click on the blue button labeled Create Service, enter a suitable Service Name (I named mine local-indigenous-whatsapp), and then hit the blue button labeled Next. You should end up on a page like the one below.

Twilio Function - Empty function

Click the blue button labeled Add on the top of the screen, and rename the path to /lookup.

Click on Dependencies, located below the Settings header on the bottom of the page. You will need to add the node-fetch module, specifically version 2.x. Enter node-fetch in the Module input box and enter 2.x in the Value input box. Then, click the button labeled Add.

Twilio Function - Dependencies tab with the node-fetch module imported on version 2.x

Next, head back to the /lookup tab. Copy and paste the following code into the code editor, replacing the preexisting code:

const fetch = require('node-fetch')

exports.handler = async function(context, event, callback) {
  // Here's an example of setting up some TwiML to respond to with this function
    let twiml = new Twilio.twiml.MessagingResponse();
  let latitude = event.Latitude
  let longitude = event.Longitude

  if(latitude && longitude) {
        let result = await fetch(`https://native-land.ca/api/index.php?maps=territories&position=${latitude},${longitude}`)
        let data = await result.json()
        let msg = "The following indigenous territories were found near you:\n\n"

        let territories = []

        for(i=0; i<data.length; i++) {
          territories.push(data[i].properties)
          msg += `${i+1}. ${territories[i].Name}\n${territories[i].description}\n\n`
        }

        twiml.message(msg)
  } else {
        twiml.message("Send your location through WhatsApp to lookup local indigenous territories.")
  }

  return callback(null, twiml);
};

This code initializes the fetch variable that will allow you to utilize the node-fetch module. In the now-asynchronous function, the twiml variable is initialized to allow you to send data messages back to the user. The latitude and longitude variables are then initialized to store incoming location messages sent through WhatsApp.

If both the latitude and longitude are provided, then the Native Land API is called and indigenous territories located near your location are found and a message listing them is sent. If not, then a message instructing the user to send their location is sent.

Hit the blue button labeled Save, then hit the blue button labeled Deploy All. Now, to get this function to work, you’ll need to set up your Twilio WhatsApp Sandbox.

Set up your WhatsApp Sandbox

In a new tab, head back over to the Explore Products page in your Twilio Console. Under Programmable communications, click Messaging. On the left-hand sidebar, click on the dropdown menu labeled Settings, then click on WhatsApp Sandbox settings. Follow the instructions on screen and send the specified WhatsApp message to the number provided to you, then complete the following instructions to access the Twilio Sandbox for WhatsApp page.

Be sure that you are sending messages through WhatsApp and not through your Messaging app. The Twilio number will respond, but you will be unable to progress through the rest of the instructions.

Copy your Twilio Function URL located above the Deploy All button you clicked in the previous part of this tutorial. Back on the Sandbox page, paste this URL into the input box next to WHEN A MESSAGE COMES IN located below the Sandbox Configuration header. At the front of the URL, add “https://” and at the end of the URL, and “/lookup”. This ensures that when a message is sent to your WhatsApp number, your Twilio Function is called properly. (e.g., https://local-indigenous-lookup-9153.twil.io/lookup)

Twilio Sandbox - Twilio Sandbox page with the Twilio Function in the WHEN A MESSAGE COMES IN header

Now, hit the blue button labeled Save at the bottom of the screen and then send a Location message to the number through WhatsApp! To send a location message, click the plus icon (+) next to the chat box, click Location, and then click Send Your Current Location.

WhatsApp - Conversation with a Twilio number containing a sent, blacked-out location message and a response message with indigenous groups

Conclusion

Congratulations, you’ve successfully completed this tutorial! Take some time to learn more about the indigenous groups near you as well as in your country. Learn about any history that you may have not been taught about in class, and learn about another important culture that shapes the world you know. Perhaps you can think of something else you can make to spread awareness with one of Twilio’s many APIs?

I can’t wait to see what you build!

Dainyl Cua is a Software Engineer who loves helping others code. They would love to talk at any time and help you out. They can be reached through LinkedIn.

Related Posts

Related Resources

A newspaper article

Twilio Docs

From APIs to SDKs to sample apps

API reference documentation, SDKs, helper libraries, quickstarts, and tutorials for your language and platform.
An Open book

Resource Center

The latest ebooks, industry reports, and webinars

Learn from customer engagement experts to improve your own communication.
User group reactions

Ahoy

Twilio's developer community hub

Best practices, code samples, and inspiration to build communications and digital engagement experiences.