---
title: "Používanie ThunderPhone s n8n"
description: "Nainštalujte uzol ThunderPhone pre n8n, pripojte kľúč serverového API a vytvorte pracovný postup, ktorý sa spustí pri každom ukončení hovoru."
---

[n8n](https://n8n.io) je nástroj na automatizáciu pracovných postupov. Balík ThunderPhone
pre n8n pridáva dva uzly:

- **ThunderPhone Trigger** spustí pracovný postup po ukončení hovoru (**Hovor
  dokončený**) alebo po dokončení vyhodnotenia hovoru (**Hovor vyhodnotený**).
- **ThunderPhone** uskutočňuje odchádzajúce hovory, pridáva kontakty do kampaní
  a spúšťa ich, získava hovory s ich prepisom a nahrávkou a zobrazuje zoznam
  vašich agentov a telefónnych čísel.

Ide o overený komunitný uzol uvedený na stránke
[ThunderPhone na n8n](https://n8n.io/integrations/thunderphone/).

## Nainštalujte uzol

V editore n8n kliknutím na **+** otvorte panel uzlov a vyhľadajte
**ThunderPhone**. Vlastník inštancie možno bude musieť nastaviť overené uzly,
kým ich budú môcť pridať ostatní používatelia.

V samostatne hostovanom n8n môžete uzol nainštalovať aj podľa názvu balíka: otvorte
**Nastavenia > Komunitné uzly** a nainštalujte `n8n-nodes-thunderphone`. Pred inštaláciou
skontrolujte riziká komunitných uzlov a pravidlá svojej inštancie.

## Vytvorte serverový kľúč API

<Steps>
  <Step title="Otvorte kartu Kľúče">
    V ThunderPhone prejdite do **Organizácia → Kľúče** a kliknite na **Vytvoriť kľúč**.
  </Step>
  <Step title="Pomenujte ho">
    Použite názov, ktorý uvádza, kde sa kľúč používa, napríklad „n8n“.
  </Step>
  <Step title="Skopírujte ho teraz">
    Úplný tajný kľúč `sk_live_...` sa zobrazí iba raz. Skopírujte ho pred zatvorením
    dialógového okna.
  </Step>
</Steps>

Kľúč môže vytvoriť iba správca alebo vlastník a ThunderPhone požiadavky
uskutočnené s týmto kľúčom považuje za požiadavky od danej osoby. Spúšťač a operácie
kampaní vyžadujú, aby táto osoba naďalej mala rolu správcu alebo vlastníka.
[Viac o vytvorení serverového kľúča API](/sk/guides/api-keys) zahŕňa rotáciu a zrušenie.

## Pridajte prihlasovacie údaje v n8n

1. V n8n vytvorte prihlasovacie údaje typu **ThunderPhone API**.
2. Vložte kľúč do poľa **Kľúč API**.
3. Uložte ich a spustite test prihlasovacích údajov. Test načíta jeden hovor z vašej
   organizácie pomocou `GET /v1/calls?limit=1`.

## Vytvorenie prvého workflow

Tento workflow pridá riadok do Google Sheets pri každom ukončení hovoru.

<Steps>
  <Step title="Pridanie spúšťača">
    Pridajte **ThunderPhone Trigger**, vyberte svoje poverenie ThunderPhone API a
    nastavte **Event** na **Call Completed**.
  </Step>
  <Step title="Získanie hovoru">
    Pridajte uzol **ThunderPhone**. Nastavte **Resource** na **Call**, **Operation**
    na **Get** a **Call ID** na výraz `{{ $json.data.call_id }}`.
    Výstupom je [záznam hovoru](/api-reference/calls) spolu s položkami `transcripts`
    a `recording_url`, čo je krátkodobý odkaz s hodnotou `null`, keď hovor nemá
    nahrávku.
  </Step>
  <Step title="Pridanie riadka">
    Pridajte uzol Google Sheets, ktorý pridáva riadok, a namapujte požadované
    stĺpce z výstupu Get Call (pozrite si tabuľku nižšie).
  </Step>
  <Step title="Aktivovanie workflow">
    Uložte a aktivujte workflow. Spúšťač zaregistruje svoju produkčnú URL ako
    endpoint webhooku vo vašej organizácii ThunderPhone. Deaktivovaním workflow
    sa tento endpoint odstráni.
  </Step>
  <Step title="Testovanie">
    Otvorte agenta v nástroji na vytváranie, kliknite na **Talk** a ukončite hovor. Testovacie
    hovory z nástroja na vytváranie sa doručujú ako `web.complete`, jedna z dvoch udalostí
    pre Call Completed, takže sa workflow spustí a zobrazí sa riadok.
  </Step>
</Steps>

Užitočné stĺpce:

| Stĺpec | Výraz |
|---|---|
| ID hovoru | `{{ $json.call_id }}` |
| Smer | `{{ $json.direction }}` |
| Od | `{{ $json.from_number }}` |
| Komu | `{{ $json.to_number }}` |
| Začiatok | `{{ $json.start_time }}` |
| Trvanie (s) | `{{ $json.duration_seconds }}` |
| Stav | `{{ $json.status }}` |
| Dôvod ukončenia | `{{ $json.end_reason }}` |
| Odkaz na hovor | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` |

Odkaz na hovor otvorí hovor na paneli ThunderPhone členom vašej
organizácie spolu s jeho prepisom a nahrávkou, takže ich tabuľka nemusí
uchovávať.

Ak chcete pridať aj prepis, namapujte
`{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`.
Platnosť URL nahrávky vyprší, preto uložte ID hovoru a znova spustite Get Call, keď
potrebujete nový odkaz. Prepisy hovorov, súhrny a nahrávky môžu obsahovať
osobné alebo zdravotné údaje. Posielajte ich iba do aplikácií, ktoré vaša organizácia
smie používať pre tieto údaje, na základe BAA, ak ide o zdravotné údaje,
a uchovávajte iba potrebné polia.

<Note>
  ThunderPhone doručuje udalosti metódou `POST` na **Production
  URL** spúšťača, preto musí byť vaša inštancia n8n dostupná z internetu cez HTTPS
  a workflow musí byť aktívny. Spúšťač overuje HMAC
  `X-ThunderPhone-Signature` pri každej požiadavke a na každú nepodpísanú alebo
  neplatnú požiadavku odpovedá `401`.
</Note>

Spúšťač poskytuje úplnú udalosť: `type`, `event_id` a `data`. Všetky polia nájdete v
[`telephony.complete` / `web.complete`](/sk/webhooks/call-complete) a
[`call.graded`](/sk/webhooks/events). Doručenie je aspoň raz
a `event_id` zostáva rovnaké pri opakovaných pokusoch o doručenie jednej udalosti, preto ho overte pred
krokom, ktorý sa nesmie opakovať.

## Bezpečné uskutočňovanie odchádzajúcich hovorov

**Uskutočniť odchádzajúci hovor** (Zdroj **Odchádzajúci hovor**, Operácia **Uskutočniť**)
vyžaduje:

| Pole | Význam |
|---|---|
| Názov alebo ID agenta | Uložený agent. Rozbaľovací zoznam obsahuje vaše agenty. |
| Názov alebo ID telefónneho čísla | Číslo, z ktorého sa volá. Rozbaľovací zoznam obsahuje iba čísla povolené na odchádzajúce hovory. |
| Číslo príjemcu | Cieľové číslo vo formáte E.164, napr. `+14155552671`. |
| Premenné | Objekt JSON s hodnotami pre zástupné symboly vo výzve agenta. |
| Kľúč idempotentnosti | Stabilné ID z nadradeného záznamu alebo udalosti. Povinné. |

Namapujte **Kľúč idempotentnosti** na ID z toho, čo spustilo beh, napríklad
ID záznamu CRM alebo `event_id` spúšťača. Uzol odošle
`n8n:<node ID>:<your value>`, takže:

- Automatické opakovanie alebo **Zopakovať vykonanie** odošle rovnaký kľúč a
  ThunderPhone vráti pôvodný hovor s hodnotou `idempotent_replay: true`
  namiesto opätovného vytáčania.
- Dva uzly ThunderPhone, ktoré dostanú rovnaký záznam, odošlú odlišné kľúče.
- Prázdna hodnota zlyhá pred odoslaním akejkoľvek požiadavky.

Nepoužívajte časové pečiatky, náhodné hodnoty ani ID vykonania alebo pracovného
postupu n8n. Nová hodnota pri opakovaní uskutoční druhý skutočný hovor. Celý
kľúč môže mať najviac 128 znakov. Opätovné použitie kľúča s iným agentom,
číslom alebo premennými zlyhá pre konflikt.

**Kampane.** **Pridať kontakty** (Zdroj **Kampaň**) pridá kontakty do
konceptu kampane. Vyžaduje ID kampane a pole kontaktov JSON. Každý kontakt
potrebuje `phone_number`; ostatné kľúče sa stanú premennými hovoru. Uzol zlyhá,
keď sú odmietnuté všetky kontakty, a nastaví `partial_success: true`, keď sú
odmietnuté iba niektoré. **Spustiť** vyžaduje začiarkavacie políčko potvrdzujúce,
že kampaň uskutočňuje skutočné hovory a využíva kredity ThunderPhone. Pozrite si
[Odchádzajúce kampane](/sk/guides/outbound-campaigns).

Predtým, než pracovný postup začne uskutočňovať hovory:

- Ak ThunderPhone požiada vašu organizáciu o potvrdenie, že jej odchádzajúce
  hovory sú v súlade so zákonom TCPA a ďalšími zákonmi o volaní, správca musí
  toto potvrdenie najprv zaznamenať na ovládacom paneli.
- Číslo, z ktorého sa volá, musí byť povolené na odchádzajúce hovory. Čísla,
  ktoré prinesiete od vlastného operátora, sú oprávnené po overení. Čísla
  ThunderPhone sú spočiatku iba na prichádzajúce hovory a môžu byť schválené na
  odchádzajúce použitie: správca o to požiada na stránke Telefónne čísla.
  Pozrite si [Získanie telefónneho čísla](/sk/guides/get-a-phone-number).
- Vaša organizácia zodpovedá za získanie súhlasu na volanie na každé číslo
  a za dodržiavanie príslušných zákonov o volaní. Pozrite si
  [Zákony o odchádzajúcom volaní](/sk/guides/outbound-calling-laws).

## Príklady pracovných postupov

- **Kontakty CRM do kampane.** Pridajte kontakty CRM do konceptu kampane
  ThunderPhone a potom kampaň spustite, keď niekto schváli zoznam.
- **Dokončený hovor do záznamu zákazníka.** Po dokončení hovoru spustite
  Získať hovor a uložte prepis a odkaz na nahrávku do zodpovedajúceho záznamu
  zákazníka.
- **Nízke hodnotenia na kontrolu.** Po vyhodnotení hovoru filtrujte podľa
  `{{ $json.data.grade.score }}` a hovory s nízkym skóre presmerujte do frontu
  na kontrolu s ID hovoru a podrobnosťami hodnotenia. Hovor môže byť vyhodnotený
  viackrát a každý dokončený beh hodnotenia spustí spúšťač, preto pre každé ID
  hovoru ponechajte iba najnovšie `graded_at`.

Prepisy hovorov, súhrny a nahrávky môžu obsahovať osobné alebo zdravotné
informácie. Odosielajte ich iba do aplikácií, ktoré vaša organizácia smie
používať pre tieto údaje, na základe dohody BAA, ak ide o zdravotné informácie,
a uchovávajte iba polia, ktoré potrebujete.

<Note>
  Odosielate rovnaké udalosti hovorov na vlastný server? Pozrite si
  [Koncové body webhookov](/sk/webhooks/endpoints).
  [Uskutočňovanie odchádzajúcich hovorov](/sk/guides/place-outbound-calls) opisuje API za
  funkciou Uskutočniť odchádzajúci hovor.
</Note>