ফাংশন টুলস

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

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

1. আপনি একটি স্কিমা দিয়ে টুল সংজ্ঞায়িত করেন (টুলটি কোন আর্গুমেন্ট গ্রহণ করে)
2. আপনি একটি endpoint কনফিগারেশন দেন (যেখানে ThunderPhone আপনার API কল করে) — অথবা আপনার সংস্থার 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"
    }
  }
}

ফাংশন সংজ্ঞা

Endpoint কনফিগারেশন

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

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

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

সরাসরি এন্ডপয়েন্ট কল

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 — সঠিক রিকোয়েস্ট-বডি বাইটের HMAC-SHA256, যা আপনার org webhook secret দিয়ে কী করা হয়
• X-ThunderPhone-Call-ID — বর্তমান কল ID

আপনার endpoint.headers এটিকে ওভাররাইড না করলে Content-Type: application/json সেট করা হয় — কাস্টম Content-Type অগ্রাধিকার পায়।

রিকোয়েস্ট বডি

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

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

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

রেসপন্স

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

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

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

webhook-মোড ডিসপ্যাচ

endpoint ছাড়া টুলগুলো আপনার org-এর লিগ্যাসি webhook URL-এ সাইন করা telephony.tool (ফোন কল) অথবা web.tool (ওয়েব কল) রিকোয়েস্ট হিসেবে ডিসপ্যাচ করা হয়। এক্সিকিউশনের পরে webhook এন্ডপয়েন্টে পৌঁছানো অডিট নোটিফিকেশন-এর বিপরীতে, এই রিকোয়েস্টটিই হল এক্সিকিউশন — আপনার 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 হিসেবে রেসপন্ড করুন — সরাসরি এন্ডপয়েন্ট কলের মতো একই রেসপন্স কন্ট্র্যাক্ট। অন্যান্য সব webhook-এর মতো, রিকোয়েস্টটি raw বডির ওপর org webhook secret দিয়ে সাইন করা হয়।

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

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

• সঠিক request-body বাইটের উপর HMAC-SHA256 (ক্যানোনিক্যাল JSON — সাজানো কী, অতিরিক্ত কোনো ফাঁকা স্থান নেই)
• আপনার অর্গানাইজেশনের ওয়েবহুক সিক্রেট দিয়ে কী করা
• 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 });
});

খালি-বডির ক্ষেত্র এবং সিক্রেট না থাকলে প্রযোজ্য সতর্কতাসহ সম্পূর্ণ রেসিপিগুলো ওয়েবহুক স্বাক্ষর যাচাই করুন-এ রয়েছে।

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

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

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

সর্বোত্তম অনুশীলন

সম্পর্কিত