ThunderPhone v3 je dostupan.Postavite sve sami, već od 2 ¢/min.Pročitajte objavu

Developer cookbook

Upućujte odlazne pozive (API)

Pokrenite odlazni poziv koji vodi AI iz vlastitog koda — ankete, naknadne kontakte ili tijekove potvrde.

Odlazno pozivanje omogućuje vam da ThunderPhoneu predate odredišni broj i konfiguraciju agenta te da AI uputi poziv u vaše ime. Uobičajeni slučajevi upotrebe:

  • Potvrde termina
  • Povratni pozivi za ankete
  • Naknadni kontakt pri „drugom pokušaju” nakon propuštenog poziva
  • Obavijesti u stilu dispečerskih poruka

Preduvjeti

  1. Odaberite broj omogućen za odlazne pozive

    Upotrijebite broj koji posjedujete putem VoIP veze ili zatražite dopuštenje za upotrebu svojih ThunderPhone brojeva za odlazne pozive na stranici Phone Numbers. ThunderPhone brojevi u početku su samo za dolazne pozive. ThunderPhone ručno pregledava svaki zahtjev; nakon odobrenja ti brojevi mogu upućivati pozive do odobrenog dnevnog ograničenja (koje se ponovno postavlja u 00:00 UTC) i pokretati kampanje, a Vi možete zatražiti veće ograničenje. VoIP brojevi korisnika nemaju dnevno ograničenje, stoga ih preporučujemo za odlazne pozive. Pogledajte Upotrijebite vlastite brojeve.

  2. Izradite agenta

    Uputa prilagođena odlaznim pozivima obično počinje tako da se agent predstavi i navede svoju svrhu — "Pozdrav, ovdje Acme, zovemo kako bismo potvrdili Vaš termin za sutra u 15 h…" Postavite outbound_speak_order na agent_first (zadana vrijednost).

  3. Održavajte pozitivan saldo

    Odlazni pozivi vraćaju 402 Payment Required ako je saldo ≤ $0.00. Nadoplatite saldo ili omogućite automatsku nadoplatu u odjeljku Organization → Billing Settings na nadzornoj ploči. Vaš ključ sk_live_ može provjeriti saldo pomoću GET /v1/billing, ali ne može nadoplatiti saldo ni promijeniti automatsku nadoplatu.

Uputite poziv sa spremljenim agentom

Najjednostavniji način — navedite agenta prema identifikatoru:

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

Uputite poziv s ugrađenom konfiguracijom

Ako želite jednokratni prompt koji ne vrijedi spremati kao agenta, umjesto toga proslijedite config. Struktura odgovara shemi odgovora web-dojavnika 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"
    }
  }'

Kontrolirajte što se događa nakon posljednje provjere tišine

Iste postavke završne radnje za tišinu možete proslijediti i u umetnutom config koji koriste spremljeni agenti:

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

Upotrijebite silence_final_action za odabir onoga što se događa nakon posljednje provjere tišine. Možete proslijediti i silence_final_message te, kada je završna radnja prijenos, silence_transfer_destination.

Dodajte popis riječi u umetnuti config

Umetnuti odlazni pozivi mogu sadržavati isti popis words kao i spremljeni agenti. Upotrijebite ovo kada želite da poziv slijedi prilagođena pravila izgovora ili prepoznavanja bez prethodnog spremanja agenta.

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

Pratite poziv

Odgovor s vremenom queued_at znači da je ThunderPhoneov odlazni kapacitet zauzet: poziv se bira kada se oslobodi kapacitet, unutar 10 minuta, i završava s end_reason outbound_queue_timeout ako se kapacitet ne oslobodi. Ne morate ponavljati pokušaj. Pogledajte pozive u redu čekanja.

Istodobno se pretplatite na webhook telephony.complete — najbrži način da saznate da je poziv završio. Možete se pretplatiti i na call.status_changed za ažuriranja napretka uživo, kao što su biranje broja, odgovoreni poziv, govorna pošta i promjene zadržavanja. Ako ne možete primati dolazne webhookove, svakih nekoliko sekundi provjeravajte GET /v1/calls/{call_id}; zapis uključuje end_reason, duration_seconds i URL snimke nakon završetka poziva.

Ako je vaš agent postavljen za izdvajanje strukturiranih podataka nakon poziva, ti se podaci isporučuju zasebno nakon dovršetka finalizacije.

