ThunderPhone v3 je zdaj na voljo.Začnite sami, že od 2 ¢/min.Preberite obvestilo

Developer cookbook

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"
    }
  }'

Nadzirajte, kaj se zgodi po zadnjem preverjanju tišine

Enake nastavitve končnega dejanja ob tišini lahko podate tudi v vdelani config, ki jo uporabljajo shranjeni agenti:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "silence_final_action": "hang_up"
  }
}

Z silence_final_action izberite, kaj se zgodi po zadnjem preverjanju tišine. Podate lahko tudi silence_final_message in, kadar je končno dejanje preusmeritev, silence_transfer_destination.

Dodajte seznam besed v vdelano config

Vdelani odhodni klici lahko vključujejo enak seznam words kot shranjeni agenti. To uporabite, kadar želite, da klic upošteva prilagojena pravila izgovorjave ali prepoznavanja brez predhodnega shranjevanja agenta.

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "prompt": "[REDACTED_LITERAL]",
    "voice": "john",
    "product": "spark",
    "words": []
  }
}

Spremljanje klica

Odgovor s časom queued_at pomeni, da je izhodna zmogljivost ThunderPhonea v uporabi: klic se vzpostavi, ko je na voljo zmogljivost, v 10 minutah, in se konča z end_reason outbound_queue_timeout, če zmogljivosti ni. Ni vam treba ponoviti poskusa. Oglejte si klice v čakalni vrsti.

Vzporedno se naročite na Webhook telephony.complete — to je najhitrejši način, da izveste, kdaj se je klic končal. Naročite se lahko tudi na call.status_changed za sprotne posodobitve napredka, kot so izbiranje številke, odgovor, glasovna pošta in spremembe zadržanja. Č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

NapakaRešitev
402 Payment RequiredNapolnite stanje ali omogočite samodejno ponovno polnjenje
400 z code: destination_not_allowedThunderPhone ne kliče te številke: neveljavne številke, številke za klic v sili, številke s posebno tarifo, kratke kode, sankcionirane države ali zvezna država ZDA, ki jo je vaša organizacija blokirala za odhodne klice. Iz številk ThunderPhone so dovoljene običajne številke iz ZDA in Kanade, dovoljene pa so tudi nekatere mednarodne destinacije, ki se zaračunajo po tarifi destinacije. reason pove, katera velja; glejte blokirane destinacije
409 z retryable: false za številko ThunderPhoneUpoštevajte code: na strani Telefonske številke zahtevajte odhodno klicanje, počakajte na pregled v obdelavi ali uporabite drugo ustrezno številko
429 z code: platform_outbound_daily_limit_reachedOrganizacija je porabila današnjo kvoto odhodnih klicev iz številk ThunderPhone. Počakajte na resets_at (00:00 UTC), na strani Telefonske številke zahtevajte višjo omejitev ali kličite s številke v lastni VoIP-povezavi
429 z code: concurrent_call_limit_reachedOrganizacija ima toliko klicev v teku, kolikor znaša njena omejitev sočasnih klicev (privzeto 20, vključno z dohodnimi, odhodnimi, spletnimi in preskusnimi klici). Poskusite znova po številu sekund, navedenem v glavi Retry-After, ali ko se klic konča; za zvišanje omejitve pišite na support@thunderphone.com
429 z code: outbound_queue_fullOrganizacija ima 50 čakajočih klicev v čakalni vrsti. Poskusite znova po številu sekund, navedenem v glavi Retry-After
429 z code: same_number_too_soonIsto to_number ste poklicali pred manj kot 10 sekundami. Poskusite znova po številu sekund, navedenem v glavi Retry-After
409 z retryable: false za VoIP-številko strankeOdpravite stanje, navedeno v code; pri neuspešnih preverjanjih zaženite POST /v1/phone-numbers/{id}/verify-voip
spor idempotentnosti 409Ključ znova uporabite samo z izvirno normalizirano zahtevo ali pošljite nov ključ
404 from_number is not registered to this organizationPotrdite, da se from_number ujema z aktivno telefonsko številko v vaši organizaciji. Ta odgovor vrne tudi številka, ki je že v postopku zagotavljanja, je neuspešna, se sprošča ali je sproščena
500 samo s poljem detailOdhodni trunk ni konfiguriran. Obrnite se na podporo; to ni težava stanja številke, ki bi jo lahko odpravili
502 Bad GatewayPrehodna napaka SIP / LiveKit; lahko varno poskusite znova

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 pri klicu ali z nastavitvijo te vrednosti pri shranjenem agentu:

{
  "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).

Če nastavite max_hold_seconds tako pri shranjenem agentu kot v zahtevi za odhodni klic, se za ta klic uporabi vrednost za posamezni klic.


Naslednji koraki