---
title: "Piga simu za kutoka (API)"
description: "Anzisha simu ya kutoka inayoendeshwa na AI kutoka kwenye msimbo wako mwenyewe — mitiririko ya utafiti, ufuatiliaji au uthibitishaji."
---

Kupiga simu zinazotoka hukuruhusu kuipa ThunderPhone nambari ya unakoenda na usanidi wa ejenti, kisha AI ipige simu kwa niaba yako. Matumizi ya kawaida:

- Uthibitishaji wa miadi
- Simu za kurudia kwa ajili ya tafiti
- Ufuatiliaji wa "jaribio la pili" baada ya simu iliyokosa kujibiwa
- Arifa za mtindo wa utumaji

<Note>
  Unapigia orodha nzima? Kipengele cha
  [**Kampeni**](/sw/guides/outbound-campaigns) cha dashibodi
  (`/dashboard/campaigns`) hupokea CSV ya waasiliani na kushughulikia
  vipindi vya kupiga simu vinavyozingatia saa za eneo, upigaji simu kwa wakati mmoja, na sera ya
  kujaribu tena kwa ajili yako. Mwongozo huu unahusu simu moja ya kiprogramu.
</Note>

## Mahitaji ya awali

<Steps>
  <Step title="Leta nambari ya VoIP">
    Kupiga simu zinazotoka kunahitaji umiliki wa `from_number` kupitia
    [muunganisho wa VoIP](/api-reference/voip-connections). Nambari za ThunderPhone
    ni za simu zinazoingia pekee. Tazama
    [Leta nambari zako mwenyewe](/sw/guides/bring-your-own-numbers).
  </Step>
  <Step title="Unda ejenti">
    Prompt ya simu zinazotoka kwa kawaida huanza ejenti ikijitambulisha
    na kueleza kusudi lake — "Habari, hapa ni Acme tunapiga simu
    kuthibitisha miadi yako ya kesho saa 3pm…" Weka
    `outbound_speak_order` kuwa `agent_first` (chaguo-msingi).
  </Step>
  <Step title="Dumisha salio chanya">
    Simu zinazotoka hurejesha `402 Payment Required` ikiwa salio ni ≤
    `$0.00`. Ongeza salio kupitia
    [`POST /v1/billing/top-up`](/api-reference/billing#top-up-balance)
    au washa [kujaza upya kiotomatiki](/api-reference/billing#update-auto-reload).
  </Step>
</Steps>

## Piga simu kwa ejenti iliyohifadhiwa

Njia rahisi zaidi — rejelea ejenti kwa id:

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

Jibu:

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

<Warning>
  `status: "initiated"` inamaanisha tu ombi lilikubaliwa — simu
  **bado haijaunganishwa**. Kagua mara kwa mara
  [`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
  ili kupata hali ya moja kwa moja (`in_progress` → `completed` / `failed`).
</Warning>

## Piga simu kwa usanidi wa ndani

Ikiwa unataka prompt ya matumizi ya mara moja ambayo haifai kuhifadhiwa kama ejenti,
pitisha `config` badala yake. Muundo unalingana na skima ya jibu ya
[`call.incoming` webhook](/sw/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"
    }
  }'
```

## Fuatilia simu

Sambamba, jiandikishe kwa
[`telephony.complete` webhook](/sw/webhooks/events) —
hii ndiyo njia ya haraka zaidi ya kujua simu imekamilika. Ikiwa huwezi kupokea
webhook zinazoingia, kagua `GET /v1/calls/{call_id}` kila baada ya sekunde chache; rekodi
inajumuisha `end_reason`, `duration_seconds`, na URL ya rekodi
mara simu inapomalizika.

## Hali za hitilafu zinazofaa kushughulikia

| Hitilafu | Suluhisho |
|-------|-----|
| `402 Payment Required` | Ongeza salio au washa kujaza upya kiotomatiki |
| `403` simu zinazotoka zimezuiwa (nambari ya ThunderPhone) | Leta nambari ya VoIP badala yake |
| `403` simu zinazotoka zimezuiwa (VoIP ambayo haijathibitishwa) | Tekeleza [`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` | Thibitisha kuwa `from_number` inalingana na nambari ya simu unayomiliki |
| `502 Bad Gateway` | Hitilafu ya muda ya SIP / LiveKit; ni salama kujaribu tena |

## Kudhibiti muda wa kusubiri

Simu za kutoka zinazochukua muda mrefu kwa sababu anayepokea anachelewa kujibu
(miti ya IVR, foleni) zinaweza kuwekwa kikomo kwa `max_hold_seconds`:

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

Ejenti hukata simu ikiwa hakuna sauti ya binadamu iliyopokelewa katika sekunde
N zilizopita. Chaguo-msingi ni 900 (dakika 15).

---

## Hatua zinazofuata

<CardGroup cols={2}>
  <Card title="Marejeleo ya simu za kutoka" icon="phone-arrow-up-right" href="/api-reference/outbound-calls">
    Kila sehemu ya ombi na msimbo wa hitilafu.
  </Card>
  <Card title="Pokea call.complete" icon="bolt" href="/sw/webhooks/call-complete">
    Tuma simu za kutoka zilizokamilika moja kwa moja kwenye mfumo wako.
  </Card>
  <Card title="Malipo" icon="credit-card" href="/api-reference/billing">
    Ongeza salio kiotomatiki ili simu za kutoka zisishindwe kwa sababu ya salio.
  </Card>
  <Card title="Jaribu ejenti za kutoka" icon="flask" href="/sw/guides/test-agents">
    Fanya jaribio la ejenti yako ya kutoka kabla ya uzalishaji.
  </Card>
</CardGroup>