Integração com o n8n

O n8n é uma ferramenta para criar fluxos de trabalho automáticos (workflows). Há dois caminhos para usá-lo com o Deskwoot. Com um node Webhook no n8n, eventos do Deskwoot como uma nova conversa, uma nova mensagem de cliente ou uma avaliação CSAT iniciam os seus workflows do n8n, para você passar esses dados ao seu CRM, a uma planilha ou aos seus próprios sistemas. O node do Deskwoot para o n8n também age no Deskwoot: os seus workflows respondem, adicionam notas, atribuem, aplicam etiquetas e criam ou atualizam contatos. Você também encontra os dois caminhos em Configurações > Integrações > n8n.

Qual plano você precisa

O node Webhook recebe os eventos de um webhook do Deskwoot. Os webhooks exigem o plano Startup ou superior, e o teste também os inclui. No plano gratuito Hacker, os webhooks não enviam nada.

Um webhook só envia dados para fora do Deskwoot. Para que o n8n responda às mensagens dos clientes como um bot, crie um bot Custom Webhook em Configurações > Bots, o que exige um plano pago (a partir do Startup). Para agir no Deskwoot a partir do n8n, use o node do Deskwoot para o n8n (abaixo). Para o que o node não faz, como resolver uma conversa, chame a API REST do Deskwoot com o node HTTP Request do n8n e um token de API. O node e a API REST exigem um plano Enterprise pago, e um teste não inclui acesso à API. Para criar um token, veja Tokens de API e acesso para desenvolvedores.

O node Webhook no n8n (a partir do Startup)

Configurar no n8n

1. No n8n, abra o seu workflow e adicione um node Webhook como primeiro passo.
2. Em HTTP Method, escolha POST.
3. Deixe Respond em Immediately, para o n8n responder ao Deskwoot na hora.
4. Copie a Production URL do node.

Configurar no Deskwoot

1. Acesse Configurações > Webhooks. Só administradores veem esta página.
2. Clique em Adicionar webhook.
3. Cole a Production URL em URL do endpoint.
4. Em Inscrever-se em eventos, marque os eventos de que o seu workflow precisa. Sem nenhum marcado, o webhook recebe todos os eventos.
5. Clique em Criar webhook.

Depois publique o workflow no n8n: o n8n só escuta a Production URL quando o workflow está publicado. A partir daí cada evento inicia uma execução do workflow, e você vê as execuções na aba Executions.

O que chega ao n8n

Cada evento chega como uma requisição POST com um corpo JSON. Na saída do node Webhook, o corpo traz event (o nome do evento), data (os dados do evento), timestamp e accountId. Os headers trazem x-deskwoot-event com o nome do evento e x-deskwoot-signature. Quando um webhook envia vários eventos, deixe o próximo node verificar event, por exemplo um node If.

Você pode escolher estes eventos: Conversa criada, Conversa atualizada, Conversa atribuída, Conversa resolvida, Mensagem criada, Contato criado, Contato atualizado e CSAT enviado. Os dados de cada evento estão na documentação da API.

Bom saber

• O Deskwoot espera no máximo 10 segundos. Se o n8n não responder a tempo ou responder com um erro, o Deskwoot tenta de novo depois de 5 segundos. Com Respond em Immediately, nem um workflow longo deixa o Deskwoot esperando.
• O n8n precisa ser acessível pela internet via HTTPS. O Deskwoot só envia para endereços HTTPS públicos. O n8n no seu próprio servidor precisa de um endereço HTTPS público, não de um endereço da sua rede interna.
• Use a Production URL, não a Test URL. O Deskwoot sempre envia para o endereço salvo, então ele precisa ser o que o n8n escuta enquanto o workflow está publicado.

O node do Deskwoot para o n8n (Enterprise)

O node do Deskwoot para o n8n é um community node com o nome n8n-nodes-deskwoot. Ele traz 2 nodes: o Deskwoot Trigger, que inicia um workflow quando algo acontece no Deskwoot, e o node Deskwoot, que age no Deskwoot. Ele funciona com o n8n no seu próprio servidor. O n8n Cloud oferece só community nodes que o n8n verificou, e este node ainda não está entre eles.

Instalar e entrar

1. No n8n, vá em Settings > Community Nodes, clique em Install, digite n8n-nodes-deskwoot e instale. Só o owner e os admins do seu n8n veem esta página.
2. No Deskwoot, acesse Configurações > Tokens de API e clique em Criar token. Marque os escopos Leitura e Escrita e crie o token. Copie o token: o Deskwoot mostra ele só uma vez. Só administradores veem esta página.
3. No n8n, crie uma credencial Deskwoot API. Cole o token em API Token. Em Account ID, digite o ID que a mesma página do Deskwoot mostra em O ID da sua conta. Deixe Base URL como está.
4. Salve a credencial. O n8n testa na hora, listando as caixas de entrada do seu workspace.

Se o teste falhar, o token foi revogado ou expirou, o ID da conta é de outro workspace, o workspace não está no plano Enterprise, ou falta ao token o escopo Leitura. Um token MCP para agentes de IA não funciona aqui: crie um token da API REST em Configurações > Tokens de API.

Deskwoot Trigger

Escolha um destes eventos em Event:

• Conversation Created: uma conversa começa, seja porque um cliente escreveu ou porque o seu time a iniciou.
• Customer Message Received: um cliente escreve numa conversa. Respostas e notas do seu time não contam.
• Conversation Assigned: uma conversa ganha um novo responsável. O rodízio (round robin) de uma conversa nova e as regras de automação não disparam esse evento.
• Conversation Resolved: uma conversa é marcada como resolvida.
• Contact Created: alguém do time adiciona um contato no Deskwoot, ou um app adiciona um pela API. Contatos que o Deskwoot cria a partir de mensagens recebidas disparam Conversation Created no lugar.
• Conversation Rated: um cliente avalia uma conversa na pesquisa de satisfação.

