ThunderPhone v3 आता लाइव्ह आहे.स्वतःच सुरू करा—2¢/मिनिटपासून.घोषणा वाचा

Developer cookbook

आउटबाउंड कॉल करा (API)

तुमच्या स्वतःच्या कोडमधून AI-चालित आउटबाउंड कॉल ट्रिगर करा — सर्वेक्षण, फॉलो-अप किंवा पुष्टीकरण प्रवाहांसाठी.

आउटबाउंड कॉलिंगमुळे तुम्ही गंतव्य क्रमांक आणि एजंट कॉन्फिगरेशन ThunderPhone ला देऊ शकता आणि AI तुमच्या वतीने कॉल करू शकते. सामान्य वापरप्रकरणे:

  • अपॉइंटमेंट पुष्टीकरणे
  • सर्वेक्षण कॉलबॅक
  • मिस्ड कॉलनंतरचे "दुसऱ्या प्रयत्नाचे" फॉलो-अप
  • डिस्पॅच-शैलीतील सूचना

पूर्वअटी

  1. आउटबाउंड सक्षम क्रमांक निवडा

    तुमच्या मालकीचा क्रमांक VoIP कनेक्शनद्वारे वापरा किंवा Phone Numbers पेजवरून तुमचे ThunderPhone क्रमांक आउटबाउंड कॉलसाठी वापरण्याची परवानगी मागा. ThunderPhone क्रमांक सुरुवातीला फक्त इनबाउंड असतात. ThunderPhone प्रत्येक विनंतीचे हाताने पुनरावलोकन करते; मंजुरीनंतर, ते क्रमांक मंजूर दैनंदिन मर्यादेपर्यंत (00:00 UTC ला रीसेट होणारी) कॉल करू शकतात आणि मोहिमा चालवू शकतात, तसेच तुम्ही अधिक मर्यादेची विनंती करू शकता. ग्राहकांच्या VoIP क्रमांकांना दैनंदिन मर्यादा नसते, त्यामुळे आउटबाउंड कॉलिंगसाठी आम्ही त्यांची शिफारस करतो. पहा तुमचे स्वतःचे क्रमांक आणा.

  2. एजंट तयार करा

    आउटबाउंडसाठी तयार केलेला prompt सहसा एजंटने स्वतःची आणि उद्देशाची ओळख करून देण्याने सुरू होतो — "नमस्कार, तुमची उद्या दुपारी 3 वाजताची अपॉइंटमेंट निश्चित करण्यासाठी Acme कडून कॉल करत आहे…" outbound_speak_order ला agent_first (डीफॉल्ट) वर सेट करा.

  3. शिल्लक सकारात्मक ठेवा

    शिल्लक ≤ $0.00 असल्यास आउटबाउंड कॉल 402 Payment Required परत करतात. डॅशबोर्डमध्ये Organization → Billing Settings अंतर्गत रक्कम भरा किंवा ऑटो-रीलोड सक्षम करा. तुमची sk_live_ की GET /v1/billing वापरून शिल्लक तपासू शकते, पण रक्कम भरू किंवा ऑटो-रीलोड बदलू शकत नाही.

जतन केलेल्या एजंटसह कॉल करा

सर्वात सोपा मार्ग — 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
  }'

प्रतिसाद:

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

इनलाइन कॉन्फिगरेशनसह कॉल करा

एजंट म्हणून जतन करण्यासारखा नसलेला एकदाच वापरायचा prompt हवा असल्यास, त्याऐवजी config पास करा. त्याचा आकार call.incoming वेबहुक च्या प्रतिसाद स्कीमाशी जुळतो:

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

शेवटच्या शांतता तपासणीनंतर काय होते ते नियंत्रित करा

सेव्ह केलेले एजंट वापरतात त्याच शांतता अंतिम-कृती सेटिंग्ज तुम्ही इनलाइन config मध्येही देऊ शकता:

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "silence_final_action": "hang_up"
  }
}

शेवटच्या शांतता तपासणीनंतर काय होते ते निवडण्यासाठी silence_final_action वापरा. तुम्ही silence_final_message देखील देऊ शकता आणि अंतिम कृती ट्रान्सफर असल्यास silence_transfer_destination देऊ शकता.

