The Keep:Scheduling Quest Starts with Zapier and API

The Keep: Index > The Mage's Tower > Scheduling Quest Starts with Zapier and API

Background

Our party wanted a way to schedule Quests to start at a particular time, both to avoid forgetting to start quests and to be able to schedule quests to start while the quest owner is busy or asleep. This is the way we came up with - by using Zapier, Google Calendar, and Habitica's Application Programming Interface, we've set it up so quest owners or the party leader can create a Google calendar entry for when the quest is scheduled to start, and then Zapier uses the API to start the quest at that time.

Step One: Register

First, make sure you have an account on and can log into Zapier, Google Calendar and Habitica. (Each of those services is free.)

Note: this write up assumes that each person participating wants their own calendar. If you wanted to, your party could set up something with a shared calendar - either every party member could create trigger calendar entries and the party leader's Zap would start quests, or you could have each party member's Zap looking for specific keywords in a shared calendar. If you set something like that up, I'd love to hear about it.

Step Two: Set Up Zapier

Zapier is a service that will monitor various web apps and then take actions. Zapier lets you set up small programs (called "Zaps") that watch for some condition ("Triggers"), then make something happen ("Actions.") Zapier uses internal "Apps" that lets it communicate with other websites for both triggers and actions. In this case, we will be using the Google Calendar app to monitor Google Calendar for quest start appointments, and using Zapier's "Webhooks" app to call Habitica's API and start the quest.

Here's how to set up Zapier:

1. Sign on to your Zapier account
2. Click on the "Make a Zap!" button.
3. In the "Trigger" phase of the set-up, we will tell Zapier to look for Google Calendar entries that match a keyword.
   1. Under "Choose a Trigger App," search for and select "Google Calendar."
   2. Select the "Event Start" trigger to have Zapier act when a matching event is about to start.
   3. Choose "Connect an Account" and log in to your Google Calendar account.
   4. Select which of your calendars you plan to use. (I used my main calendar, so my quest starts show up on my calendar screens).
   5. In the "Time Before" field, set the trigger to occur 0 minutes before the appointment.
   6. In the "Search Term" field, select a term that you will include in Calendar titles for your entries. (I chose "habquest", because I didn't think it would come up unintentionally.)
   7. The app will let you test your calendar. Click on test to make sure Zapier can connect, then finish this phase.
4. In the "Action" phase of the set-up, search for and choose "Webhooks," which is the app we will use to call Habitica's API.
   1. Choose a "Post" action
   2. Under "URL" enter https://habitica.com/api/v3/groups/party/quests/force-start
   3. Enter two Headers. The first will have a key of x-api-user and a value of your User ID, and the second will have a key of x-api-key and a value of your API Token. (Note that your token is a password, so don't share it with others!)
   4. Zapier will give you an option to test this step. Note that if successful, this test will start your quest, so I wouldn't recommend running the test unless you are ready to start or unless you are having problems and need to see if there is some kind of error code.
5. Feel free to name your Zap something memorable, finish it and turn it on.

Step Three: Create a Calendar Entry

Create an entry in your Google calendar at the date and time you want to start your quest. Make sure the title includes the keyword you set up on Zapier. I also recommend turning off notifications unless you want them for some reason.

Note: Since Zapier only checks for new appointments every 15 minutes, you should set your appointment to start least 15 minutes after you enter it.

Asusming that your quest starts, you are all set! You can schedule a quest start by entering a new appointment (including the keyword) in your calendar at any time.

Additional Resources

• Zapier Learning Center
• Application Programming Interface - Wiki documentation on Habitica API
• Habitica API v3 Documentation - The best way to find out what you can do with API, and how.
• My wall - I'd love to hear if you have any questions, a better way to do this, or any other cool API tricks!