Developer cookbook

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ändningsområden:

• Bekräftelser av bokade tider
• Återuppringningar för enkäter
• Uppföljningar med ett andra försök efter ett missat samtal
• Aviseringar i dispatch-stil

Förutsättningar#

1. Skaffa ett VoIP-nummer

   Utgående samtal kräver att du äger from_number via en VoIP-anslutning. Demnummer är endast för inkommande samtal. Se Ta med egna nummer.

2. Skapa en röstagent

   En prompt för utgående samtal börjar ofta med att röstagenten 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. Ha ett positivt saldo

   Utgående samtal returnerar 402 Payment Required om saldot är ≤ $0.00. Fyll på via POST /v1/billing/top-up eller aktivera automatisk påfyllning.

Ring med en sparad röstagent#

Det enklaste sättet — referera till en röstagent 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":   "+14155550199",
    "agent_id":    12
  }'

Svar:

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

Ring med inline-konfiguration#

Om du vill ha en engångsprompt som inte är värd att spara som en röstagent kan du skicka config i stället. Strukturen matchar svarsformatet för call.incoming-webhooken:

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

Följ samtalet#

Prenumerera parallellt på telephony.complete-webhooken — det snabbaste sättet att få veta att ett samtal har avslutats. Om du inte kan ta emot inkommande webhooks kan du hämta GET /v1/calls/{call_id} med några sekunders mellanrum; posten innehåller end_reason, duration_seconds och inspelnings-URL:en när samtalet avslutas.

Fel som är värda att hantera#

Styra väntetid#

Utgående samtal som drar ut på tiden eftersom den uppringda parten svarar långsamt (IVR-träd, köer) kan begränsas med max_hold_seconds:

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

Röstag­enten lägger på om inget mänskligt ljud har tagits emot under de senaste N sekunderna. Standardvärdet är 900 (15 minuter).

Nästa steg#