Foretag udgående opkald (API)

Udløs et AI-drevet udgående opkald fra din egen kode — spørgeskema-, opfølgnings- eller bekræftelsesforløb.

Udgående opkald lader dig give et destinationsnummer og en agentkonfiguration til ThunderPhone og få AI'en til at foretage opkaldet på dine vegne. Typiske anvendelser:

• Bekræftelser af aftaler
• Opfølgende opkald til spørgeundersøgelser
• Opfølgninger ved "andet forsøg" efter et ubesvaret opkald
• Notifikationer i dispatch-stil

Forudsætninger#

1. Vælg et nummer, der er aktiveret til udgående opkald

   Brug et nummer, du ejer, via en VoIP-forbindelse, eller anmod om tilladelse til at bruge dine ThunderPhone-numre til udgående opkald fra siden Phone Numbers. ThunderPhone-numre starter kun med indgående opkald. ThunderPhone gennemgår hver anmodning manuelt; når den er godkendt, kan disse numre foretage opkald op til den godkendte daglige grænse (nulstilles kl. 00:00 UTC) og køre kampagner, og du kan bede om en højere grænse. Kunders VoIP-numre har ingen daglig grænse, så vi anbefaler dem til udgående opkald. Se Brug dine egne numre.

2. Opret en agent

   En prompt til udgående opkald starter typisk med, at agenten identificerer sig selv og sit formål — "Hej, det er Acme, der ringer for at bekræfte din aftale i morgen kl. 15…" Angiv outbound_speak_order til agent_first (standardindstillingen).

3. Behold en positiv saldo

   Udgående opkald returnerer 402 Payment Required, hvis saldoen er ≤ $0.00. Indsæt penge eller aktivér automatisk genopfyldning under Organisation → Faktureringsindstillinger i dashboardet. Din sk_live_ nøgle kan kontrollere saldoen med GET /v1/billing, men kan ikke indsætte penge eller ændre automatisk genopfyldning.

Foretag et opkald med en gemt agent#

Den enkleste metode — referer til en agent via 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
  }'

Svar:

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

Foretag et opkald med inline-konfiguration#

Hvis du vil bruge en engangsprompt, som ikke er værd at gemme som en agent, skal du sende config i stedet. Strukturen matcher svarskemaet for 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"
    }
  }'

Følg opkaldet#

Abonner parallelt på telephony.complete-webhooken — den hurtigste måde at vide, at et opkald er afsluttet. Hvis du ikke kan modtage indgående webhooks, skal du forespørge GET /v1/calls/{call_id} hvert par sekunder; posten indeholder end_reason, duration_seconds og optagelses-URL'en, når opkaldet afsluttes.

Hvis din agent er konfigureret til at udtrække strukturerede data efter opkaldet, leveres disse data separat, når færdiggørelsen er fuldført.

Send variabler pr. opkald til en gemt agent#

Gemte agenter kan bruge pladsholdere som {{name}} eller {{name|there}} i prompttekst. Når du foretager et udgående opkald med agent_id, skal du sende variables med værdierne for det pågældende opkald:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "agent_id": 12,
  "variables": {
    "name": "Jordan"
  }
}

Brug strengværdier med pladsholdernavnet som nøgle. Disse variabler gælder for gemte agenter; denne vejlednings indbyggede config-eksempel bruger dem ikke.

Fejltilstande, du bør håndtere#

Se referencen for udgående opkald for den komplette liste over stabile kvalifikationskoder og begge 409-svarformater. Hvis et aktivt nummer bliver ukvalificeret, efter anmodningen er accepteret, men før opkaldet foretages, returnerer den endelige kontrol 409-payloaden, der ikke kan prøves igen.

Styring af ventetid#

Udgående opkald, der varer længe, fordi modtageren er langsom til at svare (IVR-træer, køer), kan begrænses med max_hold_seconds:

{
  "from_number": "+15551234567",
  "to_number":   "+14155552671",
  "agent_id":    12,
  "max_hold_seconds": 120
}

Agenten lægger på, hvis der ikke er modtaget menneskelig lyd i de seneste N sekunder. Standardværdien er 900 sekunder (15 minutter).

Næste trin#