Ring utgående samtal (API)

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

Förutsättningar#

1. Välj ett nummer som är aktiverat för utgående samtal

   Använd ett nummer du äger via en VoIP-anslutning, 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.

2. Skapa en röstagent

   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).

3. Behåll ett positivt saldo

   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 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:

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" }

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:

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 — 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:

{
  "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#

Se referensen för utgående samtal 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:

{
  "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#