---
title: "Käytä ThunderPhonea n8n:n kanssa"
description: "Asenna ThunderPhone-solmu n8n:lle, yhdistä palvelimen API-avain ja rakenna työnkulku, joka suoritetaan aina puhelun päättyessä."
---

[n8n](https://n8n.io) on työnkulkujen automatisointityökalu. ThunderPhone-paketti
n8n:lle lisää kaksi solmua:

- **ThunderPhone Trigger** käynnistää työnkulun, kun puhelu päättyy (**Puhelu
  päättynyt**) tai puhelun arviointiajo valmistuu (**Puhelu arvioitu**).
- **ThunderPhone** soittaa lähteviä puheluita, lisää yhteystietoja kampanjoihin ja
  käynnistää niitä, hakee puhelut niiden litterointeineen ja tallenteineen sekä
  listaa agenttisi ja puhelinnumerosi.

Se on vahvistettu yhteisösolmu, joka on listattu sivulla
[ThunderPhone n8n:ssä](https://n8n.io/integrations/thunderphone/).

## Asenna solmu

Napsauta n8n-editorissa **+** avataksesi solmupaneelin ja hae
**ThunderPhone**. Instanssin omistajan on ehkä otettava vahvistetut solmut
käyttöön, ennen kuin muut käyttäjät voivat lisätä niitä.

Itse ylläpidetyssä n8n:ssä voit asentaa solmun myös paketin nimellä: avaa
**Asetukset > Yhteisösolmut** ja asenna `n8n-nodes-thunderphone`. Tarkista
yhteisösolmujen riskit ja instanssisi käytäntö ennen asennusta.

## Luo palvelin-API-avain

<Steps>
  <Step title="Avaa Avaimet-välilehti">
    Siirry ThunderPhonessa kohtaan **Organisaatio → Avaimet** ja napsauta **Luo avain**.
  </Step>
  <Step title="Nimeä avain">
    Käytä nimeä, joka kertoo, missä avainta käytetään, esimerkiksi "n8n".
  </Step>
  <Step title="Kopioi avain nyt">
    Koko `sk_live_...`-salaisuus näytetään vain kerran. Kopioi se ennen kuin suljet
    valintaikkunan.
  </Step>
</Steps>

Vain ylläpitäjä tai omistaja voi luoda avaimen, ja ThunderPhone katsoo sillä
tehdyt pyynnöt kyseisen henkilön tekemiksi. Liipaisin ja kampanjatoiminnot
edellyttävät, että henkilöllä säilyy ylläpitäjän tai omistajan rooli.
[Palvelin-API-avaimen luominen](/fi/guides/api-keys) käsittelee avainten kiertoa ja
peruutusta.

## Lisää tunnistetiedot n8n:ään

1. Luo n8n:ssä **ThunderPhone API** -tyyppiset tunnistetiedot.
2. Liitä avain kohtaan **API-avain**.
3. Tallenna se ja suorita tunnistetietojen testi. Testi hakee yhden puhelun
   organisaatiostasi pyynnöllä `GET /v1/calls?limit=1`.

## Rakenna ensimmäinen työnkulku

Tämä työnkulku lisää rivin Google Sheets -taulukkoon aina, kun puhelu päättyy.

<Steps>
  <Step title="Lisää käynnistin">
    Lisää **ThunderPhone-käynnistin**, valitse ThunderPhone API -tunnistetietosi ja
    aseta **Tapahtuma** arvoon **Puhelu päättynyt**.
  </Step>
  <Step title="Hae puhelu">
    Lisää **ThunderPhone**-solmu. Aseta **Resurssi** arvoon **Puhelu**, **Toiminto**
    arvoon **Hae** ja **Puhelun tunnus** lausekkeeseen `{{ $json.data.call_id }}`.
    Tulosteena saat [puhelutietueen](/api-reference/calls) sekä `transcripts`-
    ja `recording_url`-kentät. Jälkimmäinen on lyhytaikainen linkki, jonka arvo on
    `null`, jos puhelusta ei ole tallennetta.
  </Step>
  <Step title="Lisää rivi">
    Lisää Google Sheets -solmu, joka lisää rivin, ja kohdista haluamasi sarakkeet
    Hae puhelu -tulosteesta (katso alla oleva taulukko).
  </Step>
  <Step title="Ota työnkulku käyttöön">
    Tallenna ja ota käyttöön. Käynnistin rekisteröi tuotanto-URL-osoitteensa webhook-
    päätepisteeksi ThunderPhone-organisaatiossasi. Työnkulun poistaminen käytöstä
    poistaa kyseisen päätepisteen.
  </Step>
  <Step title="Testaa">
    Avaa agentti rakentajassa, napsauta **Puhu** ja lopeta puhelu. Rakentajan
    testipuhelut toimitetaan tapahtumana `web.complete`, joka on toinen Puhelu
    päättynyt -tapahtuman kahdesta taustalla olevasta tapahtumasta, joten työnkulku
    suoritetaan ja rivi ilmestyy.
  </Step>
</Steps>

Hyödyllisiä sarakkeita:

| Sarake | Lauseke |
|---|---|
| Puhelun tunnus | `{{ $json.call_id }}` |
| Suunta | `{{ $json.direction }}` |
| Lähettäjä | `{{ $json.from_number }}` |
| Vastaanottaja | `{{ $json.to_number }}` |
| Alkoi | `{{ $json.start_time }}` |
| Kesto (s) | `{{ $json.duration_seconds }}` |
| Tila | `{{ $json.status }}` |
| Päättymissyy | `{{ $json.end_reason }}` |
| Puhelulinkki | `https://app.thunderphone.com/dashboard/call-history/{{ $json.call_id }}` |

Puhelulinkki avaa puhelun ThunderPhone-hallintapaneelissa organisaatiosi
jäsenille litterointeineen ja tallenteineen, joten taulukkoon ei tarvitse
tallentaa kumpaakaan.

Jos haluat lisätä litteroinnin silti, kohdista
`{{ $json.transcripts.filter(t => typeof t.content === 'string').map(t => t.role + ': ' + t.content).join('\n') }}`.
Tallenteen URL-osoite vanhenee, joten tallenna puhelun tunnus ja suorita Hae
puhelu uudelleen, kun tarvitset uuden linkin. Puhelujen litteroinnit, yhteenvedot
ja tallenteet voivat sisältää henkilö- tai terveystietoja. Lähetä niitä vain
sovelluksiin, joita organisaatiosi saa käyttää kyseisille tiedoille, käytä
terveystietojen kohdalla BAA-sopimusta ja säilytä vain tarvitsemasi kentät.

<Note>
  ThunderPhone toimittaa tapahtumat `POST`-pyynnöillä käynnistimen **tuotanto-
  URL-osoitteeseen**, joten n8n-instanssisi on oltava saavutettavissa internetistä
  HTTPS:n kautta ja työnkulun on oltava käytössä. Käynnistin vahvistaa
  `X-ThunderPhone-Signature` HMAC -allekirjoituksen jokaisessa pyynnössä ja vastaa
  `401`-tilakoodilla kaikkiin allekirjoittamattomiin tai virheellisiin pyyntöihin.
</Note>

Käynnistin tuottaa koko tapahtuman: `type`, `event_id` ja `data`. Katso kaikki
kentät kohdista [`telephony.complete` / `web.complete`](/fi/webhooks/call-complete) ja
[`call.graded`](/fi/webhooks/events). Toimitus tapahtuu vähintään kerran, ja
`event_id` pysyy samana yhden tapahtuman uudelleenyrityksissä, joten tarkista se
ennen vaihetta, jota ei saa toistaa.

## Soita lähteviä puheluita turvallisesti

**Soita lähtevä puhelu** (resurssi **Lähtevä puhelu**, toiminto **Soita**)
käyttää seuraavia kenttiä:

| Kenttä | Merkitys |
|---|---|
| Agentin nimi tai tunnus | Tallennettu agentti. Avattava luettelo näyttää agenttisi. |
| Puhelinnumeron nimi tai tunnus | Soittava numero. Avattava luettelo näyttää vain lähteviin puheluihin käyttöön otetut numerot. |
| Vastaanottajan numero | Kohdenumero E.164-muodossa, esim. `+14155552671`. |
| Muuttujat | JSON-objekti agentin kehotteen paikkamerkkien arvoista. |
| Idempotenssiavain | Vakaa tunnus ylävirran tietueesta tai tapahtumasta. Pakollinen. |

Yhdistä **idempotenssiavain** tunnukseen, joka on peräisin suorituksen
aiheuttaneesta lähteestä, kuten CRM-tietueen tunnukseen tai liipaisimen `event_id`-arvoon. Solmu lähettää
`n8n:<node ID>:<your value>`, joten:

- Automaattinen uudelleenyritys tai **Yritä suoritus uudelleen** lähettää saman avaimen, ja
  ThunderPhone palauttaa alkuperäisen puhelun arvolla `idempotent_replay: true`
  soittamisen sijaan.
- Kaksi ThunderPhone-solmua, joille syötetään sama tietue, lähettävät eri avaimet.
- Tyhjä arvo epäonnistuu ennen kuin pyyntöä lähetetään.

Vältä aikaleimoja, satunnaisia arvoja sekä n8n:n suorituksen tai työnkulun tunnuksia. Uusi
arvo uudelleenyrityksessä soittaa toisen todellisen puhelun. Avaimen enimmäispituus on 128
merkkiä. Avaimen uudelleenkäyttö eri agentin, numeron tai muuttujien kanssa epäonnistuu
ristiriitaan.

**Kampanjat.** **Lisää yhteystiedot** (resurssi **Kampanja**) lisää yhteystietoja
luonnoskampanjaan. Se käyttää kampanjatunnusta ja yhteystietojen JSON-taulukkoa. Jokainen yhteystieto tarvitsee `phone_number`-kentän; muut avaimet
muuttuvat puhelumuuttujiksi. Solmu epäonnistuu, kun kaikki yhteystiedot hylätään, ja asettaa
arvon `partial_success: true`, kun vain osa hylätään. **Aloita** edellyttää valintaruudun
vahvistamista siitä, että kampanja soittaa todellisia puheluita ja kuluttaa ThunderPhone
krediittejä. Katso [Lähtevät kampanjat](/fi/guides/outbound-campaigns).

Ennen kuin työnkulku aloittaa puhelut:

- Jos ThunderPhone pyytää organisaatiotasi vahvistamaan, että sen lähtevät puhelut
  noudattavat TCPA:ta ja muita puhelulakeja, järjestelmänvalvojan on ensin tallennettava
  vahvistus hallintapaneelissa.
- Soittava numero on otettava käyttöön lähteviä puheluita varten. Omasta
  operaattoristasi tuodut numerot kelpaavat vahvistamisen jälkeen. ThunderPhone-numerot ovat aluksi
  vain saapuvia puheluita varten, ja ne voidaan hyväksyä lähtevään käyttöön: järjestelmänvalvoja pyytää sitä
  Puhelinnumerot-sivulta. Katso
  [Hanki puhelinnumero](/fi/guides/get-a-phone-number).
- Organisaatiosi vastaa siitä, että sillä on suostumus soittaa kuhunkin numeroon
  ja että se noudattaa sovellettavia puhelulakeja. Katso
  [Lähtevien puheluiden lait](/fi/guides/outbound-calling-laws).

## Esimerkkityönkulut

- **CRM-yhteystiedot kampanjaan.** Lisää CRM-yhteystiedot luonnosvaiheessa olevaan ThunderPhone-kampanjaan,
  käynnistä sitten kampanja, kun joku hyväksyy luettelon.
- **Päättynyt puhelu asiakastietueeseen.** Kun Puhelu päättyi, suorita Hae puhelu
  ja tallenna litterointi ja tallennuslinkki vastaavaan asiakastietueeseen.
- **Matalat arvosanat tarkistukseen.** Kun Puhelu arvioitu, suodata arvolla
  `{{ $json.data.grade.score }}` ja reititä alhaisen pistemäärän puhelut tarkistusjonoon
  puhelutunnuksen ja arvioinnin tietojen kanssa. Puhelu voidaan arvioida useammin kuin kerran,
  ja jokainen valmis arviointisuoritus käynnistää liipaisimen, joten säilytä vain kunkin
  puhelutunnuksen viimeisin `graded_at`.

Puhelulitteroinnit, yhteenvedot ja tallenteet voivat sisältää henkilötietoja tai terveystietoja.
Lähetä niitä vain sovelluksiin, joita organisaatiosi saa käyttää kyseisille tiedoille,
terveystietojen tapauksessa BAA-sopimuksen mukaisesti, ja säilytä vain tarvitsemasi kentät.

<Note>
  Lähetätkö samat puhelutapahtumat omalle palvelimellesi? Katso
  [Webhook-päätepisteet](/fi/webhooks/endpoints).
  [Soita lähteviä puheluita](/fi/guides/place-outbound-calls) käsittelee APIa, joka on
  Soita lähtevä puhelu -toiminnon taustalla.
</Note>