Cada evento chega como um item com campos simples. Uma conversa vem com o ID, o número, o link, o status, o assunto, o canal, a caixa de entrada, o responsável, o time, as etiquetas, o nome, o email e o telefone do cliente, e a primeira mensagem do cliente.

Quando você publica o workflow, o trigger inscreve a Production URL dele no evento no Deskwoot, e quando você despublica, o trigger remove essa inscrição. O Deskwoot assina cada evento, e o trigger confere a assinatura, então ninguém mais consegue iniciar o seu workflow pela URL dele. O trigger precisa de:

• Um token criado por um administrador. Só esse token consegue ligar triggers do Deskwoot.
• Um n8n acessível pela internet via HTTPS. Se o n8n roda atrás de um reverse proxy, defina o WEBHOOK_URL do n8n com o endereço público dele.

Node do Deskwoot

Escolha Resource e Operation:

• Conversation > Start: envia uma primeira mensagem a um contato a partir de uma das suas caixas de entrada, por email, telefone ou ID do contato. Funciona onde uma empresa pode escrever primeiro, como email ou SMS. O Deskwoot recusa um início que o canal não consegue entregar (um chat ao vivo, WhatsApp sem um modelo aprovado, ou alguém no Telegram, LINE ou X que nunca escreveu para aquela caixa de entrada), e o node mostra o motivo.
• Conversation > Reply: envia uma resposta ao cliente pelo canal da conversa.
• Conversation > Add Private Note: adiciona uma nota que só o seu time vê.
• Conversation > Assign: atribui uma conversa a um colega, a um time ou aos dois.
• Conversation > Add Label: aplica uma das suas etiquetas a uma conversa.
• Contact > Create or Update: atualiza o contato com este email, ou cria o contato quando não existe nenhum.
• Contact > Find: devolve o contato que melhor corresponde a um email, telefone ou nome.

Você pode pegar o ID da conversa na saída do Deskwoot Trigger. Respostas e notas vindas do n8n mostram o nome da pessoa que criou o token de API. O node também funciona como ferramenta para os agentes de IA do n8n.

Perguntas frequentes

Qual plano eu preciso?

Startup ou superior para o webhook que inicia os seus workflows, e o teste também o inclui. Um bot Custom Webhook, com o qual o n8n responde aos seus clientes, exige um plano pago (a partir do Startup). O node do Deskwoot para o n8n e a API REST exigem um plano Enterprise pago, e um teste não inclui acesso à API.

Por que o meu workflow não inicia?

Verifique se o workflow está publicado no n8n, se o webhook no Deskwoot tem a Production URL e não a Test URL, se o evento está marcado (ou nenhum está) e se o n8n é acessível pela internet via HTTPS. No plano gratuito Hacker, os webhooks não enviam nada.

O n8n pode mudar algo no Deskwoot?

Sim, com o node do Deskwoot para o n8n no plano Enterprise: ele responde, adiciona notas privadas, atribui, aplica etiquetas, inicia conversas e cria ou atualiza contatos. Para o resto, como resolver uma conversa, chame a API REST com o node HTTP Request do n8n, também no Enterprise. O webhook só envia eventos para fora. Sem o Enterprise, um bot Custom Webhook em Configurações > Bots (a partir do Startup) deixa o n8n responder às mensagens dos clientes como um bot.

Por que não consigo publicar um workflow com o Deskwoot Trigger?

Só um token de API criado por um administrador consegue ligar triggers do Deskwoot, porque um trigger recebe os eventos de todas as conversas, como um webhook. Crie o token como administrador e use na credencial Deskwoot API. O n8n também precisa ser acessível pela internet via HTTPS, e um workspace pode ter no máximo 100 dessas inscrições, junto com os gatilhos do app do Deskwoot para o Zapier.

O que acontece quando eu revogo o token?

Todo trigger que esse token ligou para na hora, e as ações do node falham. Crie um novo token, atualize a credencial Deskwoot API, depois despublique e publique o workflow de novo.

Como sei que um evento veio mesmo do Deskwoot?

Cada requisição traz o header x-deskwoot-signature: sha256= seguido do HMAC SHA256 em hex do corpo bruto, assinado com o secret do webhook. O Deskwoot Trigger confere isso para você. No node Webhook, o painel não mostra esse secret, então trate a Production URL como uma senha: o n8n dá a ela um caminho aleatório, e só o Deskwoot deve conhecê-lo. Um webhook criado pela API REST devolve o seu secret uma vez na resposta.

Funciona com o n8n Cloud?

O node Webhook funciona no n8n Cloud e no n8n que você roda no seu próprio servidor. O node do Deskwoot para o n8n funciona só com o n8n no seu próprio servidor, porque o n8n Cloud oferece só community nodes que o n8n verificou. No seu próprio servidor, o n8n precisa de um endereço HTTPS público para o Deskwoot alcançá-lo.

Posso iniciar vários workflows?

Sim. Crie no Deskwoot um webhook para a Production URL de cada workflow, cada um com os seus próprios eventos. Com o node do Deskwoot, cada workflow publicado com um Deskwoot Trigger ganha a sua própria inscrição.

O que acontece se o n8n ficar fora do ar por um tempo?

Os eventos desse período se perdem depois da única nova tentativa, porque o Deskwoot não guarda nada além disso. No Enterprise, você pode recuperar pela API REST, por exemplo listando as conversas ordenadas pela atividade mais recente.