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

Developer cookbook

Обработване на входящи обаждания (API)

От край до край: конфигурирайте агент, назначете го към телефонен номер, приемете обаждане и прегледайте транскрипцията.

Каноничният процес „отговорете на телефон с AI“ от вашия терминал. Ще:

  1. Създадете агент с подкана и глас.
  2. Осигурите (или добавите) телефонен номер и зададете агента като негов обработчик на входящи обаждания.
  3. Позвъните на номера. Прегледайте дневника на обаждането, транскрипцията и записа.

Общо API извиквания: четири. Общо време: под пет минути.

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

Агентът обединява подканата, гласа и продуктовото ниво, които ще управляват разговора. Можете също да зададете ограничения за разговора, като max_call_duration_seconds и ring_duration_seconds, за агента. За изходящи разговори можете също да зададете max_hold_seconds, за да ограничите колко дълго агентът чака на изчакване, преди да прекрати разговора. Агентите Bolt поддържат също audio_tier, endpointing и intelligence, за да управляват как слушат и отговарят: intelligence е core или pro, а audio_tier (Слух) е lite, standard, plus или max (Max не е общодостъпен). По-старите стойности (lite и standard за intelligence; lean, hearing и deep_hearing за слух) все още се приемат. Агентите с пълен дуплекс запазват един и същ глас на поддържаните езици, така че превключването на глас според езика не се прилага за тези разговори. Агентите също поддържат intro_clip и intro_ring_count, за да възпроизвеждат предварително записано въведение и до две позвънявания, преди агентът да заговори. Новите агенти се нуждаят и от часова зона. Ако вашият агент е многоезичен, можете да зададете language_switching, за да управлявате дали да пита преди превключване на езиците, или да следва езика на обаждащия се. Можете също да зададете words за агента, за да управлявате как произнася конкретни термини и за кои термини слуша. Вижте Агенти за всички полета за конфигуриране; минималната конфигурация е:

curl -X POST https://api.thunderphone.com/v1/agents \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":    "Acme Support",
    "prompt":  "You are a friendly support agent for Acme. Help callers with orders and returns. Keep answers short.",
    "voice":   "john",
    "product": "bolt"
  }'

Запазете върнатия id — ще ви е необходим в стъпка 2.

2. Вземете телефонен номер

Ако просто ви е необходим номер, на който да позвъните, вземете номер на ThunderPhone от пула на ThunderPhone:

curl -X POST https://api.thunderphone.com/v1/phone-numbers \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"area_code": "415"}'

Отговорът включва id и number във формат E.164. Номерата на ThunderPhone започват със status="provisioning" и стават active в рамките на няколко секунди — проверявайте периодично GET /v1/phone-numbers/{id}, за да следите прехода, ако това е важно за вас.

3. Задайте агента

Свържете агента от стъпка 1 с входящата посока на номера:

curl -X PATCH https://api.thunderphone.com/v1/phone-numbers/{phone_id} \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inbound_agent_id": 12}'

Това е всичко — номерът е активен. След като изходящите обаждания бъдат одобрени за вашата организация, можете също да зададете outbound_agent_id в същата PATCH заявка. Дотогава API отхвърля това присвояване с 400.

Ако насочвате входящите обаждания чрез конфигурационен webhook вместо чрез фиксиран inbound_agent_id, този webhook вече може да връща timezone за всяко обаждане заедно с agent_id и variables. За агентите Bolt можете също да задавате audio_tier, endpointing и intelligence за агента при API заявки за запис. API все още приема по-старото име eagerness като псевдоним на endpointing. Ако вашият агент използва API връзки с trigger="call_start", ThunderPhone може да изпълни тези инструменти веднъж в началото на всяко телефонно обаждане, преди поздрава, като използва запазените им call_start_arguments.

Обратни обаждания към вашите изходящи обаждания

Когато някой върне обаждане към номер, който му е звънял през последните 30 дни, отговарящият агент получава кратка контекстна бележка за това обаждане: кога е извършено, от кой агент и какво се е случило (без отговор, гласова поща или разговор). Номер без входящ агент изпраща същите данни към вашия webhook за конфигурация като returning_call. Ако този номер няма webhook или webhook изтече, или не може да бъде достигнат, обаждането се насочва към агента, извършил предишното обаждане, вместо да приключи. Идентификаторът на обаждащия се може да бъде фалшифициран, затова обобщението и променливите от предишното обаждане се споделят само ако администратор включи Споделяне на данните от предишното обаждане в Организация → Общи → Обратни обаждания. Вижте Обратни обаждания.

4. Приемете обаждане

Позвънете на номера от вашия телефон. Агентът отговаря, представя се според вашата подкана и разговорът започва.

Докато обаждането е в ход, то се показва в GET /v1/calls със status="in_progress". Когато приключи, записът се актуализира с end_reason, duration_seconds, billable_minutes и (впоследствие) URL адрес за запис и AI оценка.

Входящите обаждания се отчитат към лимита за едновременни обаждания на вашата организация (по подразбиране 20 обаждания в ход, споделени с изходящите, уеб и тестовите обаждания). Обаждане, което постъпи при достигнат лимит, се отказва преди агентът да отговори и се прекратява, не се таксува и се записва като неуспешно обаждане с причина за приключване concurrent_call_limit_reached. Изпратете имейл на support@thunderphone.com, ако се нуждаете от по-висок лимит.

5. Проверете резултатите

Извлечете списъка с последните обаждания:

curl 'https://api.thunderphone.com/v1/calls?limit=5' \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Изтеглете транскрипцията:

curl https://api.thunderphone.com/v1/calls/{call_id}/transcript \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

И URL адреса на записа (с кратък срок на валидност, подписан):

curl https://api.thunderphone.com/v1/calls/{call_id}/audio \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Ако сте се абонирали за webhook telephony.complete, ще получите същите данни като POST заявка към вашия сървър — вижте call.complete.

Ако за вашия агент са конфигурирани полета за извличане, полезният товар за завършеното обаждане може също да включва структурирани извлечени данни. Обобщенията на обажданията се изготвят на езика, който вашата организация използва в ThunderPhone, освен ако агентът не замени тази настройка.


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