---
title: "Ring utgående samtal (API)"
description: "Utlös ett AI-drivet utgående samtal från din egen kod — för enkäter, uppföljningar eller bekräftelseflöden."
---
Med utgående samtal kan du ge ThunderPhone ett destinationsnummer och en
agentkonfiguration och låta AI:n ringa samtalet åt dig. Vanliga användningsfall:
- Bekräftelser av bokade tider
- Återuppringningar för enkäter
- Uppföljningar vid ett andra försök efter ett missat samtal
- Distributionsaviseringar
Ringer du en hel lista? Dashboardens funktion
[**Kampanjer**](/sv/guides/outbound-campaigns)
(`/dashboard/campaigns`) tar emot en CSV-fil med kontakter och hanterar
tidszonsanpassade samtalsfönster, samtidighet och återförsökspolicy åt
dig. Den här guiden omfattar enskilda programmatiska samtal.
## Förutsättningar
Använd ett nummer du äger via en
[VoIP-anslutning](/api-reference/voip-connections), eller begär behörighet
att använda dina ThunderPhone-nummer för utgående samtal från sidan
Telefonnummer. ThunderPhone-nummer är från början endast för inkommande samtal.
ThunderPhone granskar varje begäran manuellt. När den har godkänts kan dessa
nummer ringa samtal upp till den godkända dagliga gränsen (som återställs
00:00 UTC) och köra kampanjer, och du kan begära en högre gräns. Kundernas
VoIP-nummer har ingen daglig gräns, så vi rekommenderar dem för utgående samtal.
Se
[Använd dina egna nummer](/sv/guides/bring-your-own-numbers).
En prompt anpassad för utgående samtal börjar ofta med att agenten
identifierar sig själv och sitt syfte — "Hej, det här är Acme som ringer för
att bekräfta din tid i morgon klockan 15…" Ange
`outbound_speak_order` till `agent_first` (standardvärdet).
Utgående samtal returnerar `402 Payment Required` om saldot är ≤
`$0.00`. Fyll på saldot eller aktivera automatisk påfyllning under
**Organisation → Faktureringsinställningar** i instrumentpanelen. Din `sk_live_`
nyckel kan kontrollera saldot med
[`GET /v1/billing`](/api-reference/billing#get-billing-account) men
kan inte fylla på saldot eller ändra automatisk påfyllning.
## Ring ett samtal med en sparad agent
Den enklaste vägen — referera till en agent med 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": "+14155552671",
"agent_id": 12
}'
```
Svar:
```json
{ "call_id": 987654321, "status": "initiated" }
```
`status: "initiated"` betyder bara att begäran accepterades — samtalet
är **ännu inte anslutet**. Kontrollera
[`GET /v1/calls/{call_id}`](/api-reference/calls#retrieve-a-call)
för aktuell status (`in_progress` → `completed` / `failed`).
## Ring ett samtal med inlinekonfiguration
Om du vill använda en engångsprompt som inte är värd att spara som en agent
skickar du `config` i stället. Formatet matchar svarsschemat för
[`call.incoming` webhook](/sv/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": "+14155552671",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'
```
## Följ samtalet
Prenumerera parallellt på
[`telephony.complete`-webhooken](/sv/webhooks/events) —
det snabbaste sättet att veta att ett samtal är avslutat. Om du inte kan ta emot inkommande
webhooks kan du polla `GET /v1/calls/{call_id}` varannan sekund; posten innehåller
`end_reason`, `duration_seconds` och inspelnings-URL:en när samtalet avslutas.
Om din agent är konfigurerad för att extrahera strukturerad data efter samtalet
levereras dessa data separat när slutbehandlingen är klar.
### Skicka variabler per samtal till en sparad agent
Sparade agenter kan använda platshållare som `{{name}}` eller `{{name|there}}` i
prompttexten. När du ringer ett utgående samtal med `agent_id` skickar du
`variables` med värdena för det samtalet:
```json
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}
```
Använd strängvärden med platshållarnamnet som nyckel. Dessa variabler gäller för
sparade agenter; den här guidens inbäddade `config`-exempel använder dem inte.
## Fellägen som är värda att hantera
| Fel | Åtgärd |
|-------|-----|
| `402 Payment Required` | Fyll på saldot eller aktivera automatisk påfyllning |
| `400` med `code: destination_not_allowed` | ThunderPhone ringer inte det numret: ogiltiga nummer, nödnummer, nummer med förhöjd taxa, kortnummer eller sanktionsbelagda länder. Från ThunderPhone-nummer är endast vanliga amerikanska och kanadensiska nummer tillåtna (inga nummer med förhöjd taxa). `reason` anger vilket; se [blockerade destinationer](/api-reference/outbound-calls#blocked-destinations) |
| `409` med `retryable: false` för ett ThunderPhone-nummer | Följ `code`: begär utgående samtal på sidan Telefonnummer, vänta på en pågående granskning eller använd ett annat kvalificerat nummer |
| `429` med `code: platform_outbound_daily_limit_reached` | Organisationen har förbrukat dagens kvot för utgående samtal från ThunderPhone-nummer. Vänta på `resets_at` (00:00 UTC), begär en högre gräns på sidan Telefonnummer eller ring från ett nummer i din egen VoIP-anslutning |
| `429` med `code: concurrent_call_limit_reached` | Organisationen har nått sin [gräns för samtidiga samtal](/api-reference/introduction#call-limits) (20 som standard, inklusive inkommande, utgående, webb- och testsamtal). Försök igen efter det antal sekunder som anges i headern `Retry-After` eller när ett samtal avslutas; skicka e-post till support@thunderphone.com för att höja gränsen |
| `429` med `code: same_number_too_soon` | Du ringde samma `to_number` för mindre än 10 sekunder sedan. Försök igen efter det antal sekunder som anges i headern `Retry-After` |
| `409` med `retryable: false` för ett VoIP-nummer från en kund | Åtgärda det tillstånd som anges av `code`; kör [`POST /v1/phone-numbers/{id}/verify-voip`](/api-reference/phone-numbers#verify-a-voip-sourced-number) vid verifieringsfel |
| `409` idempotenskonflikt | Återanvänd endast nyckeln med den ursprungliga normaliserade begäran, eller skicka en ny nyckel |
| `404 from_number is not registered to this organization` | Kontrollera att `from_number` matchar ett aktivt telefonnummer i din organisation. Ett nummer som redan provisioneras, har misslyckats, frisläpps eller har frisläppts returnerar också detta svar |
| `500` med endast ett `detail`-fält | Ingen utgående trunk är konfigurerad. Kontakta supporten; detta är inte ett problem med nummerstatus som du kan åtgärda |
| `502 Bad Gateway` | Tillfälligt SIP-/LiveKit-fel; det är säkert att försöka igen |
Se [referensen för utgående samtal](/api-reference/outbound-calls#error-responses)
för den fullständiga stabila listan över behörighetskoder och båda svarsformaten för `409`.
Om ett aktivt nummer blir obehörigt efter att begäran har godkänts men innan
samtalet rings upp returnerar den slutliga kontrollen `409`-payloaden som inte kan återförsökas.
## Styra väntetiden
Utgående samtal som blir långa eftersom mottagaren svarar långsamt
(IVR-träd, köer) kan begränsas med `max_hold_seconds`:
```json
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}
```
Agenten lägger på om inget mänskligt ljud har tagits emot under de senaste
N sekunderna. Standardvärdet är 900 sekunder (15 minuter).
---
## Nästa steg
Alla begärandefält och felkoder.
Strömma avslutade utgående samtal till ditt system.
Automatisk påfyllning så att utgående samtal aldrig misslyckas på grund av saldo.
Torrkör din utgående agent före produktion.