ThunderPhone v3 је сада доступан.Почните самостално, већ од 2 ¢/мин.Прочитајте објаву

Developer cookbook

Покрените одлазне позиве (API)

Покрените одлазни позив који води AI из сопственог кода — за анкете, накнадне контакте или токове потврде.

Одлазно позивање Вам омогућава да ThunderPhone-у проследите одредишни број и конфигурацију агента, а да AI обави позив у Ваше име. Уобичајени случајеви употребе:

  • Потврде термина
  • Повратни позиви за анкете
  • Накнадни покушаји након пропуштеног позива
  • Обавештења у стилу диспечерске службе

Предуслови

  1. Изаберите број омогућен за одлазне позиве

    Користите број који поседујете преко VoIP везе или затражите дозволу за коришћење својих ThunderPhone бројева за одлазне позиве на страници Бројеви телефона. ThunderPhone бројеви су у почетку намењени само за долазне позиве. ThunderPhone сваки захтев прегледа ручно; када буде одобрен, ти бројеви могу да упућују позиве до одобреног дневног ограничења (које се ресетује у 00:00 UTC) и покрећу кампање, а можете затражити и веће ограничење. VoIP бројеви клијената немају дневно ограничење, па их препоручујемо за одлазне позиве. Погледајте Користите сопствене бројеве.

  2. Креирајте агента

    Упит прилагођен одлазним позивима обично почиње тако што се агент представи и наведе сврху позива — „Здраво, овде Acme, зовемо да потврдимо ваш термин за сутра у 15 часова…“ Подесите outbound_speak_order на agent_first (подразумевано).

  3. Одржавајте позитивно стање

    Одлазни позиви враћају 402 Payment Required ако је стање ≤ $0.00. Допуните стање или омогућите аутоматску допуну у оквиру Организација → Подешавања наплате на контролној табли. Ваш sk_live_ кључ може да провери стање помоћу GET /v1/billing, али не може да допуни стање нити да промени аутоматску допуну.

Обавите позив са сачуваним агентом

Најједноставнији начин — наведите агента преко ID-а:

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

Одговор:

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

Обавите позив са уграђеном конфигурацијом

Ако желите једнократни упит који не вреди чувати као агента, уместо тога проследите config. Облик одговара шеми одговора 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"
    }
  }'

Контролишите шта се дешава након последње провере тишине

Иста подешавања завршне радње за тишину можете да проследите и у уграђеном config који користе сачувани агенти:

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

Користите silence_final_action да изаберете шта се дешава након последње провере тишине. Такође можете да проследите silence_final_message, а када је завршна радња пренос позива, и silence_transfer_destination.

Додајте листу речи у уграђени config

Уграђени одлазни позиви могу да садрже исту листу words као и сачувани агенти. Користите ово када желите да позив прати прилагођена правила изговора или препознавања без претходног чувања агента.

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

Пратите позив

Одговор са временом queued_at значи да је одлазни капацитет услуге ThunderPhone заузет: позив се бира када се ослободи капацитет, у року од 10 минута, а завршава се са end_reason outbound_queue_timeout ако се капацитет не ослободи. Не морате поново да покушавате. Погледајте позиве у реду.

Паралелно се претплатите на вебхук telephony.complete — најбржи начин да сазнате да је позив завршен. Можете се претплатити и на call.status_changed за ажурирања напретка уживо, као што су бирање броја, јављање, говорна пошта и промене статуса чекања. Ако не можете да прихватате долазне вебхукове, испитујте GET /v1/calls/{call_id} сваких неколико секунди; запис укључује end_reason, duration_seconds и URL снимка када се позив заврши.

Ако је Ваш агент подешен да издваја структуриране податке након позива, ти подаци се испоручују засебно након завршетка финализације.

Проследите променљиве по позиву сачуваном агенту

Сачувани агенти могу да користе чуваре места попут {{name}} или {{name|there}} у тексту упита. Када упутите одлазни позив са agent_id, проследите variables са вредностима за тај позив:

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

Користите вредности стрингова са кључем који одговара називу чувара места. Ове променљиве важе за сачуване агенте; пример уметнутог config у овом водичу их не користи.

Режими отказа које треба обрадити

ГрешкаРешење
402 Payment RequiredДопуните стање или омогућите аутоматску допуну
400 са code: destination_not_allowedThunderPhone не позива тај број: неважеће бројеве, бројеве за хитне случајеве, бројеве са премијум тарифом, кратке кодове, земље под санкцијама или савезну државу САД коју је ваша организација блокирала за одлазне позиве. Са ThunderPhone бројева дозвољени су уобичајени бројеви у САД и Канади, као и нека међународна одредишта, која се наплаћују по тарифи одредишта. reason наводи које; погледајте блокирана одредишта
409 са retryable: false за ThunderPhone бројПратите code: затражите одлазне позиве на страници Бројеви телефона, сачекајте преглед на чекању или користите други подобан број
429 са code: platform_outbound_daily_limit_reachedОрганизација је искористила данашње одлазне позиве са ThunderPhone бројева. Сачекајте resets_at (00:00 UTC), затражите већи лимит на страници Бројеви телефона или позовите са броја на сопственој VoIP вези
429 са code: concurrent_call_limit_reachedОрганизација има онолико позива у току колики је њен лимит истовремених позива (подразумевано 20, укључујући долазне, одлазне, веб и пробне позиве). Покушајте поново након броја секунди из заглавља Retry-After или када се позив заврши; пошаљите е-поруку на support@thunderphone.com да бисте повећали лимит
429 са code: outbound_queue_fullОрганизација има 50 позива у реду који чекају. Покушајте поново након броја секунди из заглавља Retry-After
429 са code: same_number_too_soonПозвали сте исти to_number пре мање од 10 секунди. Покушајте поново након броја секунди из заглавља Retry-After
409 са retryable: false за VoIP број клијентаИсправите стање наведено у code; у случају неуспеха верификације покрените POST /v1/phone-numbers/{id}/verify-voip
Конфликт идемпотентности 409Поново употребите кључ само са оригиналним нормализованим захтевом или пошаљите нови кључ
404 from_number is not registered to this organizationПотврдите да се from_number подудара са активним бројем телефона у вашој организацији. Број који се већ обезбеђује, није успео, ослобађа се или је ослобођен такође враћа овај одговор
500 само са пољем detailНије конфигурисан ниједан одлазни trunk. Обратите се подршци; ово није проблем са стањем броја који можете исправити
502 Bad GatewayПривремени неуспех SIP-а / LiveKit-а; безбедно је покушати поново

Погледајте референцу за одлазне позиве за потпуну стабилну листу кодова подобности и оба облика одговора 409. Ако активни број постане неподобан након што је захтев прихваћен, али пре упућивања позива, завршна провера враћа садржај одговора 409 који није могуће поновити.

Контрола времена на чекању

Одлазни позиви који трају дуго јер позвана страна споро одговара (IVR стабла, редови чекања) могу се ограничити помоћу max_hold_seconds у позиву или његовим подешавањем на сачуваном агенту:

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

Агент прекида позив ако у последњих N секунди није примљен људски говор. Подразумевана вредност је 900 секунди (15 минута).

Ако подесите max_hold_seconds и на сачуваном агенту и у захтеву за одлазни позив, за тај позив се користи вредност по позиву.


Следећи кораци