ThunderPhone v3 вече е тук.Започнете самостоятелно — от 2 цента/мин.Прочетете съобщението

Developer cookbook

Извършване на изходящи обаждания (API)

Задействайте изходящо обаждане, управлявано от AI, от собствения си код — за анкети, последващи действия или потвърждения.

Изходящите обаждания Ви позволяват да подадете номер на получател и конфигурация на агент към ThunderPhone, а ИИ да извърши обаждането от Ваше име. Типични случаи на употреба:

  • Потвърждения на записани часове
  • Обратни обаждания за анкети
  • Последващи обаждания „втори опит“ след пропуснато обаждане
  • Известия в стил диспечиране

Предварителни изисквания

  1. Изберете номер с активирани изходящи обаждания

    Използвайте номер, който притежавате чрез VoIP връзка, или поискайте разрешение да използвате своите номера на ThunderPhone за изходящи обаждания от страницата Phone Numbers. Номерата на ThunderPhone първоначално са само за входящи обаждания. ThunderPhone преглежда всяка заявка ръчно; след одобрение тези номера могат да извършват обаждания до одобрения дневен лимит (който се нулира в 00:00 UTC) и да изпълняват кампании, като можете да поискате по-висок лимит. Клиентските VoIP номера нямат дневен лимит, затова ги препоръчваме за изходящи обаждания. Вижте Използване на собствени номера.

  2. Създайте агент

    Подкана, ориентирана към изходящи обаждания, обикновено започва с това агентът да се представя и да посочва целта си — „Здравейте, обажда се Acme, за да потвърди вашия час за утре в 15:00 ч.…“ Задайте 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 webhook:

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, ако такъв не се освободи. Не е необходимо да опитвате отново. Вижте обаждания на опашка.

Успоредно с това се абонирайте за webhook telephony.complete — най-бързият начин да разберете, че разговорът е приключил. Можете също да се абонирате за call.status_changed за актуализации на напредъка в реално време, като набиране, отговор, гласова поща и промени в задържането. Ако не можете да приемате входящи webhook заявки, изпращайте заявка към 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Не е конфигуриран изходящ транк. Свържете се с поддръжката; това не е проблем със състоянието на номера, който можете да коригирате
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 както за запазения агент, така и в заявката за изходящо обаждане, за това обаждане се използва стойността за конкретното обаждане.


Следващи стъпки