---
title: "Use o ThunderPhone com o n8n"
description: "Instale o nó do ThunderPhone para n8n, conecte uma chave de API do servidor e crie um fluxo de trabalho executado sempre que uma chamada terminar."
---

[n8n](https://n8n.io) é uma ferramenta de automação de fluxos de trabalho. O pacote do ThunderPhone
para n8n adiciona dois nós:

- **ThunderPhone Trigger** inicia um fluxo de trabalho quando uma chamada termina (**Chamada
  concluída**) ou quando uma execução de avaliação de chamada é concluída (**Chamada avaliada**).
- **ThunderPhone** realiza chamadas de saída, adiciona contatos a campanhas e
  as inicia, obtém chamadas com suas transcrições e gravações e lista seus
  agentes e números de telefone.

É um nó da comunidade verificado, listado em
[ThunderPhone no n8n](https://n8n.io/integrations/thunderphone/).

## Instale o nó

No editor do n8n, clique em **+** para abrir o painel de nós e pesquise por
**ThunderPhone**. Talvez o proprietário da instância precise configurar nós verificados antes
que outros usuários possam adicioná-los.

No n8n auto-hospedado, você também pode instalar pelo nome do pacote: abra
**Configurações > Nós da comunidade** e instale `n8n-nodes-thunderphone`. Verifique os riscos dos nós da comunidade e a política da sua instância
antes de instalar.

## Crie uma chave de API de servidor

<Steps>
  <Step title="Abra a aba Chaves">
    No ThunderPhone, acesse **Organização → Chaves** e clique em **Criar chave**.
  </Step>
  <Step title="Dê um nome">
    Use um nome que indique onde a chave é usada, como "n8n".
  </Step>
  <Step title="Copie-a agora">
    O segredo completo `sk_live_...` é exibido uma única vez. Copie-o antes de fechar a
    caixa de diálogo.
  </Step>
</Steps>

Somente um administrador ou proprietário pode criar a chave, e o ThunderPhone trata as solicitações
feitas com ela como se viessem dessa pessoa. O gatilho e as
operações de campanha exigem que essa pessoa mantenha a função de administrador ou proprietário.
[Criar uma chave de API de servidor](/pt/guides/api-keys) aborda rotação e revogação.

## Adicione a credencial no n8n

1. No n8n, crie uma credencial do tipo **ThunderPhone API**.
2. Cole a chave em **Chave de API**.
3. Salve-a e execute o teste da credencial. O teste lê uma chamada da sua
   organização com `GET /v1/calls?limit=1`.

## Crie um primeiro fluxo de trabalho

Este fluxo de trabalho adiciona uma linha a uma Planilha Google sempre que uma chamada termina.

<Steps>
  <Step title="Adicione o gatilho">
    Adicione **ThunderPhone Trigger**, selecione sua credencial de API do ThunderPhone e
    defina **Event** como **Call Completed**.
  </Step>
  <Step title="Obtenha a chamada">
    Adicione um nó **ThunderPhone**. Defina **Resource** como **Call**, **Operation**
    como **Get** e **Call ID** como a expressão `{{ $json.data.call_id }}`.
    A saída é o [registro da chamada](/api-reference/calls), além de `transcripts`
    e `recording_url`, um link temporário que é `null` quando a chamada não tem
    gravação.
  </Step>
  <Step title="Acrescente uma linha">
    Adicione um nó do Planilhas Google que acrescente uma linha e mapeie as colunas desejadas
    da saída de Get Call (consulte a tabela abaixo).
  </Step>
  <Step title="Ative o fluxo de trabalho">
    Salve e ative. O gatilho registra sua URL de produção como um endpoint de webhook
    na sua organização do ThunderPhone. Desativar o fluxo de trabalho exclui esse endpoint.
  </Step>
  <Step title="Teste">
    Abra um agente no builder, clique em **Falar** e encerre a chamada. As chamadas de
    teste do builder são entregues como `web.complete`, um dos dois eventos por trás de
    Call Completed, portanto o fluxo de trabalho é executado e uma linha é exibida.
  </Step>
</Steps>

Colunas úteis:

| Coluna | Expressão |
|---|---|
| ID da chamada | `{{ $json.call_id }}` |
| Direção | `{{ $json.direction }}` |
| De | `{{ $json.from_number }}` |
| Para | `{{ $json.to_number }}` |
| Iniciada em | `{{ $json.start_time }}` |
| Duração (s) | `{{ $json.duration_seconds }}` |
| Status | `{{ $json.status }}` |
| Motivo do encerramento | `{{ $json.end_reason }}` |
| Link da chamada | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` |

O link da chamada abre a chamada no painel do ThunderPhone para membros da
sua organização, com a transcrição e a gravação, portanto a planilha não
precisa armazenar nenhuma delas.

Para adicionar a transcrição mesmo assim, mapeie
`{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`.
A URL da gravação expira, portanto armazene o ID da chamada e execute Get Call novamente quando
precisar de um link atualizado. Transcrições, resumos e gravações de chamadas podem conter
informações pessoais ou de saúde. Envie-os apenas para aplicativos que sua organização tenha
permissão de usar para esses dados, sob um BAA quando houver informações de saúde
envolvidas, e mantenha apenas os campos necessários.

<Note>
  O ThunderPhone entrega eventos com `POST` à **URL de produção** do gatilho,
  portanto sua instância do n8n deve estar acessível pela internet via HTTPS,
  e o fluxo de trabalho deve estar ativo. O gatilho verifica o HMAC
  `X-ThunderPhone-Signature` em cada solicitação e responde `401` a
  qualquer solicitação não assinada ou inválida.
</Note>

O gatilho produz o evento completo: `type`, `event_id` e `data`. Consulte
[`telephony.complete` / `web.complete`](/pt/webhooks/call-complete) e
[`call.graded`](/pt/webhooks/events) para ver todos os campos. A entrega ocorre pelo menos uma vez,
e `event_id` permanece igual entre as tentativas de um mesmo evento, portanto verifique-o antes
de uma etapa que não deve ser repetida.

## Faça chamadas de saída com segurança

**Fazer chamada de saída** (Recurso **Chamada de saída**, Operação **Fazer chamada**)
recebe:

| Campo | Significado |
|---|---|
| Nome ou ID do agente | Um agente salvo. O menu suspenso lista seus agentes. |
| Nome ou ID do número de telefone | O número de origem. O menu suspenso lista apenas números habilitados para chamadas de saída. |
| Número de destino | Destino no formato E.164, por exemplo, `+14155552671`. |
| Variáveis | Objeto JSON de valores para marcadores no prompt do agente. |
| Chave de idempotência | Um ID estável do registro ou evento de origem. Obrigatório. |

Mapeie a **Chave de idempotência** para um ID do que causou a execução, como o
ID de um registro de CRM ou o `event_id` do gatilho. O nó envia
`n8n:<node ID>:<your value>`, portanto:

- Uma nova tentativa automática ou **Repetir execução** envia a mesma chave, e
  o ThunderPhone retorna a chamada original com `idempotent_replay: true`
  em vez de discar novamente.
- Dois nós do ThunderPhone alimentados pelo mesmo registro enviam chaves diferentes.
- Um valor em branco falha antes do envio de qualquer solicitação.

Evite carimbos de data e hora, valores aleatórios e IDs de execução ou de fluxo de trabalho do n8n. Um novo
valor em uma nova tentativa faz uma segunda chamada real. A chave inteira pode ter no máximo 128
caracteres. Reutilizar uma chave com outro agente, número ou variáveis falha
com um conflito.

**Campanhas.** **Adicionar contatos** (Recurso **Campanha**) adiciona contatos a uma
campanha em rascunho. Recebe um ID de campanha e uma matriz JSON de contatos. Cada contato precisa de `phone_number`; outras chaves
se tornam variáveis da chamada. O nó falha quando todos os contatos são rejeitados e define
`partial_success: true` quando apenas alguns são. **Iniciar** exige a caixa de seleção
que confirma que a campanha faz chamadas reais e consome créditos do ThunderPhone.
Consulte [Campanhas de saída](/pt/guides/outbound-campaigns).

Antes de um fluxo de trabalho iniciar chamadas:

- Se o ThunderPhone solicitar que sua organização confirme que suas chamadas de saída
  seguem a TCPA e outras leis de chamadas, um administrador deverá registrar essa
  confirmação primeiro no painel.
- O número de origem deve estar habilitado para chamadas de saída. Números trazidos
  da sua própria operadora se qualificam após a verificação. Os números do ThunderPhone começam
  apenas para chamadas recebidas e podem ser aprovados para uso em chamadas de saída: um administrador solicita isso
  na página Números de telefone. Consulte
  [Obter um número de telefone](/pt/guides/get-a-phone-number).
- Sua organização é responsável por ter consentimento para ligar para cada número
  e por seguir as leis de chamadas aplicáveis. Consulte
  [Leis de chamadas de saída](/pt/guides/outbound-calling-laws).

## Exemplos de fluxos de trabalho

- **Contatos do CRM para uma campanha.** Adicione contatos do CRM a uma campanha do ThunderPhone
  em rascunho e inicie a campanha quando alguém aprovar a lista.
- **Chamada concluída para o registro do cliente.** Em Chamada concluída, execute Obter chamada
  e salve a transcrição e o link da gravação no registro de cliente correspondente.
- **Notas baixas para revisão.** Em Chamada avaliada, filtre por
  `{{ $json.data.grade.score }}` e encaminhe chamadas com baixa pontuação para uma fila de revisão
  com o ID da chamada e os detalhes da avaliação. Uma chamada pode ser avaliada mais de uma vez,
  e cada execução de avaliação concluída aciona o gatilho, portanto mantenha apenas o `graded_at`
  mais recente para cada ID de chamada.

Transcrições, resumos e gravações de chamadas podem conter informações pessoais ou de saúde.
Envie-os apenas para aplicativos que sua organização tem permissão para usar com esses
dados, nos termos de um BAA quando houver informações de saúde envolvidas, e mantenha apenas
os campos necessários.

<Note>
  Vai enviar os mesmos eventos de chamada para seu próprio servidor? Consulte
  [Endpoints de webhook](/pt/webhooks/endpoints).
  [Fazer chamadas de saída](/pt/guides/place-outbound-calls) aborda a API por trás de
  Fazer chamada de saída.
</Note>