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

Developer cookbook

ওয়েব উইজেট এমবেড করুন

একটি মাত্র স্ক্রিপ্ট ট্যাগ দিয়ে আপনার মার্কেটিং বা সাপোর্ট সাইটে একটি ভয়েস এজেন্ট যোগ করুন — দর্শকরা ফোন নম্বর ছাড়াই সরাসরি ব্রাউজার থেকে এর সঙ্গে কথা বলতে পারবেন।

ওয়েব উইজেটটি ব্রাউজারের মাইক্রোফোন ব্যবহার করে আপনার সাইট ভিজিটরদের একটি AI এজেন্টের সঙ্গে ক্লিক-টু-টক কথোপকথনের সুবিধা দেয়। এটি নিজস্ব SDK রেফারেন্স সহ একটি আলাদা JavaScript / React SDK — এই গাইডটি উইজেটের প্রয়োজনীয় ThunderPhone-সাইড সেটআপের ওপর কেন্দ্রীভূত।

পূর্বশর্ত

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

    যে এজেন্টের prompt এবং ভয়েস উইজেট সেশন চালাবে। সেট করুন widget_enabled: true (ডিফল্ট)।

  2. রাউটিং মোড নির্ধারণ করুন
    • mode="agent" — প্রতি কী-তে একটি স্থির এজেন্ট। সবচেয়ে সহজ।
    • mode="webhook" — আপনার সার্ভার একটি web.incoming ওয়েবহুক-এর মাধ্যমে প্রতি ভিজিটরের জন্য এজেন্ট বেছে নেয়। লগ-ইন করা ব্যবহারকারী, A/B পরীক্ষা বা প্রতি-পৃষ্ঠা রাউটিংয়ের জন্য এটি ব্যবহার করুন।
  3. অনুমোদিত ডোমেনগুলোর তালিকা করুন

    উইজেট এম্বেড করবে এমন প্রতিটি হোস্টনেম উল্লেখ করুন। ব্রাউজার প্রতিটি সেশন অনুরোধের সঙ্গে পৃষ্ঠার উৎস পাঠায়, তাই কেউ আপনার কী অন্য সাইটে কপি করলে এই তালিকা সেটিকে কাজ করতে বাধা দেয়। এটি প্রমাণীকরণ নয়: ব্রাউজারের বাইরে থাকা একটি স্ক্রিপ্ট যেকোনো Origin হেডার পাঠাতে পারে। প্রোডাকশনে localhost স্বয়ংক্রিয়ভাবে অনুমোদিত নয়; প্রোডাকশন API-এর বিরুদ্ধে স্থানীয়ভাবে পরীক্ষা করতে তালিকায় localhost যোগ করুন।

  4. ব্রাউজার ওভাররাইড বেছে নিন

    আপনার পৃষ্ঠা কোন সেশন সেটিংস পাঠাতে পারবে তা নির্ধারণ করুন। নতুন কী কোনোটি গ্রহণ করে না; ব্রাউজার ওভাররাইড দেখুন।

একটি প্রকাশযোগ্য কী তৈরি করুন

Static agent
curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Marketing site (prod)",
    "mode":            "agent",
    "agent_id":        12,
    "allowed_domains": ["example.com", "*.example.com"],
    "allowed_overrides": ["context"]
  }'
Dynamic via webhook
curl -X POST https://api.thunderphone.com/v1/publishable-key \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name":            "Support (dynamic)",
    "mode":            "webhook",
    "webhook_url":     "https://example.com/thunderphone/widget-hook",
    "allowed_domains": ["support.example.com"]
  }'

প্রতিক্রিয়ায় pk_live_... দিয়ে শুরু হওয়া একটি key অন্তর্ভুক্ত থাকে। প্রকাশযোগ্য কী ডিজাইন অনুযায়ী সর্বজনীন — আপনার ফ্রন্ট-এন্ড বান্ডলে দেওয়া নিরাপদ। সব ফিল্ডের জন্য প্রকাশযোগ্য কী রেফারেন্স দেখুন।

আপনার সাইটে উইজেট যোগ করুন

তিনটি ইন্টিগ্রেশন বিকল্প উইজেট SDK ডকুমেন্টেশন-এ বর্ণিত আছে:

তিনটিই একই publishableKey গ্রহণ করে এবং মাইক বোতামের সঙ্গে কল চলাকালীন অডিও এলিমেন্ট রেন্ডার করে।