इनलाइन config मध्ये शब्दांची सूची जोडा

इनलाइन आउटबाउंड कॉलमध्ये सेव्ह केलेल्या एजंटप्रमाणेच words सूची समाविष्ट असू शकते. एजंट आधी सेव्ह न करता कॉलने सानुकूल उच्चार किंवा ऐकण्याचे नियम पाळावेत असे तुम्हाला वाटत असल्यास हे वापरा.

{
  "from_number": "+[REDACTED_PHONE]",
  "to_number": "+[REDACTED_PHONE]",
  "config": {
    "prompt": "[REDACTED_LITERAL]",
    "voice": "john",
    "product": "spark",
    "words": []
  }
}

कॉलचे अनुसरण करा

queued_at वेळ असलेल्या प्रतिसादाचा अर्थ ThunderPhone ची आउटबाउंड क्षमता वापरात आहे: जागा उपलब्ध झाल्यावर कॉल 10 मिनिटांच्या आत डायल होतो; जागा उपलब्ध नसल्यास तो end_reason outbound_queue_timeout सह समाप्त होतो. तुम्हाला पुन्हा प्रयत्न करण्याची गरज नाही. रांगेतील कॉल पहा.

त्याच वेळी, telephony.complete वेबहुकची सदस्यता घ्या — कॉल संपल्याचे जाणून घेण्याचा हा सर्वात जलद मार्ग आहे. डायलिंग, कॉलला उत्तर दिले जाणे, व्हॉइसमेल आणि होल्डमधील बदल यांसारख्या थेट प्रगती अद्यतनांसाठी तुम्ही call.status_changed चीही सदस्यता घेऊ शकता. तुम्ही येणारे वेबहुक स्वीकारू शकत नसल्यास, प्रत्येक काही सेकंदांनी GET /v1/calls/{call_id} पोल करा; कॉल संपल्यानंतर रेकॉर्डमध्ये end_reason, duration_seconds, आणि रेकॉर्डिंग URL समाविष्ट असते.

तुमचा एजंट कॉलनंतर संरचित डेटा काढण्यासाठी सेट केलेला असल्यास, अंतिमीकरण पूर्ण झाल्यानंतर तो डेटा स्वतंत्रपणे वितरित केला जातो.

सेव्ह केलेल्या एजंटला प्रति-कॉल व्हेरिएबल्स द्या

सेव्ह केलेले एजंट prompt मजकुरात {{name}} किंवा {{name|there}} यांसारखे प्लेसहोल्डर वापरू शकतात. तुम्ही agent_id सह आउटबाउंड कॉल करता तेव्हा, त्या कॉलच्या मूल्यांसह variables पाठवा:

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

प्लेसहोल्डरच्या नावानुसार की असलेली स्ट्रिंग मूल्ये वापरा. हे व्हेरिएबल्स सेव्ह केलेल्या एजंटसाठी लागू होतात; या मार्गदर्शिकेतील इनलाइन config उदाहरण त्यांचा वापर करत नाही.

हाताळण्यासारख्या अयशस्वी अवस्था

