--- title: "ফাংশন টুলস" description: "আপনার AI এজেন্টদের এমন ফাংশন টুল দিন যা কথোপকথনের মাঝখানে বাহ্যিক API কল করে — গ্রাহকের ডেটা আনে, অ্যাপয়েন্টমেন্ট বুক করে, রেকর্ড আপডেট করে — টাইপ করা প্যারামিটারসহ।" --- ফাংশন টুল আপনার AI এজেন্টদের ফোন কলের সময় বাহ্যিক API আহ্বান করতে দেয়। গ্রাহকের ডেটা খুঁজতে, উপলভ্যতা পরীক্ষা করতে, অ্যাপয়েন্টমেন্ট বুক করতে বা আপনার ব্যাকএন্ড সমর্থন করে এমন যেকোনো কাজ করতে এগুলো ব্যবহার করুন। ## এটি কীভাবে কাজ করে 1. আপনি একটি স্কিমাসহ টুল সংজ্ঞায়িত করেন (টুলটি কোন আর্গুমেন্ট গ্রহণ করে) 2. আপনি একটি `endpoint` কনফিগারেশন দেন (ThunderPhone কোথায় আপনার API কল করে) — অথবা আপনার org webhook-এ টুল কল পেতে এটি বাদ রাখুন 3. কল চলাকালে, কথোপকথনের ভিত্তিতে AI সিদ্ধান্ত নেয় কখন একটি টুল ব্যবহার করবে 4. ThunderPhone টুল আর্গুমেন্টসহ আপনার endpoint কল করে 5. কথোপকথন চালিয়ে যেতে আপনার API প্রতিক্রিয়া AI-তে ফেরত পাঠানো হয় | সক্ষমতা | কোথায় চলে | সেটআপ | | --- | --- | --- | | [অন্তর্নির্মিত টুল](/bn/guides/built-in-tools) | ThunderPhone | Prompt নির্দেশনা; কিছু টুলের জন্য এজেন্ট সেটিংও প্রয়োজন | | [অ্যাপ সংযোগ](/bn/guides/connect-apps) | ThunderPhone এবং সংযুক্ত প্রোভাইডার | অ্যাকাউন্ট সংযুক্ত করুন এবং অনুমোদিত অ্যাকশন যুক্ত করুন | | [API সংযোগ](/bn/guides/api-connections) এবং ফাংশন টুল | আপনার HTTP API | endpoint এবং স্কিমা সংজ্ঞায়িত করুন, অথবা webhook-এর মাধ্যমে ফাংশন কল গ্রহণ করুন | | [MCP সার্ভার](/bn/guides/mcp-servers) | একটি দূরবর্তী MCP সার্ভার | সার্ভার যোগ করুন, এর টুলগুলো আবিষ্কার করুন এবং এজেন্টের সঙ্গে যুক্ত করুন | --- ## টুল স্কিমা প্রতিটি টুল এই কাঠামো অনুসরণ করে: ```json { "type": "function", "function": { "name": "search_appointments", "description": "Find available appointment slots for a given date", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "Date in YYYY-MM-DD format" }, "service": { "type": "string", "description": "Type of service (e.g., 'consultation', 'follow-up')" } }, "required": ["date"] } }, "endpoint": { "url": "https://api.example.com/appointments/search", "method": "POST", "headers": { "X-Api-Key": "your-api-key" } }, "timeout": 120 } ``` ### টুল কনফিগারেশন | ক্ষেত্র | ধরন | প্রয়োজনীয় | বিবরণ | |-------|------|----------|-------------| | `timeout` | সংখ্যা | না | সেকেন্ডে সর্বোচ্চ এক্সিকিউশন সময় (ডিফল্ট: `20`, সর্বোচ্চ: `180`) | ### ফাংশন সংজ্ঞা | ক্ষেত্র | ধরন | প্রয়োজনীয় | বিবরণ | |-------|------|----------|-------------| | `name` | স্ট্রিং | হ্যাঁ | টুলের জন্য অনন্য শনাক্তকারী | | `description` | স্ট্রিং | হ্যাঁ | এই টুল কখন ব্যবহার করতে হবে তা AI-কে ব্যাখ্যা করে | | `parameters` | অবজেক্ট | হ্যাঁ | টুল আর্গুমেন্টের জন্য JSON Schema | ### Endpoint কনফিগারেশন | ক্ষেত্র | ধরন | প্রয়োজনীয় | বিবরণ | |-------|------|----------|-------------| | `url` | স্ট্রিং | হ্যাঁ | আপনার API endpoint URL | | `method` | স্ট্রিং | না | HTTP মেথড (ডিফল্ট: `POST`) | | `headers` | অবজেক্ট | না | অন্তর্ভুক্ত করার জন্য কাস্টম হেডার | `endpoint` কনফিগারেশনটি AI মডেলে পাঠানো হয় **না**—এটি শুধু টুল কল কার্যকর করতে ThunderPhone ব্যবহার করে। --- ## দুটি আহ্বান পাথ আপনার সার্ভার কোন অনুরোধ পাবে, তা নির্ভর করে টুলটির একটি `endpoint` আছে কি না তার ওপর: | | `endpoint` **সহ** টুল | `endpoint` **ছাড়া** টুল | |---|---|---| | অনুরোধ কোথায় যায় | সরাসরি `endpoint.url`-এ | আপনার org-এর [লিগ্যাসি webhook URL](/api-reference/organizations#legacy-single-url-webhook) | | বডি | **শুধু টুল আর্গুমেন্ট** | `telephony.tool` / `web.tool` এনভেলপ | | হেডার | আপনার `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature` | `Content-Type` + `X-ThunderPhone-Signature` | | সাইনিং কী | Org webhook secret | Org webhook secret | উভয় পাথই **ব্লকিং** — AI ফলাফলের জন্য বাক্যের মাঝখানে অপেক্ষা করে। ডিফল্ট timeout হলো **20 s**; আরও দীর্ঘ এক্সিকিউশনের অনুমতি দিতে টুলের শীর্ষ-স্তরের `timeout` সেট করুন, সর্বোচ্চ প্ল্যাটফর্ম সীমা **180 s** পর্যন্ত। হ্যান্ডলার দ্রুত রাখুন। মিশ্র ব্যবহারও সম্ভব: যে কলের org-এ একটি webhook URL আছে, সেখানে `endpoint`-সহ টুলগুলো সরাসরি কল করা হয় এবং বাকি টুলগুলো webhook-এ ফিরে যায়। ## সরাসরি endpoint কল AI যখন এমন একটি টুল আহ্বান করে যার একটি `endpoint` আছে, ThunderPhone আপনার URL-এ একটি অনুরোধ পাঠায়: ### অনুরোধ হেডার ```http POST /appointments/search HTTP/1.1 Host: api.example.com Content-Type: application/json X-ThunderPhone-Signature: abc123... X-ThunderPhone-Call-ID: 987654321 X-Api-Key: your-api-key ``` আপনার `endpoint.headers`-এর কাস্টম হেডার সবসময় হুবহু অন্তর্ভুক্ত করা হয়, সেই সঙ্গে ThunderPhone-নেমস্পেসযুক্ত দুটি হেডার: - `X-ThunderPhone-Signature` — আপনার **org webhook secret** দিয়ে কী করা, সঠিক অনুরোধ-বডির বাইটগুলোর HMAC-SHA256 - `X-ThunderPhone-Call-ID` — বর্তমান কল ID আপনার `endpoint.headers` এটি ওভাররাইড না করলে `Content-Type: application/json` সেট করা হয় — কাস্টম `Content-Type` অগ্রাধিকার পায়। স্বাক্ষরটি [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)-এর org-স্তরের webhook secret দিয়ে কী করা হয়। আপনার org কখনও লিগ্যাসি webhook কনফিগার না করে থাকলে কোনো secret থাকবে না এবং টুল কলগুলিতে **শুধুমাত্র** `X-ThunderPhone-Call-ID` থাকবে — অনুপস্থিত স্বাক্ষরে হার্ড-ফেইল করা কোনো হ্যান্ডলার সেগুলো প্রত্যাখ্যান করবে। secret পেতে লিগ্যাসি webhook কনফিগার করুন, অথবা `endpoint.headers`-এ নিজের shared secret দিন। ### অনুরোধ বডি `POST` / `PUT` / `PATCH`-এর জন্য, বডিতে **শুধুমাত্র** টুলের আর্গুমেন্ট থাকে (কোনো wrapper নেই), ক্যানোনিক্যালভাবে সিরিয়ালাইজ করা (সাজানো কী, কমপ্যাক্ট separator): ```json {"date":"2025-01-02","service":"consultation"} ``` `GET` / `DELETE`-এর জন্য, আর্গুমেন্টগুলো **query parameter** হিসেবে পাঠানো হয় এবং বডি খালি থাকে — তখন স্বাক্ষরটি খালি বাইট স্ট্রিংয়ের উপর গণনা করা হয়। দেখুন [webhook স্বাক্ষর যাচাই করুন](/bn/guides/verify-webhook-signatures)। ### প্রতিক্রিয়া টুলের ফলাফলসহ একটি JSON প্রতিক্রিয়া ফেরত দিন: ```json { "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"], "timezone": "America/Los_Angeles" } ``` প্রতিক্রিয়াটি ফরম্যাট করে কথোপকথন চালিয়ে যাওয়ার জন্য AI-কে দেওয়া হয়। নন-JSON প্রতিক্রিয়াগুলো `{"data": ""}` হিসেবে wrapper করা হয়; timeout এবং সংযোগ ব্যর্থতা AI-কে ত্রুটি হিসেবে জানানো হয়, যাতে এজেন্ট থেমে না গিয়ে ক্ষমা চেয়ে এগিয়ে যেতে পারে। ## Webhook-মোড ডিসপ্যাচ `endpoint` **ছাড়া** টুলগুলো আপনার org-এর লিগ্যাসি webhook URL-এ স্বাক্ষরিত `telephony.tool` (ফোন কল) অথবা `web.tool` (ওয়েব কল) অনুরোধ হিসেবে ডিসপ্যাচ করা হয়। এক্সিকিউশনের পরে webhook endpoint-এ পৌঁছানো [অডিট বিজ্ঞপ্তি](/bn/webhooks/events)-এর বিপরীতে, এই অনুরোধটিই **হল** এক্সিকিউশন — আপনার HTTP প্রতিক্রিয়াই টুলের ফলাফল। ```json { "type": "telephony.tool", "data": { "call_id": 987654321, "tool_name": "search_appointments", "arguments": { "date": "2026-04-21" }, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` `web.tool`, `from_number` / `to_number`-এর বদলে `origin_domain` বহন করে। টুলের ফলাফল JSON হিসেবে প্রতিক্রিয়া দিন — সরাসরি endpoint কলের মতো একই প্রতিক্রিয়া চুক্তি। অন্য সব webhook-এর মতো, raw body-র উপর org webhook secret দিয়ে অনুরোধটি স্বাক্ষরিত হয়। সাবস্ক্রাইব করা [webhook endpoint](/bn/webhooks/endpoints) প্রতিটি টুল এক্সিকিউট হওয়ার **পরে** অতিরিক্তভাবে একটি নন-ব্লকিং `telephony.tool` / `web.tool` **বিজ্ঞপ্তি পায়** (যে পথেই এটি চালানো হোক), যার মধ্যে টুলের প্রতিক্রিয়াও থাকে — অডিট ট্রেইলের জন্য উপযোগী। দেখুন [ইভেন্ট ক্যাটালগ](/bn/webhooks/events)। --- ## স্বাক্ষর যাচাইকরণ সরাসরি টুল কলগুলো ওয়েবহুকের মতো একইভাবে স্বাক্ষরিত হয়: - সঠিক request-body বাইটের ওপর HMAC-SHA256 (ক্যানোনিক্যাল JSON — সাজানো কী, অতিরিক্ত হোয়াইটস্পেস ছাড়া) - আপনার org webhook secret দিয়ে কী করা - `GET` / `DELETE` টুলগুলো খালি বাইট স্ট্রিংয়ে স্বাক্ষর করে ```python Python import hmac import hashlib def verify_tool_call(body: bytes, signature: str, secret: str) -> bool: expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) @app.post("/appointments/search") async def search_appointments(request: Request): body = await request.body() signature = request.headers.get("X-ThunderPhone-Signature", "") if not verify_tool_call(body, signature, WEBHOOK_SECRET): raise HTTPException(status_code=401) data = json.loads(body) date = data["date"] # Look up availability slots = await get_available_slots(date) return {"available_slots": slots} ``` ```javascript Node.js app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => { const signature = req.headers['x-thunderphone-signature'] || ''; const expected = crypto .createHmac('sha256', WEBHOOK_SECRET) .update(req.body) .digest('hex'); if (!signature || signature.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) { return res.status(401).send('Invalid signature'); } const { date, service } = JSON.parse(req.body); // Look up availability const slots = getAvailableSlots(date, service); res.json({ available_slots: slots }); }); ``` খালি-বডির ক্ষেত্র এবং secret না থাকার সতর্কতাসহ সম্পূর্ণ রেসিপিগুলো রয়েছে [ওয়েবহুক স্বাক্ষর যাচাই করুন](/bn/guides/verify-webhook-signatures)-এ। --- ## উদাহরণ: সম্পূর্ণ বুকিং ফ্লো এখানে একটি সম্পূর্ণ অ্যাপয়েন্টমেন্ট বুকিং সিস্টেমের জন্য টুলগুলোর একটি সেট দেওয়া হলো: ```json { "tools": [ { "type": "function", "function": { "name": "search_appointments", "description": "Find available appointment slots", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" }, "service": { "type": "string" } }, "required": ["date"] } }, "endpoint": { "url": "https://api.example.com/appointments/search", "method": "POST", "headers": { "X-Api-Key": "key" } } }, { "type": "function", "function": { "name": "book_appointment", "description": "Book an appointment at a specific time", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" }, "time": { "type": "string", "description": "HH:MM format" }, "customer_name": { "type": "string" }, "customer_phone": { "type": "string" } }, "required": ["date", "time", "customer_name"] } }, "endpoint": { "url": "https://api.example.com/appointments/book", "method": "POST", "headers": { "X-Api-Key": "key" } } }, { "type": "function", "function": { "name": "cancel_appointment", "description": "Cancel an existing appointment", "parameters": { "type": "object", "properties": { "confirmation_number": { "type": "string" } }, "required": ["confirmation_number"] } }, "endpoint": { "url": "https://api.example.com/appointments/cancel", "method": "POST", "headers": { "X-Api-Key": "key" } } } ] } ``` --- ## সেরা অনুশীলন `description` ফিল্ডটি AI-কে টুলটি **কখন** ব্যবহার করতে হবে তা বুঝতে সাহায্য করে। এটি কী করে এবং কখন উপযুক্ত, সে বিষয়ে সুনির্দিষ্ট থাকুন। AI বুঝতে পারে এমন ত্রুটি বার্তা দিন: সাধারণ 500 ত্রুটির পরিবর্তে `{"error": "No slots available for that date"}`। কথোপকথন চালিয়ে যেতে AI-এর যা প্রয়োজন, শুধু তা-ই দিন। বড় পেলোড রেসপন্সের সময় ধীর করে। সত্যিই প্রয়োজন হলে তবেই ফিল্ডকে `required` হিসেবে চিহ্নিত করুন। টুল কল করার আগে AI ব্যবহারকারীর কাছে প্রয়োজনীয় তথ্য চাইবে। --- ## সম্পর্কিত এন্ডপয়েন্ট নির্ধারণ না করেই প্ল্যাটফর্ম-পরিচালিত কল অ্যাকশন prompt করুন। HubSpot, Salesforce, Slack, Google Calendar, Google Sheets এবং Cal.com-এর জন্য প্ল্যাটফর্ম-পরিচালিত টুল — কোনো এন্ডপয়েন্ট প্রয়োজন নেই। একটি MCP সার্ভার সংযুক্ত করুন এবং এজেন্টকে এর টুল কল করতে দিন। পুনর্ব্যবহারযোগ্য REST ইন্টিগ্রেশন, যা আপনি এজেন্টের সঙ্গে সংযুক্ত করতে পারেন। Webhook এবং টুল কলের জন্য একটি যাচাইকরণ সহায়ক।