ব্রাউজার ওভাররাইড

উইজেট পৃষ্ঠা থেকে প্রতি-সেশনে চারটি সেটিংস পাঠাতে পারে:

সেটিংউইজেট propএটি কী পরিবর্তন করে
contextcontextপৃষ্ঠার টেক্সট, রেফারেন্স হিসেবে এজেন্টের prompt-এ যুক্ত করা হয়
variablesনেই (শুধু raw POST /v1/widget/session)prompt-এ থাকা {{variable}} প্লেসহোল্ডারের মান
voicevoiceএই সেশনের জন্য এজেন্টের কণ্ঠ
languagelanguageসেশন যে ভাষায় শুরু হয়

আপনার প্রকাশযোগ্য কী সর্বজনীন, তাই এটি যার কাছে আছে সে-ই এই সেটিংগুলো পাঠাতে পারে, এমনকি আপনার ডোমেইন নকল করে এমন কোনো স্ক্রিপ্ট থেকেও। তাই কী-তে অনুমতি না দেওয়া পর্যন্ত প্রতিটি সেটিং বন্ধ থাকে: ড্যাশবোর্ডে উইজেট তৈরি বা সম্পাদনা করার সময় ব্রাউজার ওভাররাইড-এর অধীনে এটি টিক দিন, অথবা allowed_overrides সেট করুন প্রকাশযোগ্য কী API-এর মাধ্যমে। আপনার পৃষ্ঠা আসলে যা পাঠায়, শুধু সেটিই অনুমতি দিন।

কী যে সেটিং অনুমোদন করে না, এমন সেটিং বহনকারী সেশন রিকোয়েস্ট 400 দিয়ে ব্যর্থ হয় এবং সেটির নাম জানায়:

{
  "error": "override_not_allowed",
  "fields": ["voice"],
  "message": "This publishable key does not allow the browser to set `voice`. ..."
}

পরীক্ষাটি উভয় মোডেই প্রযোজ্য। webhook মোডে অনুমোদিত একটি সেটিং আপনার web.incoming webhook-এও ফরোয়ার্ড করা হয় (context আসে website_context হিসেবে)। এই সেটিংটি চালুর আগে তৈরি করা কীগুলো চারটিই অনুমোদন করে, তাই বিদ্যমান এমবেডগুলো কাজ করতে থাকে; আপনি ব্যবহার করেন না এমনগুলো বন্ধ করুন।

উইজেটের context 12,000 অক্ষরে সীমিত করা হয় (সাধারণ ইংরেজি টেক্সটের প্রায় 3,400 টোকেন) এবং এটি মডেলগুলো যে prompt পড়ে তার অংশ, তাই দীর্ঘতর context-এর প্রতি মিনিটে খরচ বেশি। এজেন্টকে এটিকে নির্দেশনা হিসেবে নয়, পৃষ্ঠার কনটেন্ট হিসেবে বিবেচনা করতে বলা হয়।

উইজেট-মোড webhook

mode="webhook" হলে, ThunderPhone প্রতিটি সেশন শুরুর সময় আপনার webhook_url-এ একটি web.incoming payload পাঠায়। ওই ভিজিটরের জন্য আপনি যে এজেন্ট কনফিগারেশন চালাতে চান তা ফেরত দিন — এটি ফোন কলের মতো একই response schema অনুসরণ করে:

{
  "prompt":  "You are a VIP concierge for Jane Doe.",
  "voice":   "john",
  "product": "storm-base",
  "tools":   [ /* per-customer tools */ ]
}

আপনি নিজের সেশন থেকে context (কোন গ্রাহক ব্রাউজ করছেন, তাঁরা কোন পৃষ্ঠায় আছেন) prompt-এ যুক্ত করতে পারেন এবং রোলআউট অনুযায়ী এজেন্ট বদলাতে পারেন।

সেশন পর্যবেক্ষণ করুন

উইজেট সেশনগুলো দেখা যায় GET /v1/calls-এ direction="widget" সহ — ফোন কলের মতোই একই ট্রান্সক্রিপ্ট, রেকর্ডিং, গ্রেডিং এবং বিলিং। শুধু উইজেটের জন্য ড্যাশবোর্ড তৈরি করতে direction দিয়ে ফিল্টার করুন।


পরবর্তী ধাপ