Proslijedite varijable po pozivu spremljenom agentu

Spremljeni agenti mogu upotrebljavati rezervirana mjesta kao što su {{name}} ili {{name|there}} u tekstu upute. Kada upućujete odlazni poziv s agent_id, proslijedite variables s vrijednostima za taj poziv:

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

Upotrijebite vrijednosti niza označene nazivom rezerviranog mjesta. Te se varijable primjenjuju na spremljene agente; primjer umetnutog config u ovom vodiču ne upotrebljava ih.

Načini neuspjeha koje vrijedi obraditi

PogreškaRješenje
402 Payment RequiredDopunite stanje ili omogućite automatsku nadoplatu
400 s code: destination_not_allowedThunderPhone ne poziva taj broj: nevaljane brojeve, brojeve za hitne službe, brojeve s posebnom tarifom, kratke kodove, sankcionirane zemlje ili saveznu državu SAD-a za koju je vaša organizacija blokirala odlazno pozivanje. S brojeva ThunderPhone dopušteni su uobičajeni brojevi u SAD-u i Kanadi, a dopuštena su i neka međunarodna odredišta koja se naplaćuju prema tarifi odredišta. reason navodi koji; pogledajte blokirana odredišta
409 s retryable: false za broj ThunderPhoneSlijedite code: zatražite odlazno pozivanje na stranici Telefonski brojevi, pričekajte provjeru na čekanju ili upotrijebite drugi prihvatljivi broj
429 s code: platform_outbound_daily_limit_reachedOrganizacija je iskoristila današnje odlazne pozive s brojeva ThunderPhone. Pričekajte resets_at (00:00 UTC), zatražite viši limit na stranici Telefonski brojevi ili pozovite s broja na vlastitoj VoIP vezi
429 s code: concurrent_call_limit_reachedOrganizacija ima onoliko poziva u tijeku koliko iznosi njezino ograničenje istodobnih poziva (zadano 20, uključujući dolazne, odlazne, web i testne pozive). Ponovite pokušaj nakon broja sekundi iz zaglavlja Retry-After ili kada poziv završi; pošaljite e-poruku na support@thunderphone.com kako biste povećali limit
429 s code: outbound_queue_fullOrganizacija ima 50 poziva u redu na čekanju. Ponovite pokušaj nakon broja sekundi iz zaglavlja Retry-After
429 s code: same_number_too_soonIsti to_number pozvali ste prije manje od 10 sekundi. Ponovite pokušaj nakon broja sekundi iz zaglavlja Retry-After
409 s retryable: false za korisnički VoIP brojIspravite stanje navedeno u code; za neuspjele provjere pokrenite POST /v1/phone-numbers/{id}/verify-voip
409 sukob idempotentnostiPonovno upotrijebite ključ samo s izvornim normaliziranim zahtjevom ili pošaljite novi ključ
404 from_number is not registered to this organizationPotvrdite da from_number odgovara aktivnom telefonskom broju u vašoj organizaciji. Broj koji se već aktivira, nije uspio, otpušta se ili je otpušten također vraća ovaj odgovor
500 samo s poljem detailNije konfiguriran odlazni trunk. Obratite se podršci; ovo nije problem stanja broja koji možete ispraviti
502 Bad GatewayPrivremeni kvar SIP-a / LiveKit-a; sigurno je ponoviti pokušaj

Pogledajte referencu za odlazne pozive za potpuni stabilni popis kodova prihvatljivosti i oba oblika odgovora 409. Ako aktivni broj postane neprihvatljiv nakon prihvaćanja zahtjeva, ali prije upućivanja poziva, završna provjera vraća sadržaj odgovora 409 koji nije moguće ponovno pokušati.

Upravljanje vremenom čekanja

Odlazni pozivi koji dugo traju jer pozvana strana sporo odgovara (IVR stabla, redovi čekanja) mogu se ograničiti pomoću max_hold_seconds na pozivu ili postavljanjem te vrijednosti na spremljenom agentu:

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

Agent prekida poziv ako u posljednjih N sekundi nije primljen ljudski zvuk. Zadana vrijednost je 900 sekundi (15 minuta).

Ako postavite max_hold_seconds i na spremljenom agentu i u zahtjevu za odlazni poziv, za taj se poziv koristi vrijednost po pozivu.


Sljedeći koraci