त्रुटीउपाय
402 Payment Requiredशिल्लक भरा किंवा ऑटो-रिलोड सक्षम करा
400 with code: destination_not_allowedThunderPhone त्या नंबरवर कॉल करत नाही: अवैध नंबर, आपत्कालीन नंबर, प्रीमियम-दराचे नंबर, शॉर्ट कोड, निर्बंधित देश किंवा तुमच्या संस्थेने आउटबाउंड कॉलिंगसाठी ब्लॉक केलेले अमेरिकेतील राज्य. ThunderPhone नंबरवरून सामान्य अमेरिकन आणि कॅनेडियन नंबरना परवानगी आहे आणि काही आंतरराष्ट्रीय गंतव्यांना परवानगी असून त्यांना गंतव्याच्या दराने बिल आकारले जाते. कोणते ते reason सांगते; ब्लॉक केलेली गंतव्ये पहा
409 with retryable: false for a ThunderPhone numbercode नुसार कृती करा: फोन नंबर पृष्ठावर आउटबाउंड कॉलिंगची विनंती करा, प्रलंबित पुनरावलोकनाची प्रतीक्षा करा किंवा दुसरा पात्र नंबर वापरा
429 with code: platform_outbound_daily_limit_reachedसंस्थेने ThunderPhone नंबरवरून आजची आउटबाउंड कॉल मर्यादा वापरली आहे. resets_at (00:00 UTC) पर्यंत प्रतीक्षा करा, फोन नंबर पृष्ठावर जास्त मर्यादेची विनंती करा किंवा तुमच्या स्वतःच्या VoIP कनेक्शनवरील नंबरवरून कॉल करा
429 with code: concurrent_call_limit_reachedसंस्थेमध्ये तिच्या समवर्ती कॉल मर्यादेइतके कॉल प्रगतीपथावर आहेत (डीफॉल्टनुसार 20, ज्यात इनबाउंड, आउटबाउंड, वेब आणि चाचणी कॉल समाविष्ट आहेत). Retry-After हेडरमधील सेकंदांनंतर किंवा कॉल संपल्यावर पुन्हा प्रयत्न करा; मर्यादा वाढवण्यासाठी support@thunderphone.com वर ईमेल करा
429 with code: outbound_queue_fullसंस्थेचे 50 रांगेतील कॉल प्रतीक्षेत आहेत. Retry-After हेडरमधील सेकंदांनंतर पुन्हा प्रयत्न करा
429 with code: same_number_too_soonतुम्ही 10 सेकंदांपेक्षा कमी वेळापूर्वी त्याच to_number वर कॉल केला आहे. Retry-After हेडरमधील सेकंदांनंतर पुन्हा प्रयत्न करा
409 with retryable: false for a customer VoIP numbercode ने निर्दिष्ट केलेली स्थिती दुरुस्त करा; पडताळणी अयशस्वी झाल्यास, POST /v1/phone-numbers/{id}/verify-voip चालवा
409 idempotency conflictकी फक्त मूळ सामान्यीकृत विनंतीसोबत पुन्हा वापरा किंवा नवीन की पाठवा
404 from_number is not registered to this organizationfrom_number तुमच्या संस्थेतील सक्रिय फोन नंबरशी जुळत असल्याची खात्री करा. आधीपासून प्रोव्हिजन होत असलेला, अयशस्वी झालेला, रिलीज होत असलेला किंवा रिलीज झालेला नंबरही हा प्रतिसाद परत करतो
500 with only a detail fieldकोणताही आउटबाउंड ट्रंक कॉन्फिगर केलेला नाही. सपोर्टशी संपर्क करा; ही नंबर-स्थितीची समस्या नाही जी तुम्ही दुरुस्त करू शकता
502 Bad Gatewayतात्पुरते SIP / LiveKit अपयश; पुन्हा प्रयत्न करणे सुरक्षित आहे

स्थिर पात्रता-कोडची संपूर्ण यादी आणि 409 प्रतिसादाचे दोन्ही स्वरूप यांसाठी आउटबाउंड कॉल्स संदर्भ पहा. विनंती स्वीकारल्यानंतर पण कॉल लावण्यापूर्वी सक्रिय नंबर अपात्र झाल्यास, अंतिम तपासणी पुन्हा प्रयत्न न करता येणारा 409 पेलोड परत करते.

होल्ड वेळ नियंत्रित करणे

ज्या आउटबाउंड कॉलमध्ये समोरील व्यक्तीचा प्रतिसाद मंद असल्यामुळे जास्त वेळ लागतो (IVR ट्री, रांगा), त्या कॉलवर max_hold_seconds वापरून किंवा जतन केलेल्या एजंटवर ते सेट करून मर्यादा घालू शकता:

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

मागील N सेकंदांत मानवी आवाज प्राप्त झाला नसेल, तर एजंट कॉल बंद करतो. डीफॉल्ट 900 सेकंद (15 मिनिटे) आहे.

तुम्ही जतन केलेल्या एजंटवर आणि आउटबाउंड कॉल विनंतीवर दोन्ही ठिकाणी max_hold_seconds सेट केल्यास, त्या कॉलसाठी प्रति-कॉल मूल्य वापरले जाते.


पुढील पायऱ्या