Automate sending Discourse invite emails with Zapier

The Discourse API can be used to automate sending invitation emails from your forum when an action on an is performed on an external application. For many applications, you can use Zapier to set this up without having to write any code.

A common use case for this is to invite users to your forum when they purchase a product
or signup on an external service. For the example in this topic I will use the Zapier WordPress integration to trigger sending an invite from Discourse when a new user signs up on a WordPress site.

Setup a trigger step on Zapier

Go to your Zapier dashboard and search for the application that you would like to trigger the invite email. In the screenshots below, I have selected WordPress as the trigger.

wordpress_trigger

The only configuration that is required for this is to connect the WordPress Zap to a WordPress account, and to select the New User event to trigger the Zap.

Setup a action step to send the invite

Click the Add a Step button and then click Action/Search from the dropdown menu.

Enter ‘webhook’ into the search menu and then select Webhooks by Zapier from the actions menu. The Webhook action step will be added to your Zap’s sidebar, and a form will open that lets you choose what type of request you would like the webhook to perform.

Select POST from the form and then click Continue.

The form that opens lets you configure the POST request that is made to Discourse. In the URL field, enter your forum’s base URL, followed by /invites. For example, my forum’s base URL is https://demo.scossar.com, so the full link to the invites route is https://demo.scossar.com/invites

You now need to configure the form’s Payload Type, Data, and Headers sections. All other sections of the form can be left with their default values.

The Payload Type tells Zapier what format to send the payload in. It should be set to Json.

The Data section is used to tell Discourse which email address to send the invite to, and to set an optional list of group names and a custom message. To invite a user without adding them to groups or including a custom message, enter the text email as a data Key, and then click the ‘Insert a Field’ icon to open the field’s dropdown menu. Scroll down the list until you see the value that has been passed from your trigger app that contains the user’s email. When using WordPress as the trigger app, the completed Data section should look similar to this:

To automatically add users to groups when they accept the invite, click the Data section’s :heavy_plus_sign: icon to add a new field. Set the Key of the field to group_names. Set the Value of the field to a comma separated list of group names that you would like users to be added to. To include a custom message in the invite email, create another field with its Key set to custom_message and its value set to the message you would like to send.

Note: by adding a Code step after your Zap’s trigger step it should be possible to dynamically set group names and a custom message for specific users.

The Headers section is used to authenticate your request. To configure the Headers field, you will need to generate an API key for a staff user on your site or an All Users API Key. To do that, go to your Discourse site’s Admin / API page and click the “New API Key” button.

Now, in the Headers section of the Zap, enter the following key/value pairs. Replace any values that I’ve included in brackets with values appropriate for your site. Capitalization of the key names is important.

Api-Username: <the staff username you want to send the invites>
Api-Key: <the API Key you generated>
Content-Type: application/json

The form should now look similar to the screenshot below, but with your Api-Username and Api-Key:

Click the Continue button.

You will now be able to test the integration by clicking the ‘Send Test To Webhooks by Zapier’ button. The test will be performed with data that you setup in your trigger step. You’ll see a success message if everything is correctly configured, and the user you setup in your trigger step does not yet exist on your Discourse forum, an invite email will be sent and you will see a Success message on Zapier. Once the test step is passing, click the Finish button and turn your Zap on.

For details about how to make other types of requests to the Discourse API with Zapier, see How to make requests to the Discourse API with Zapier.

21 Likes

This is awesome thank you for the feature and clear instructions!

Is it possible to also set the custom group when generating an invite, like you can from within the app?

That can be done by adding a group_names key to the Headers field. Its value should be set to a comma separated list of group names. I’ll add an example of this to the topic.

The basic approach that’s used in this topic will work for any API request to Discourse.

3 Likes

Awesome!! I think the dialog accepts a custom message too, guessing that can be done the same way?

1 Like

I tried setting this up this AM and was running into a 400 error. With a little bit of debugging, I found that the auth-related steps need to go in the headers section as instructed, but the actual form values (email, group name, and custom message) need to go in the data section as key/value sets.

Once I made that change, though, it worked perfectly!

1 Like

Thanks for that, @simon!

Are there any descriptions on meta about alternative ways to create an automated process for sending an invite email after the reader signed up to an offering and to which you could link here?

Thanks for testing that! What I’m finding is that when no custom_message or group_names are included in the request, passing the email in the Headers works. It’s not the correct way to pass the email address though. I’ve updated the guide to use the Data section for setting the email address, and have included examples for adding users to groups and including a custom message.

4 Likes

I’m not aware of other services that are similar to Zapier, but I’m sure there are some out there. You can make requests directly to the Discourse API without using a third party service. The main requirement for doing this is that you have an application to make the requests from. This can be something a simple as a WordPress site.

