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ను తిరిగి ఇస్తాయి. డ్యాష్‌బోర్డ్‌లోని సంస్థ → బిల్లింగ్ సెట్టింగ్‌లు కింద టాప్ అప్ చేయండి లేదా ఆటో-రీలోడ్‌ను ప్రారంభించండి. మీ 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 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"
    }
  }'

చివరి నిశ్శబ్ద చెక్-ఇన్ తర్వాత ఏమి జరుగుతుందో నియంత్రించండి

సేవ్ చేసిన ఏజెంట్‌లు ఉపయోగించే అదే నిశ్శబ్ద తుది-చర్య సెట్టింగ్‌లను ఇన్‌లైన్ 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 తో code: destination_not_allowedThunderPhone ఆ నంబర్‌కు కాల్ చేయదు: చెల్లని నంబర్‌లు, అత్యవసర నంబర్‌లు, ప్రీమియం-రేట్ నంబర్‌లు, షార్ట్ కోడ్‌లు, ఆంక్షలు విధించిన దేశాలు లేదా మీ సంస్థ అవుట్‌బౌండ్ కాలింగ్ కోసం బ్లాక్ చేసిన US రాష్ట్రం. ThunderPhone నంబర్‌ల నుండి, సాధారణ US మరియు కెనడియన్ నంబర్‌లు అనుమతించబడతాయి; కొన్ని అంతర్జాతీయ గమ్యస్థానాలు కూడా అనుమతించబడతాయి మరియు గమ్యస్థాన రేట్ ప్రకారం బిల్ చేయబడతాయి. ఏదో reason తెలియజేస్తుంది; బ్లాక్ చేసిన గమ్యస్థానాలు చూడండి
ThunderPhone నంబర్ కోసం retryable: false తో 409codeను అనుసరించండి: ఫోన్ నంబర్‌లు పేజీలో అవుట్‌బౌండ్ కాలింగ్‌ను అభ్యర్థించండి, పెండింగ్ సమీక్ష కోసం వేచి ఉండండి లేదా మరో అర్హతగల నంబర్‌ను ఉపయోగించండి
429 తో code: platform_outbound_daily_limit_reachedసంస్థ ఈరోజు ThunderPhone నంబర్‌ల నుండి అనుమతించిన అవుట్‌బౌండ్ కాల్‌లను ఉపయోగించుకుంది. resets_at (00:00 UTC) వరకు వేచి ఉండండి, ఫోన్ నంబర్‌లు పేజీలో అధిక పరిమితిని అభ్యర్థించండి లేదా మీ స్వంత VoIP కనెక్షన్‌లోని నంబర్ నుండి కాల్ చేయండి
429 తో code: concurrent_call_limit_reachedసంస్థలో దాని ఏకకాల కాల్ పరిమితి మేరకు కాల్‌లు కొనసాగుతున్నాయి (డిఫాల్ట్‌గా 20, ఇన్‌బౌండ్, అవుట్‌బౌండ్, వెబ్ మరియు టెస్ట్ కాల్‌లను లెక్కిస్తూ). Retry-After హెడర్‌లోని సెకన్ల తర్వాత లేదా ఒక కాల్ ముగిసినప్పుడు మళ్లీ ప్రయత్నించండి; పరిమితిని పెంచడానికి support@thunderphone.comకు ఇమెయిల్ చేయండి
429 తో code: outbound_queue_fullసంస్థలో 50 క్యూ చేసిన కాల్‌లు వేచి ఉన్నాయి. Retry-After హెడర్‌లోని సెకన్ల తర్వాత మళ్లీ ప్రయత్నించండి
429 తో code: same_number_too_soonమీరు 10 సెకన్లలోపు అదే to_numberకు కాల్ చేశారు. Retry-After హెడర్‌లోని సెకన్ల తర్వాత మళ్లీ ప్రయత్నించండి
కస్టమర్ VoIP నంబర్ కోసం retryable: false తో 409code పేర్కొన్న స్థితిని సరిచేయండి; ధృవీకరణ వైఫల్యాల కోసం, POST /v1/phone-numbers/{id}/verify-voipను అమలు చేయండి
409 ఐడెంపోటెన్సీ సంఘర్షణఅసలు సాధారణీకరించిన అభ్యర్థనతోనే కీని మళ్లీ ఉపయోగించండి లేదా కొత్త కీని పంపండి
404 from_number is not registered to this organizationfrom_number మీ సంస్థలోని సక్రియ ఫోన్ నంబర్‌తో సరిపోతుందని నిర్ధారించండి. ఇప్పటికే ప్రొవిజనింగ్‌లో ఉన్న, విఫలమైన, విడుదల చేస్తున్న లేదా విడుదలైన నంబర్ కూడా ఈ ప్రతిస్పందనను ఇస్తుంది
కేవలం detail ఫీల్డ్‌తో 500ఏ అవుట్‌బౌండ్ ట్రంక్ కాన్ఫిగర్ చేయబడలేదు. సపోర్ట్‌ను సంప్రదించండి; ఇది మీరు సరిచేయగల నంబర్-స్థితి సమస్య కాదు
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 సెట్ చేస్తే, ఆ కాల్‌కు ప్రతి-కాల్ విలువ ఉపయోగించబడుతుంది.


తదుపరి దశలు