Izvajanje odhodnih klicev (API)

Iz lastne kode sprožite odhodni klic, ki ga vodi umetna inteligenca — za ankete, nadaljnje stike ali potrditvene poteke.

Odhodno klicanje vam omogoča, da ThunderPhone posredujete ciljno številko in konfiguracijo agenta, AI pa opravi klic v vašem imenu. Običajni primeri uporabe:

• Potrditve terminov
• Povratni klici za ankete
• Nadaljnji klici ob »drugem poskusu« po neodgovorjenem klicu
• Obvestila v slogu dispečerskih obvestil

Predpogoji#

1. Izberite številko, omogočeno za odhodne klice

   Uporabite številko, ki jo imate v lasti prek VoIP-povezave, ali zaprosite za dovoljenje za uporabo svojih številk ThunderPhone za odhodne klice na strani Telefonske številke. Številke ThunderPhone so sprva omogočene samo za dohodne klice. ThunderPhone vsako zahtevo pregleda ročno; po odobritvi lahko te številke opravljajo klice do odobrene dnevne omejitve (ki se ponastavi ob 00:00 UTC) in izvajajo kampanje, vi pa lahko zaprosite za višjo omejitev. VoIP-številke strank nimajo dnevne omejitve, zato jih priporočamo za odhodne klice. Glejte Uporabite svoje številke.

2. Ustvarite agenta

   Poziv, prilagojen odhodnim klicem, se običajno začne tako, da se agent predstavi in navede svoj namen — "Pozdravljeni, tukaj Acme, kličemo, da potrdimo vaš jutrišnji termin ob 15.00 …" Nastavite outbound_speak_order na agent_first (privzeto).

3. Ohranite pozitivno stanje

   Odhodni klici vrnejo 402 Payment Required, če je stanje ≤ $0.00. Dodajte sredstva ali omogočite samodejno ponovno polnjenje v Organizacija → Nastavitve obračunavanja na nadzorni plošči. Z vašim ključem sk_live_ lahko preverite stanje z GET /v1/billing, vendar z njim ne morete dodati sredstev ali spremeniti samodejnega ponovnega polnjenja.

Opravite klic s shranjenim agentom#

Najpreprostejši način — sklicujte se na agenta po ID-ju:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "agent_id":    12
  }'

Odgovor:

{ "call_id": 987654321, "status": "initiated" }

Opravite klic z vdelano konfiguracijo#

Če želite enkraten poziv, ki ga ni vredno shraniti kot agenta, namesto tega posredujte config. Oblika se ujema s shemo odgovora spletnega kljuka call.incoming:

curl -X POST https://api.thunderphone.com/v1/call \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from_number": "+15551234567",
    "to_number":   "+14155552671",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'

Spremljanje klica#

Hkrati se naročite na telephony.complete webhook — najhitrejši način, da izveste, da se je klic končal. Če ne morete sprejemati dohodnih webhookov, vsakih nekaj sekund preverite GET /v1/calls/{call_id}; zapis po koncu klica vključuje end_reason, duration_seconds in URL posnetka.

Če je vaš agent nastavljen za pridobivanje strukturiranih podatkov po klicu, so ti podatki dostavljeni ločeno po zaključku finalizacije.

Posredovanje spremenljivk posameznega klica shranjenemu agentu#

Shranjeni agenti lahko v besedilu poziva uporabljajo označbe mesta, kot sta {{name}} ali {{name|there}}. Ko opravite odhodni klic z agent_id, posredujte variables z vrednostmi za ta klic:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Uporabite vrednosti nizov, katerih ključi so imena označb mesta. Te spremenljivke veljajo za shranjene agente; primer vdelane config v tem vodniku jih ne uporablja.

Primeri napak, ki jih je vredno obravnavati#

Za celoten stabilni seznam kod upravičenosti in obe obliki odziva 409 glejte referenco odhodnih klicev. Če aktivna številka postane neupravičena po sprejetju zahteve, vendar pred izvedbo klica, končno preverjanje vrne vsebino 409, pri kateri ponovni poskus ni mogoč.

Nadzor časa čakanja#

Odhodne klice, ki trajajo dolgo, ker se klicana oseba počasi odziva (drevesa IVR, čakalne vrste), lahko omejite z max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Agent prekine klic, če v zadnjih N sekundah ni prejel človeškega zvoka. Privzeta vrednost je 900 sekund (15 minut).

Naslednji koraki#