Building a Drift App: Part 3 – OAuth and Conversations API
In this week’s continuation of Building a Drift App, we’ll be looking at setting up Drift OAuth. In earlier examples, we used Drift’s Access Token to interact with the API. This token is great if you only plan to add your bot to your own team because that token will never expire and you do not need to build an OAuth flow. However, if you want to submit to the Drift App store and share your awesome bot across the platform you will need to add OAuth.
But don’t fear, we’ve added some helper methods in the Drift-Chat NPM and example code in the GitHub Repo.
You’ll need to head over to the Drift Dev Platform and add a few things. You will need to enter in a valid ngrok (or local tunnel) URL to handle the OAuth request. And also enable conversations_read scope for this example.
Setup the /oauth Route:
We’ve added a popular MongoDB ORM called Mongoose and Bluebird Promises to help persist the token within a Team Object so we can recall it when we receive events. We use the orgId as our unique ID because it is sent in every Event wrapper.
We need to do a few things to set up the API call to Drift:
- Set up the Mongoose connection (bot.js line 10 – 12).
- Require the mongoose Team constructor. You will need to take a look at ./models/team.js in the example code to check out the Schema (bot.js line 6).
- Instantiate a drift object from the Drift constructor but unlike in previous examples do not pass in an access token (bot.js line 15).
- The drift.oauth method will need an options Object with Client ID and Secret Key from the portal and the temp code found in req.query.code. Take a look at Drift Dev Docs if you have any question here (bot.js line 16-20).
- Drift will return an Object containing your accessToken and refreshToken. Go ahead and save the whole object via Mongoose for later.
- As a final step you’ll want to redirect the user somewhere to provide a better user experience, but for this example, we just send them a prompt letting them know they are ready to use the bot (bot.js line 34).
Receiving Events & Using your new Token:
We’ve added some new stuff to this route:
- You will always want to enforce a Token Verification to ensure that these requests are coming from Drift. This token is found in the same place you copied your Client ID and Secret (bot.js line 39).
- We need to fetch the team Object from the Database (bot.js line 42).
- Then initialize the Drift-Chat NPM with that team’s token (bot.js line 43).
We’ve built a few new methods around the Conversations API including getConvo() & postMessage(). But for this example we’ll examine getConvo() which contains an Array of Message Objects:
- Pass in the message as an argument to give the method context to fetch the Convo (bot.js line 45).
- If an error occurs the first thing you’ll want to do is ensure that the team’s accessToken is not expired.
Refreshing an Expired Token:
- Similar to how we set up the OAuth options Object we will need to do a similar setup here but pass in the refreshToken as an option for the drift.refreshToken() method (bot.js line 52-56)
- Use the response to update the team Object and persist for later (bot.js line 58-59).
- Overwrite the drift.token with the new accessToken (bot.js line 60).
- You should have a fresh new token in the drift Object to make any subsequent calls.
Whelp, we covered a lot in this post. OAuth can be somewhat complicated, but with the NPM helper methods we tried to reduce the technical overhead and the great news is that once it’s wired up you rarely need to change it.
That’s all for this week. Next, we will look at the interactive messages and button actions via the Conversations API!