ফাংশন টুলস

আপনার AI এজেন্টদের এমন ফাংশন টুল দিন যা কথোপকথনের মাঝখানে বাহ্যিক API কল করে — গ্রাহকের ডেটা আনে, অ্যাপয়েন্টমেন্ট বুক করে, রেকর্ড আপডেট করে — টাইপ করা প্যারামিটারসহ।

ফাংশন টুল আপনার AI এজেন্টদের ফোন কলের সময় বাহ্যিক API আহ্বান করতে দেয়। গ্রাহকের ডেটা খুঁজতে, উপলভ্যতা পরীক্ষা করতে, অ্যাপয়েন্টমেন্ট বুক করতে বা আপনার ব্যাকএন্ড সমর্থন করে এমন যেকোনো কাজ করতে এগুলো ব্যবহার করুন।

এটি কীভাবে কাজ করে#

1. আপনি একটি স্কিমাসহ টুল সংজ্ঞায়িত করেন (টুলটি কোন আর্গুমেন্ট গ্রহণ করে)
2. আপনি একটি endpoint কনফিগারেশন দেন (ThunderPhone কোথায় আপনার API কল করে) — অথবা আপনার org webhook-এ টুল কল পেতে এটি বাদ রাখুন
3. কল চলাকালে, কথোপকথনের ভিত্তিতে AI সিদ্ধান্ত নেয় কখন একটি টুল ব্যবহার করবে
4. ThunderPhone টুল আর্গুমেন্টসহ আপনার endpoint কল করে
5. কথোপকথন চালিয়ে যেতে আপনার API প্রতিক্রিয়া AI-তে ফেরত পাঠানো হয়

টুল স্কিমা#

প্রতিটি টুল এই কাঠামো অনুসরণ করে:

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

টুল কনফিগারেশন#

ফাংশন সংজ্ঞা#

Endpoint কনফিগারেশন#

দুটি আহ্বান পাথ#

আপনার সার্ভার কোন অনুরোধ পাবে, তা নির্ভর করে টুলটির একটি endpoint আছে কি না তার ওপর:

উভয় পাথই ব্লকিং — AI ফলাফলের জন্য বাক্যের মাঝখানে অপেক্ষা করে। ডিফল্ট timeout হলো 20 s; আরও দীর্ঘ এক্সিকিউশনের অনুমতি দিতে টুলের শীর্ষ-স্তরের timeout সেট করুন, সর্বোচ্চ প্ল্যাটফর্ম সীমা 180 s পর্যন্ত। হ্যান্ডলার দ্রুত রাখুন। মিশ্র ব্যবহারও সম্ভব: যে কলের org-এ একটি webhook URL আছে, সেখানে endpoint-সহ টুলগুলো সরাসরি কল করা হয় এবং বাকি টুলগুলো webhook-এ ফিরে যায়।

সরাসরি endpoint কল#

AI যখন এমন একটি টুল আহ্বান করে যার একটি endpoint আছে, ThunderPhone আপনার URL-এ একটি অনুরোধ পাঠায়:

অনুরোধ হেডার#

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 অগ্রাধিকার পায়।

অনুরোধ বডি#

POST / PUT / PATCH-এর জন্য, বডিতে শুধুমাত্র টুলের আর্গুমেন্ট থাকে (কোনো wrapper নেই), ক্যানোনিক্যালভাবে সিরিয়ালাইজ করা (সাজানো কী, কমপ্যাক্ট separator):

{"date":"2025-01-02","service":"consultation"}

GET / DELETE-এর জন্য, আর্গুমেন্টগুলো query parameter হিসেবে পাঠানো হয় এবং বডি খালি থাকে — তখন স্বাক্ষরটি খালি বাইট স্ট্রিংয়ের উপর গণনা করা হয়। দেখুন webhook স্বাক্ষর যাচাই করুন।

প্রতিক্রিয়া#

টুলের ফলাফলসহ একটি JSON প্রতিক্রিয়া ফেরত দিন:

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

প্রতিক্রিয়াটি ফরম্যাট করে কথোপকথন চালিয়ে যাওয়ার জন্য AI-কে দেওয়া হয়। নন-JSON প্রতিক্রিয়াগুলো {"data": "<text>"} হিসেবে wrapper করা হয়; timeout এবং সংযোগ ব্যর্থতা AI-কে ত্রুটি হিসেবে জানানো হয়, যাতে এজেন্ট থেমে না গিয়ে ক্ষমা চেয়ে এগিয়ে যেতে পারে।

Webhook-মোড ডিসপ্যাচ#

endpoint ছাড়া টুলগুলো আপনার org-এর লিগ্যাসি webhook URL-এ স্বাক্ষরিত telephony.tool (ফোন কল) অথবা web.tool (ওয়েব কল) অনুরোধ হিসেবে ডিসপ্যাচ করা হয়। এক্সিকিউশনের পরে webhook endpoint-এ পৌঁছানো অডিট বিজ্ঞপ্তি-এর বিপরীতে, এই অনুরোধটিই হল এক্সিকিউশন — আপনার HTTP প্রতিক্রিয়াই টুলের ফলাফল।

{
  "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 দিয়ে অনুরোধটি স্বাক্ষরিত হয়।

স্বাক্ষর যাচাইকরণ#

সরাসরি টুল কলগুলো ওয়েবহুকের মতো একইভাবে স্বাক্ষরিত হয়:

• সঠিক request-body বাইটের ওপর HMAC-SHA256 (ক্যানোনিক্যাল JSON — সাজানো কী, অতিরিক্ত হোয়াইটস্পেস ছাড়া)
• আপনার org webhook secret দিয়ে কী করা
• GET / DELETE টুলগুলো খালি বাইট স্ট্রিংয়ে স্বাক্ষর করে

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}

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 না থাকার সতর্কতাসহ সম্পূর্ণ রেসিপিগুলো রয়েছে ওয়েবহুক স্বাক্ষর যাচাই করুন-এ।

উদাহরণ: সম্পূর্ণ বুকিং ফ্লো#

এখানে একটি সম্পূর্ণ অ্যাপয়েন্টমেন্ট বুকিং সিস্টেমের জন্য টুলগুলোর একটি সেট দেওয়া হলো:

{
  "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" }
      }
    }
  ]
}

সেরা অনুশীলন#

সম্পর্কিত#