Automatize o envio de e-mails de convite do Discourse com Zapier

[Discourse]

A API do Discourse pode ser usada para automatizar o envio de e-mails de convite do seu fórum quando uma ação é realizada em uma aplicação externa. Para muitas aplicações, você pode usar o Zapier para configurar isso sem ter que escrever nenhum código.

Um caso de uso comum para isso é convidar usuários para o seu fórum quando eles compram um produto ou se inscrevem em um serviço externo. Para o exemplo neste tópico, usarei a integração Zapier WordPress para acionar o envio de um convite do Discourse quando um novo usuário se inscreve em um site WordPress.

Configurar uma etapa de gatilho (trigger) no Zapier

Vá para o seu painel do Zapier e pesquise pela aplicação que você gostaria que acionasse o e-mail de convite. Nas capturas de tela abaixo, selecionei o WordPress como o gatilho.

A única configuração necessária para isso é conectar o Zap do WordPress a uma conta do WordPress e selecionar o evento New User (Novo Usuário) para acionar o Zap.

Configurar uma etapa de ação (action) para enviar o convite

Clique no botão Add a Step (Adicionar uma Etapa) e, em seguida, clique em Action/Search (Ação/Pesquisa) no menu suspenso.

Digite ‘webhook’ no menu de pesquisa e selecione Webhooks by Zapier no menu de ações. A etapa de ação Webhook será adicionada à barra lateral do seu Zap, e um formulário será aberto que permite escolher que tipo de requisição você gostaria que o webhook executasse.

Selecione POST no formulário e clique em Continue (Continuar).

O formulário que se abre permite configurar a requisição POST feita para o Discourse. No campo URL, insira a URL base do seu fórum, seguida por /invites. Por exemplo, a URL base do meu fórum é https://demo.scossar.com, então o link completo para a rota de convites é https://demo.scossar.com/invites.

Agora você precisa configurar as seções Payload Type (Tipo de Carga Útil), Data (Dados) e Headers (Cabeçalhos) do formulário. Todas as outras seções do formulário podem ser deixadas com seus valores padrão.

O Payload Type informa ao Zapier em qual formato enviar a carga útil. Ele deve ser definido como Json.

A seção Data é usada para informar ao Discourse qual endereço de e-mail enviar o convite, e para definir uma lista opcional de nomes de grupos e uma mensagem personalizada. Para convidar um usuário sem adicioná-lo a grupos ou incluir uma mensagem personalizada, insira o texto email como uma Chave de dados (Key) e, em seguida, clique no ícone ‘Insert a Field’ (Inserir um Campo) para abrir o menu suspenso do campo. Role para baixo na lista até ver o valor que foi passado do seu aplicativo de gatilho que contém o e-mail do usuário. Ao usar o WordPress como aplicativo de gatilho, a seção Data completa deve ser parecida com esta:

Para adicionar automaticamente usuários a grupos quando eles aceitarem o convite, clique no ícone da seção Data para adicionar um novo campo. Defina a Chave (Key) do campo como group_names. Defina o Valor (Value) do campo como uma lista de nomes de grupos separados por vírgulas para os quais você gostaria que os usuários fossem adicionados. Para incluir uma mensagem personalizada no e-mail de convite, crie outro campo com sua Chave definida como custom_message e seu valor definido como a mensagem que você gostaria de enviar.

Nota: adicionando uma etapa de Código após a etapa de gatilho do seu Zap, deve ser possível definir dinamicamente nomes de grupos e uma mensagem personalizada para usuários específicos.

A seção Headers é usada para autenticar sua requisição. Para configurar o campo Headers, você precisará gerar uma chave de API no seu site Discourse. Para fazer isso, vá para a página Admin / API do seu site Discourse e clique no botão “New API Key” (Nova Chave de API). Ao criar a chave, atribua-a a um usuário da equipe (staff user) e defina o escopo como Global, ou use um escopo Granular com a caixa Invites > Create (Convites > Criar) marcada.

