---
title: "Извършване на изходящи обаждания (API)"
description: "Задействайте изходящо обаждане, управлявано от AI, от собствения си код — за анкети, последващи действия или потвърждения."
---

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

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

<Note>
  Обаждате се на цял списък? Функцията
  [**Кампании**](/bg/guides/outbound-campaigns) в таблото
  (`/dashboard/campaigns`) приема CSV файл с контакти и обработва вместо вас
  прозорците за обаждания според часовата зона, едновременните обаждания и
  правилата за повторен опит. Това ръководство обхваща единични програмни обаждания.
</Note>

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

<Steps>
  <Step title="Осигурете VoIP номер">
    За изходящи обаждания трябва да притежавате `from_number` чрез
    [VoIP връзка](/api-reference/voip-connections). Номерата на ThunderPhone
    са само за входящи обаждания. Вижте
    [Използване на собствени номера](/bg/guides/bring-your-own-numbers).
  </Step>
  <Step title="Създайте агент">
    Подканата за изходящи обаждания обикновено започва с това агентът да
    се представи и да посочи целта си — „Здравейте, обажда се Acme, за да
    потвърди вашата среща за утре в 15:00 ч.…“ Задайте
    `outbound_speak_order` на `agent_first` (стойността по подразбиране).
  </Step>
  <Step title="Поддържайте положителен баланс">
    Изходящите обаждания връщат `402 Payment Required`, ако балансът е ≤
    `$0.00`. Заредете баланс чрез
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    или активирайте [автоматично презареждане](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Извършване на обаждане със запазен агент

Най-лесният начин — посочете агент по идентификатор:

```bash
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":   "+14155550199",
    "agent_id":    12
  }'
```

Отговор:

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

<Warning>
  `status: "initiated"` означава само че заявката е приета — обаждането
  **все още не е свързано**. Проверявайте
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  за текущото състояние (`in_progress` → `completed` / `failed`).
</Warning>

## Извършване на обаждане с вградена конфигурация

Ако искате еднократна подкана, която не си заслужава да запазвате като агент,
подайте вместо това `config`. Формата съответства на схемата на отговора на
[уебкуката `call.incoming`](/bg/webhooks/call-incoming):

```bash
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":   "+14155550199",
    "config": {
      "prompt":  "You are confirming Jane Doe appointment for 3pm tomorrow…",
      "voice":   "john",
      "product": "spark"
    }
  }'
```

## Проследяване на обаждането

Паралелно се абонирайте за
[уебкуката `telephony.complete`](/bg/webhooks/events) —
това е най-бързият начин да разберете, че обаждането е приключило. Ако не можете
да приемате входящи уебкуки, проверявайте `GET /v1/calls/{call_id}` на всеки няколко секунди; записът включва `end_reason`, `duration_seconds` и URL адреса на записа, след като обаждането приключи.

## Грешки, които си струва да обработвате

| Грешка | Решение |
|-------|-----|
| `402 Payment Required` | Заредете баланса или активирайте автоматично презареждане |
| `403` изходящите обаждания са блокирани (номер на ThunderPhone) | Вместо това използвайте VoIP номер |
| `403` изходящите обаждания са блокирани (непотвърден VoIP) | Изпълнете [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) |
| `404 from_number is not registered to this organization` | Потвърдете, че `from_number` съответства на телефонен номер, който притежавате |
| `502 Bad Gateway` | Временна грешка на SIP / LiveKit; може безопасно да опитате отново |

## Управление на времето на изчакване

Изходящите обаждания, които се проточват, защото отсрещната страна отговаря бавно
(IVR дървета, опашки), могат да бъдат ограничени с `max_hold_seconds`:

```json
{
  "from_number": "+15551234567",
  "to_number":   "+14155550199",
  "agent_id":    12,
  "max_hold_seconds": 120
}
```

Агентът прекратява разговора, ако през последните
N секунди не е получен човешки звук. По подразбиране е 900 (15 минути).

---

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

<CardGroup cols={2}>
  <Card title="Справочник за изходящи обаждания" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Всяко поле в заявката и код за грешка.
  </Card>
  <Card title="Получаване на call.complete" icon="bolt" href="/bg/webhooks/call-complete">
    Предавайте завършените изходящи обаждания към вашата система.
  </Card>
  <Card title="Фактуриране" icon="credit-card" href="/api-reference/billing">
    Автоматично презареждане, така че изходящите обаждания никога да не се провалят поради недостатъчен баланс.
  </Card>
  <Card title="Тестване на изходящи агенти" icon="flask" href="/bg/guides/test-agents">
    Извършете пробно изпълнение на вашия изходящ агент преди продукционна среда.
  </Card>
</CardGroup>