ThunderPhone v3 এখন লাইভ।নিজেই ব্যবহার শুরু করুন, 2¢/মিনিট থেকে।ঘোষণাটি পড়ুন

Developer cookbook

আউটবাউন্ড কল করুন (API)

নিজের কোড থেকে AI-চালিত আউটবাউন্ড কল ট্রিগার করুন — জরিপ, ফলো-আপ বা নিশ্চিতকরণ ফ্লোর জন্য।

বহির্গামী কলিং আপনাকে একটি গন্তব্য নম্বর এবং একটি এজেন্ট কনফিগারেশন ThunderPhone-এ দিতে দেয় এবং AI-কে আপনার হয়ে কল করতে দেয়। সাধারণ ব্যবহারের ক্ষেত্র:

  • অ্যাপয়েন্টমেন্ট নিশ্চিতকরণ
  • সার্ভে কলব্যাক
  • মিসড কলের পর "দ্বিতীয়-চেষ্টা" ফলো-আপ
  • ডিসপ্যাচ-ধাঁচের বিজ্ঞপ্তি

পূর্বশর্ত

  1. বহির্গামী কল-সক্ষম নম্বর নির্বাচন করুন

    একটি VoIP সংযোগ-এর মাধ্যমে আপনার মালিকানাধীন নম্বর ব্যবহার করুন, অথবা ফোন নম্বর পৃষ্ঠা থেকে বহির্গামী কলের জন্য আপনার ThunderPhone নম্বর ব্যবহার করার অনুমতি অনুরোধ করুন। ThunderPhone নম্বর শুরুতে শুধু ইনবাউন্ডের জন্য থাকে। ThunderPhone প্রতিটি অনুরোধ ম্যানুয়ালি পর্যালোচনা করে; অনুমোদিত হলে, সেই নম্বরগুলো অনুমোদিত দৈনিক সীমা পর্যন্ত কল করতে পারে (যা 00:00 UTC-তে রিসেট হয়) এবং ক্যাম্পেইন চালাতে পারে, আর আপনি আরও বেশি সীমার জন্য অনুরোধ করতে পারেন। গ্রাহকের VoIP নম্বরের কোনো দৈনিক সীমা নেই, তাই আমরা বহির্গামী কলের জন্য সেগুলো সুপারিশ করি। দেখুন নিজের নম্বর ব্যবহার করুন।

  2. একটি এজেন্ট তৈরি করুন

    বহির্গামী কলের উপযোগী একটি prompt সাধারণত এজেন্টের নিজের পরিচয় এবং উদ্দেশ্য দিয়ে শুরু হয় — "হ্যালো, আমি Acme থেকে বলছি, আগামীকাল বিকেল 3টায় আপনার অ্যাপয়েন্টমেন্ট নিশ্চিত করতে…" 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 ওয়েবহুক](/bn/webhooks/events)-এ সাবস্ক্রাইব করুন — কল শেষ হয়েছে জানার সবচেয়ে দ্রুত উপায়। লাইভ অগ্রগতি আপডেটের জন্য আপনি [call.status_changed](/bn/webhooks/events)-এও সাবস্ক্রাইব করতে পারেন, যেমন ডায়াল করা, উত্তর দেওয়া, ভয়েসমেইল এবং হোল্ডের পরিবর্তন। আপনি যদি ইনবাউন্ড ওয়েবহুক গ্রহণ করতে না পারেন, প্রতি কয়েক সেকেন্ডে GET /v1/calls/পোল করুন; কল শেষ হলে রেকর্ডে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 জানায়; দেখুন ব্লক করা গন্তব্য
ThunderPhone নম্বরের জন্য retryable: false সহ 409code অনুসরণ করুন: ফোন নম্বর পৃষ্ঠায় বহির্গামী কলের অনুরোধ করুন, মুলতুবি পর্যালোচনার জন্য অপেক্ষা করুন, অথবা অন্য কোনো যোগ্য নম্বর ব্যবহার করুন
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 হেডারে উল্লেখিত সেকেন্ড পর আবার চেষ্টা করুন
গ্রাহকের VoIP নম্বরের জন্য retryable: false সহ 409code-এ উল্লিখিত অবস্থা সংশোধন করুন; যাচাইকরণ ব্যর্থ হলে POST /v1/phone-numbers/{id}/verify-voip চালান
409 idempotency দ্বন্দ্বশুধু মূল নর্মালাইজ করা অনুরোধের সঙ্গেই কী পুনর্ব্যবহার করুন, অথবা একটি নতুন কী পাঠান
404 from_number is not registered to this organizationনিশ্চিত করুন যে from_number আপনার সংস্থার একটি সক্রিয় ফোন নম্বরের সঙ্গে মেলে। ইতিমধ্যে প্রভিশনিং অবস্থায় থাকা, ব্যর্থ হওয়া, রিলিজ হওয়া বা রিলিজ করা নম্বরও এই প্রতিক্রিয়া দেয়
শুধু detail ফিল্ডসহ 500কোনো বহির্গামী ট্রাঙ্ক কনফিগার করা নেই। সহায়তা দলের সঙ্গে যোগাযোগ করুন; এটি এমন কোনো নম্বর-অবস্থার সমস্যা নয় যা আপনি সংশোধন করতে পারেন
502 Bad Gatewayঅস্থায়ী SIP / LiveKit ব্যর্থতা; আবার চেষ্টা করা নিরাপদ

সম্পূর্ণ স্থিতিশীল যোগ্যতা-কোড তালিকা এবং উভয় 409 প্রতিক্রিয়া বিন্যাসের জন্য বহির্গামী কলের রেফারেন্স দেখুন। অনুরোধ গ্রহণ হওয়ার পরে কিন্তু কল করার আগে কোনো সক্রিয় নম্বর অযোগ্য হয়ে গেলে, চূড়ান্ত যাচাই অ-পুনঃচেষ্টাযোগ্য 409 পেলোড ফেরত দেয়।

হোল্ড সময় নিয়ন্ত্রণ

কল প্রাপক সাড়া দিতে ধীর হওয়ার কারণে দীর্ঘ সময় চলা আউটবাউন্ড কলগুলোকে কলে max_hold_seconds দিয়ে, অথবা সংরক্ষিত এজেন্টে এটি সেট করে সীমিত করা যায় (IVR ট্রি, কিউ):

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

গত N সেকেন্ডে কোনো মানব কণ্ঠস্বর না পেলে এজেন্ট কলটি কেটে দেয়। ডিফল্ট হলো 900 সেকেন্ড (15 মিনিট)।

আপনি সংরক্ষিত এজেন্ট এবং আউটবাউন্ড কল রিকোয়েস্ট—উভয়টিতে max_hold_seconds সেট করলে, সেই কলের জন্য প্রতি-কলের মানটি ব্যবহার করা হয়।


পরবর্তী ধাপ