A good resource on Meta for getting started with the API is How to reverse engineer the Discourse API. You can test API requests with CURL from your computer’s terminal, or with a service like Postman.

2 Likes

Thank you! Most of what you write I have no idea about… but I’ll check I’ll out your links and see if so can understand anything :smiley:

2 Likes

@simon

Quick question:

When I send an automated invite through Zapier, would this then be an already personalized link, or a link to the general login page to my forum (where someone can log in and also create an account)?

I would like to avoid that everybody and their dog who knows the login page creates an account. How can that best be avoided?

When you send an invite link through Zapier you are triggering exactly the same action as if you had clicked the ‘Send an Invite’ link from your account’s Invite page.

Creating an invite will send an email to invited user’s email address. That email contains a link to a page where the invited user can set their name and password, and login to their new account. The email address for the new account is set by the email address that you used for the invite.

Only users who have been sent an invite can create an account through this page. If you would like to only allow invited users to register for your site, go to the Login section of your Site Settings and select the invite only site setting.

The best way to get a sense of how invites work is to invite yourself to your site. You can use a throw-away gmail address for this. You will need to log out of the site before you will be able to accept your invite.

3 Likes

Ah, awesome info. Thanks!!

1 Like

Thanks for the great tutorial! Is there a way to add a topic id that the user gets redirected to after signing up like in the bulk invite feature?

It is possible to invite a new user to a topic with a similar approach to what is outlined above, but the URL that you setup in the Action step needs to point to the topic. For example, to invite a user to a topic with the id 123 you would add the URL https://forum.example.com/t/123/invite to the Action step. You would then add the email and the optional custom_message and group_names parameters in the same way as they are outlined in the guide.

2 Likes

Hi Simon,

Thanks for your post !

I have 2 questions, if you could help me, it could be awesome :slight_smile:

Question 1/
On my side, the invite + message is working fine, but whatever group_names I’m adding, I only have access to the default public group, when I join the forum.

Do you know is something could “block” the invite to specific private group ?

The URL of the group name is like that : https://forum.[mywebsite].com/c/cercle/33

So I have : group_names /// PUBLIC,cercle

I also tried to use “number” instead of the group name (33) for this group, but it still doesn’t work.

Maybe there is a kind of “restriction” on the admin setting of the forum, which block the private group invite ?

Question 2/

I would like to be able to invite people, not only to “private group”, but "private “sub-group” (I don’t know the right name for that)

Screenshot 2021-05-12 at 08.04.11

Here you can see, I have the group “RÉSERVÉ…”
And all the little sub-groups under it.

I would like to invite users to specific subgroups.

Do you know how I can do that ?

Thanks a lot if you can take some time to help me on that ! :slight_smile:

1 Like

Make sure that you are using the group’s name and not the name of the category that you allow the group to access. You can find the group’s name in the URL for the group, or from the group’s Name field:

If that does not resolve the issue, make sure that the Discourse API key you add to Zapier is a global All Users API key. Also, make sure that the API Username set on Zapier has permission to add users to the group. Any admin username on your site will work for this.

Let me know if this doesn’t resolve the issue for you.

You can invite the user to multiple groups by adding a comma separated list of group names to the group_names field on Zapier. Discoure doesn’t have the concept of sub-groups, so you will need to add the name of each group you want to invite the user to.

From the screenshot you have provided, it looks like you are trying to give the user access to a category and all of its subcategories. Instead of creating a group for each subcategory you could just allow a single group to access the category and all of its subcategories. This is configured on the Security section of the category’s edit page.

2 Likes

Thanks for your reply Simon !

So, regarding the API :

I had give the access to only one user (the admin) I thought it was ok. So now I created a new API to give access to all user.

But, it still didn’t work. But I may have understood the issue :slight_smile:

I’m trying to add a “category” name, in the “group_names” field. So I guess it can’t work :).

I misunderstood the name of groups/category/topic…

On the screenshot you can see a list of maybe 15 subcategories : TB, MT, RD,MA…)

For example, the URL of the first subcategory is : https://forum.MYWEBSITE.com/c/question-formactions/TBD/14

So I guess would like to invite new members automatically to some private subcategory, and Not some Group.

On the URL I gave you, I would like to give only access to the subcategory “TBD” for example.

And, another user will have Only access to another one.

Do you know if it’s possible to do it ?

Maybe I just have to replace the field “group_names” on Zapier, by the one for Categories ?

1 Like

Groups and Categories are a source of much confusion in Discourse!

  1. Groups are collections of people.
  2. Categories are collections of topics. You can’t invite people to them per se. But access to these is controlled by groups.

To achieve what you want, make a group. In the relevant category security settings, add access for that group. Use that group for the invites API. Done.

3 Likes

Thanks for your reply Nathan !

I will try that and post my result here :wink:

2 Likes