Requests to the Discourse API can be automated by creating a Zap that uses a Zapier Webhook as its action step. This topic will describe how to perform requests for the following actions:
- add user to group
- grant a custom badge
To figure out how to perform other types of API requests with Zapier, read through the topic and then search the Discourse API docs for the action you are wanting to perform. You can also find how to create an API request for a specific action by reading Reverse engineer the Discourse API.
Setup the trigger step
Each Zap must have a trigger and an action step. The trigger is used to pass data from an application to the Zapâs action step. In some cases, the trigger can also be used to stop a Zap from completing its action step unless its data meets certain conditions.
To setup your action step, go to your Zapier Dashboard and click the Make a Zap button. A search form will open asking you to choose a trigger app.
For the examples in this topic, I am using the WordPress New User event as the action step. This is because it is easy to setup for testing the API calls.
The âTest This Stepâ node of your trigger step allows you to select a sample of data from your trigger application that will be passed to your Zapâs action step. This data will be useful for setting up the action step.
Add an optional step to retrieve details from Discourse
Depending on what data is passed from your trigger app, you may need to retrieve some data from Discourse before you can make your final API request. For example, the WordPress New User trigger passes the userâs WordPress username and email address. I know that the email address will match the Discourse userâs email address, but for the API requests in this example, I need to know the userâs Discourse username.
To get a userâs Discourse details from their email address, add an action step to your Zap. Select âGETâ from the webhookâs action menu.
On the webhookâs Edit template step, enter your Discourse siteâs base URL, followed by /admin/users/list/all.json
into the URL section. For example, my siteâs base URL is https://demo.scossar.com
, so I enter https://demo.scossar.com/admin/users/list/all.json
into the URL field.
In the Query String Params section, enter âemailâ as the Key and then click the âInsert a Fieldâ icon to open the dropdown menu. Select the value that was passed by your trigger step that contains the userâs email address.
Authenticate the request
Scroll down the form to its Headers section. This section is used to authenticate the request. It requires three key/value pairs:
-
Api-Username
: the username of an admin user on your site. For most cases the âsystemâ user will be a good choice for this. -
Api-Key
: the API Key that is associated with the username you have used in the first key/value pair -
Content-Type
:multipart/form-data
The completed Headers section should look similar to this, but with your userâs API key:
Click the Continue button to see the data that is retrieved from Discourse for this request.
Add the final action step
Once your trigger and the optional step to retrieve data from Discourse are configured, click the âAdd a Stepâ link and select âWebhooks by Zapierâ from the action menu. You will then be asked to choose which request method you would like to use in your API request to Discourse.
Here are the request types required for the examples used in this topic:
- add user to group:
PUT
- grant custom badge:
POST
To configure API requests other than this topicâs examples, have a look at the Discourse API documentation to see if there is an example of the request you would like to make. If you are not finding an example there, read through How to reverse engineer the Discourse API to learn how to find the URL and request method for the action you would like to perform. Once you have found the request method, select it from the action menu.
Note: if your request uses the DELETE
method, select âCustom Requestâ from the action menu.
Configure the final action step
The actionâs Headers section can be configured in the same way for all API requests. See the âAuthenticate the requestâ section of this topic for details. If you have added the optional step to retrieve details from Discourse, you can configure the Headers section of the final action in exactly the same way as you did for that step.
Once the Header key/value pairs have been added, you will need to fill out the formâs URL and Data fields for your API request.
Add user to group
To add a user to a group, a PUT
request is made to /groups/<group_id>/members.json
. The easiest way to find a groupâs ID is to visit the groupâs page through the Discourse UI, and then enter .json
into the URL in your browserâs address bar. For example, my site has a âsupportâ group at https://demo.scossar.com/g/support
. By going to https://demo.scossar.com/g/support.json
I can see that the groupâs ID is 41. My forumâs base URL is https://demo.scossar.com
. The URL in my final action step to add users to a group gets set to https://demo.scossar.com/groups/41/members.json
.
The request to add users to a group requires one parameter - a comma separated list of usernames. In the formâs Data section, enter âusernamesâ as the key. Then click the âInsert a Fieldâ icon to search for the username property that has been passed from either the trigger, or the optional GET
action step.
For my case, I want the username that was retrieved by the GET
step, so I expand the âGETâ menu and select Username from the dropdown.
All other sections of the form can be left at their default values.
Click the Continue button and then test your step. If the user you have passed through the previous steps exists on your Discourse site, and they are not already a member of the group you have selected, they should be added to the group when you test the step.
If everything works as expected, turn on your Zap.
Grant a custom badge
To grant a custom badge to a user, a POST
request is made to your forumâs base URL + /user_badges
. For my site, the URL for granting badges is https://demo.scossar.com/user_badges
. The completed URL field on Zapier looks like this:
The formâs Data section requires two key/value pairs. Add a âusernameâ key and set it to the field that returns the userâs username. Add a âbadge_idâ key and set it to the ID of the badge you would like to grant. You can find the badge ID by going to your Admin / Badges page and selecting the badge from the left side menu. You will see the badge ID as the last value of the URL in your browserâs address bar.
The badge that I am granting has an ID of 105, so my completed Data section looks like this:
Make sure you have configured the formâs Headers section, then click Continue. Then click the Send Test button to test your Zap. The user you have passed through the previous steps should be granted the badge.
If everything is working correctly, turn on the Zap.
Last edited by @JammyDodger 2024-05-26T06:52:05Z
Check document
Perform check on document: