Faça solicitações à API do Discourse com o Zapier

[Discourse]

As solicitações à API do Discourse podem ser automatizadas criando um Zap que usa um Webhook do Zapier como etapa de ação. Este tópico descreverá como realizar solicitações para as seguintes ações:

• adicionar usuário a um grupo
• conceder uma insígnia personalizada

Para descobrir como realizar outros tipos de solicitações de API com o Zapier, leia este tópico e, em seguida, pesquise na documentação da API do Discourse pela ação que deseja executar. Você também pode descobrir como criar uma solicitação de API para uma ação específica lendo Reverse engineer the Discourse API.

Configurar a etapa de gatilho

Cada Zap deve ter um gatilho e uma etapa de ação. O gatilho é usado para passar dados de um aplicativo para a etapa de ação do Zap. Em alguns casos, o gatilho também pode ser usado para impedir que um Zap conclua sua etapa de ação, a menos que seus dados atendam a certas condições.

Para configurar sua etapa de ação, acesse seu Painel do Zapier e clique no botão Criar um Zap. Um formulário de pesquisa será aberto pedindo que você escolha um aplicativo de gatilho.

Para os exemplos neste tópico, estou usando o evento Novo Usuário do WordPress como a etapa de ação. Isso ocorre porque é fácil configurar para testar as chamadas de API.

O nó “Testar esta etapa” da sua etapa de gatilho permite selecionar uma amostra de dados do seu aplicativo de gatilho que será passada para a etapa de ação do seu Zap. Esses dados serão úteis para configurar a etapa de ação.

Adicionar uma etapa opcional para recuperar detalhes do Discourse

Dependendo dos dados passados pelo seu aplicativo de gatilho, você pode precisar recuperar alguns dados do Discourse antes de fazer sua solicitação de API final. Por exemplo, o gatilho Novo Usuário do WordPress passa o nome de usuário do WordPress e o endereço de e-mail do usuário. Sei que o endereço de e-mail corresponderá ao e-mail do usuário do Discourse, mas para as solicitações de API neste exemplo, preciso saber o nome de usuário do usuário no Discourse.

Para obter os detalhes de um usuário no Discourse a partir do endereço de e-mail, adicione uma etapa de ação ao seu Zap. Selecione “GET” no menu de ação do webhook.

Na etapa de edição do modelo do webhook, insira a URL base do seu site do Discourse, seguida de /admin/users/list/all.json na seção URL. Por exemplo, a URL base do meu site é https://demo.scossar.com, então insiro https://demo.scossar.com/admin/users/list/all.json no campo URL.

Na seção Parâmetros da String de Consulta, insira “email” como a Chave e, em seguida, clique no ícone “Inserir um Campo” para abrir o menu suspenso. Selecione o valor que foi passado pela sua etapa de gatilho e que contém o endereço de e-mail do usuário.

Autenticar a solicitação

Role para baixo no formulário até a seção Cabeçalhos. Esta seção é usada para autenticar a solicitação. Ela requer três pares chave/valor:

• Api-Username: o nome de usuário de um usuário administrador no seu site. Na maioria dos casos, o usuário ‘system’ será uma boa escolha para isso.
• Api-Key: a Chave de API associada ao nome de usuário que você usou no primeiro par chave/valor
• Content-Type: multipart/form-data

A seção Cabeçalhos concluída deve parecer semelhante a esta, mas com a chave de API do seu usuário:

Clique no botão Continuar para ver os dados recuperados do Discourse para esta solicitação.

Adicionar a etapa de ação final

Depois que seu gatilho e a etapa opcional para recuperar dados do Discourse estiverem configurados, clique no link “Adicionar uma etapa” e selecione “Webhooks by Zapier” no menu de ação. Em seguida, será solicitado que você escolha qual método de solicitação deseja usar em sua solicitação de API ao Discourse.

Aqui estão os tipos de solicitação necessários para os exemplos usados neste tópico:

• adicionar usuário a um grupo: PUT
• conceder insígnia personalizada: POST

Para configurar solicitações de API diferentes dos exemplos deste tópico, consulte a documentação da API do Discourse para ver se há um exemplo da solicitação que você deseja fazer. Se não encontrar um exemplo lá, leia Como fazer engenharia reversa da API do Discourse para aprender a encontrar a URL e o método de solicitação para a ação que deseja executar. Depois de encontrar o método de solicitação, selecione-o no menu de ação.

Observação: se sua solicitação usar o método DELETE, selecione “Solicitação Personalizada” no menu de ação.

Configurar a etapa de ação final

A seção Cabeçalhos da ação pode ser configurada da mesma forma para todas as solicitações de API. Consulte a seção ‘Autenticar a solicitação’ deste tópico para obter detalhes. Se você adicionou a etapa opcional para recuperar detalhes do Discourse, pode configurar a seção Cabeçalhos da ação final exatamente da mesma forma que fez para aquela etapa.

Depois que os pares chave/valor do Cabeçalho forem adicionados, você precisará preencher os campos URL e Dados do formulário para sua solicitação de API.

Adicionar usuário a um grupo

Para adicionar um usuário a um grupo, uma solicitação PUT é feita para /groups/<group_id>/members.json. A maneira mais fácil de encontrar o ID de um grupo é visitar a página do grupo pela interface do usuário do Discourse e, em seguida, inserir .json na URL na barra de endereços do seu navegador. Por exemplo, meu site tem um grupo “suporte” em https://demo.scossar.com/g/support. Ao acessar https://demo.scossar.com/g/support.json, posso ver que o ID do grupo é 41. A URL base do meu fórum é https://demo.scossar.com. A URL na minha etapa de ação final para adicionar usuários a um grupo é definida como https://demo.scossar.com/groups/41/members.json.

A solicitação para adicionar usuários a um grupo requer um parâmetro: uma lista de nomes de usuário separada por vírgulas. Na seção Dados do formulário, insira “usernames” como a chave. Em seguida, clique no ícone “Inserir um Campo” para pesquisar a propriedade de nome de usuário que foi passada do gatilho ou da etapa de ação GET opcional.

No meu caso, quero o nome de usuário recuperado pela etapa GET, então expando o menu “GET” e selecio Username no menu suspenso.

Todas as outras seções do formulário podem permanecer com seus valores padrão.

Clique no botão Continuar e, em seguida, teste sua etapa. Se o usuário que você passou pelas etapas anteriores existir no seu site do Discourse e ele ainda não for membro do grupo que você selecionou, ele deverá ser adicionado ao grupo ao testar a etapa.

Se tudo funcionar conforme o esperado, ative seu Zap.

Conceder uma insígnia personalizada

Para conceder uma insígnia personalizada a um usuário, uma solicitação POST é feita para a URL base do seu fórum + /user_badges. Para o meu site, a URL para conceder insígnias é https://demo.scossar.com/user_badges. O campo URL concluído no Zapier fica assim:

A seção Dados do formulário requer dois pares chave/valor. Adicione uma chave “username” e defina-a como o campo que retorna o nome de usuário do usuário. Adicione uma chave “badge_id” e defina-a como o ID da insígnia que você deseja conceder. Você pode encontrar o ID da insígnia acessando sua página Admin / Insígnias e selecionando a insígnia no menu lateral esquerdo. Você verá o ID da insígnia como o último valor da URL na barra de endereços do seu navegador.

A insígnia que estou concedendo tem um ID de 105, então minha seção Dados concluída fica assim:

Certifique-se de ter configurado a seção Cabeçalhos do formulário e, em seguida, clique em Continuar. Em seguida, clique no botão Enviar teste para testar seu Zap. O usuário que você passou pelas etapas anteriores deverá receber a insígnia.

Se tudo estiver funcionando corretamente, ative o Zap.

[aj_silvers]

Can this workflow be used to automatically create an account for a new user and add them to a specific discourse group?

The use case here is someone buys a training product, I want to automatically then add them to the relevant discourse sub forum for that product.

I can get the new customer data into Zapier but the regular discourse zap doesn’t have create account capabilities - just wondering if I can do this via the API and webhook link as you describe in this example.

Thanks!

[simon]

@aj_silvers

The use case here is someone buys a training product, I want to automatically then add them to the relevant discourse sub forum for that product.

The easiest approach would be to send an invite email to the person after they make a purchase. You can setup the invite so that the user is automatically added to a Discourse group when they accept the invitation. See Automate sending Discourse invite emails with Zapier for details.

If sending invites is not an option for you, it should be possible to use a Zapier webhook to create a Discourse user. The Discourse API Docs give details about the request to create a user.

[aj_silvers]

Thanks @simon I’ll try the email invite. No doubt some people won’t get it/find it/open it but it’s the easier option for sure.

Appreciate the speedy response too!

[pfaffman (Jay Pfaffman)]

It’s often easier to have whatever is selling the thing make the discourse api calls directly.

[Nacho_Caballero]

Is there a reason why this works for me when I do it in Zapier, but I get an empty response when I try to do my own fetch request?

I’m using ObservableHQ, but the idea is the same. Shouldn’t this work?:

fetch("https://mycommunity.com/g.json", {
  headers: {
    "Content-Type": "multipart/form-data",
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
  method: "GET",
  mode: "no-cors"
})

[simon]

Are you able to get any API requests to Discourse working with calls in that format with ObservableHQ? It seems that there must be something wrong with the format of the request.

You can also double check requests by making curl calls from your terminal, or by using Postman.

[Nacho_Caballero]

OK, I figured out what I needed to do:

1. Install cors-anywhere locally and run the server
2. Modify the request to include the reverse proxy before the API endpoint and call the json method in the Fetch Response object:

await (fetch("http://localhost:8080/mycommunity.com/g.json", {
  headers: {
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
})).json()

[markersocial]

Just going to leave this here, might be worth checking out:

n8n.io - AI workflow automation tool

GitHub - n8n-io/n8n: Fair-code workflow automation platform with native...

[Bernstein (Carey Bernstein)]

@simon

To grant a custom badge to a user, a POST request is made to your forum’s base URL + /user_badges .

Hi @simon, thanks for this how to. I’m setting this up in Zapier using but my forum doesn’t have this URL for granting badges.

I’m wondering, is this not a standard URL for all Discourse installs, or has the URL possibly changed in a recent update?

[simon]

@Bernstein

my forum doesn’t have this URL for granting badges.

It should have. It is not a URL that can be visited through the Discourse user interface though. I just double checked the route on my site by following the steps outlined here: How to reverse engineer the Discourse API. Based on that, it looks like the details given in the topic are still up to date.

[Bernstein (Carey Bernstein)]

It was, no surprise, my own error.