Agora, na seção Headers do Zap, insira os seguintes pares de chave/valor. Substitua quaisquer valores que incluí entre colchetes por valores apropriados para o seu site. A capitalização dos nomes das chaves é importante.

Api-Username: <o nome de usuário da equipe que você deseja enviar os convites>
Api-Key: <a Chave de API que você gerou>
Content-Type: application/json

O formulário agora deve se parecer com a captura de tela abaixo, mas com seu Api-Username e Api-Key:

Clique no botão Continue (Continuar).

Agora você poderá testar a integração clicando no botão ‘Send Test To Webhooks by Zapier’ (Enviar Teste para Webhooks por Zapier). O teste será realizado com os dados que você configurou na etapa de gatilho. Você verá uma mensagem de sucesso se tudo estiver configurado corretamente, e se o usuário que você configurou na etapa de gatilho ainda não existir no seu fórum Discourse, um e-mail de convite será enviado e você verá uma mensagem de Sucesso no Zapier. Assim que a etapa de teste estiver passando, clique no botão Finish (Finalizar) e ative seu Zap.

Para detalhes sobre como fazer outros tipos de requisições à API do Discourse com o Zapier, veja Make requests to the Discourse API with Zapier.

[alexknowshtml]

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?

[simon]

@alexknowshtml

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.

[alexknowshtml]

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

[alexknowshtml]

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!

[Thermaikos (David Altmann)]

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?

[simon]

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.

[simon]

@Thermaikos

Are there any descriptions on meta about alternative ways to create an automated process for sending an invite email after the reader signed up

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 Reverse engineer the Discourse API. You can test API requests with CURL from your computer’s terminal, or with a service like Postman.

[Thermaikos (David Altmann)]

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

[Thermaikos (David Altmann)]

@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?

[simon]

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.

[Thermaikos (David Altmann)]

Ah, awesome info. Thanks!!

[Krischan]

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?

[simon]

@Krischan

Is there a way to add a topic id that the user gets redirected to after signing up

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.

[Sebastien78 (Sebastien)]

Oi Simon,

Obrigado pelo seu post!

Tenho 2 perguntas; se você puder me ajudar, seria ótimo

Pergunta 1/
Do meu lado, o convite + mensagem está funcionando bem, mas, independentemente dos group_names que eu adiciono, tenho acesso apenas ao grupo público padrão quando entro no fórum.

Você sabe se algo pode “bloquear” o convite para um grupo privado específico?

A URL do nome do grupo é assim: https://forum.[mywebsite].com/c/cercle/33

Então eu tenho: group_names /// PUBLIC,cercle

Também tentei usar o “número” em vez do nome do grupo (33) para este grupo, mas ainda não funciona.

Talvez haja algum tipo de “restrição” nas configurações de administrador do fórum que bloqueie o convite para grupos privados?

Pergunta 2/

Gostaria de poder convidar pessoas não apenas para um “grupo privado”, mas para um “subgrupo privado” (não sei o nome correto para isso).

Aqui você pode ver que tenho o grupo “RÉSERVÉ…”
E todos os pequenos subgrupos abaixo dele.

Gostaria de convidar usuários para subgrupos específicos.

Você sabe como posso fazer isso?

Muito obrigado se puder dedicar um tempo para me ajudar com isso!

[simon]

@Sebastien78

No meu caso, o convite + mensagem está funcionando bem, mas, independentemente dos group_names que eu adiciono, só tenho acesso ao grupo público padrão ao entrar no fórum.

Certifique-se de estar usando o nome do grupo e não o nome da categoria à qual você permite que o grupo acesse. Você pode encontrar o nome do grupo na URL do grupo ou no campo Nome do grupo:

Se isso não resolver o problema, verifique se a chave da API do Discourse que você adicionou ao Zapier é uma chave global “Todos os Usuários”. Além disso, certifique-se de que o nome de usuário da API definido no Zapier tenha permissão para adicionar usuários ao grupo. Qualquer nome de usuário de administrador do seu site funcionará para isso.

Me avise se isso não resolver o problema para você.

@Sebastien78

Gostaria de poder convidar pessoas não apenas para um “grupo privado”, mas para um “subgrupo privado”.

Você pode convidar o usuário para vários grupos adicionando uma lista de nomes de grupos separados por vírgula ao campo group_names no Zapier. O Discourse não possui o conceito de subgrupos, então você precisará adicionar o nome de cada grupo ao qual deseja convidar o usuário.

Pela captura de tela que você forneceu, parece que você está tentando conceder ao usuário acesso a uma categoria e a todas as suas subcategorias. Em vez de criar um grupo para cada subcategoria, você pode simplesmente permitir que um único grupo acesse a categoria e todas as suas subcategorias. Isso é configurado na seção Segurança da página de edição da categoria.

[Sebastien78 (Sebastien)]

Obrigado pela sua resposta, Simon!

Então, em relação à API:

Eu havia concedido acesso apenas a um usuário (o administrador), achando que isso estava correto. Agora, criei uma nova API para dar acesso a todos os usuários.

Mas, ainda não funcionou. No entanto, acho que entendi o problema

Estou tentando adicionar um nome de “categoria” no campo “group_names”. Então, imagino que isso não funcione :).

Eu entendi mal os nomes de grupos/categorias/tópicos…

Na captura de tela, você pode ver uma lista de talvez 15 subcategorias: TB, MT, RD, MA…

Por exemplo, a URL da primeira subcategoria é: https://forum.MYWEBSITE.com/c/question-formactions/TBD/14

Então, imagino que eu queira convidar novos membros automaticamente para algumas subcategorias privadas, e não para algum Grupo.

Na URL que forneci, eu gostaria de conceder acesso apenas à subcategoria “TBD”, por exemplo.

E outro usuário teria acesso apenas a outra.

Você sabe se é possível fazer isso?

Talvez eu precise apenas substituir o campo “group_names” no Zapier pelo campo correspondente às Categorias?

[nathank (Nathan Kershaw)]

@Sebastien78

Então, acho que gostaria de convidar novos membros automaticamente para alguma subcategoria privada, e não para algum Grupo.

Grupos e Categorias são uma fonte de muita confusão no Discourse!

1. Grupos são coleções de pessoas.
2. Categorias são coleções de tópicos. Você não pode convidar pessoas para elas diretamente. Mas o acesso a essas categorias é controlado por grupos.

Para alcançar o que você deseja, crie um grupo. Nas configurações de segurança da categoria relevante, adicione acesso para esse grupo. Use esse grupo para a API de convites. Pronto.

[Sebastien78 (Sebastien)]

Obrigado pela sua resposta, Nathan!

Vou tentar isso e postar meu resultado aqui

[Sebastien78 (Sebastien)]

Sua solução funciona perfeitamente, obrigado!

Tenho outra pergunta, talvez você (ou @simon) possa me ajudar nisso:

Com o Zapier, existe alguma maneira de conceder acesso a um novo grupo para pessoas que já são membros do Discourse?

Basicamente, este é meu fluxo de trabalho:

1/ Um membro se inscreve em um dos meus cursos

2/ O Zapier pega o e-mail dele da minha plataforma de ensino e envia um convite para meu Discourse + o adiciona automaticamente ao grupo correto, relacionado ao curso que ele acabou de entrar.

3/ Às vezes, alguns meses depois, esse mesmo membro se inscreve em outro curso: então, com meu processo atual, meu Zapier enviará um novo convite para o Discourse, embora ele já seja membro, de modo que o convite não funcionará.

Preciso que o Zapier conceda a ele acesso a um novo grupo, caso ele já seja membro do meu Discourse.

Você vê alguma maneira de fazer isso?