செயல்பாட்டு கருவிகள்

செயல்பாட்டு கருவிகள், தொலைபேசி அழைப்புகளின்போது உங்கள் AI ஏஜென்ட்கள் வெளிப்புற API-களை அழைக்க அனுமதிக்கின்றன. வாடிக்கையாளர் தரவைத் தேட, இருப்பைக் சரிபார்க்க, சந்திப்புகளை முன்பதிவு செய்ய அல்லது உங்கள் பேக்கெண்ட் ஆதரிக்கும் எந்தச் செயலையும் செய்ய அவற்றைப் பயன்படுத்துங்கள்.

இது எப்படி செயல்படுகிறது

1. நீங்கள் ஒரு ஸ்கீமாவுடன் கருவிகளை வரையறுக்கிறீர்கள் (கருவி ஏற்கும் ஆர்க்யூமென்ட்கள்)
2. நீங்கள் ஒரு endpoint உள்ளமைவை வழங்குகிறீர்கள் (ThunderPhone உங்கள் API-ஐ அழைக்கும் இடம்) — அல்லது உங்கள் org வெப்ஹுக்கில் கருவி அழைப்புகளைப் பெற அதை விடுங்கள்
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 வி நேர முடிவைக் கொண்டுள்ளன. ஹேண்ட்லர்களை வேகமாக வைத்திருங்கள். கலவையாகப் பயன்படுத்தலாம்: வெப்ஹுக் URL கொண்ட org-இன் அழைப்பில், endpoint உள்ள கருவிகள் நேரடியாக அழைக்கப்படும்; மீதமுள்ளவை வெப்ஹுக்கிற்கு மாற்றாகச் செல்லும்.

நேரடி 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 ரகசியம் கொண்டு key செய்யப்பட்ட துல்லியமான கோரிக்கை-body பைட்டுகளின் HMAC-SHA256
• X-ThunderPhone-Call-ID — தற்போதைய அழைப்பு ID

உங்கள் endpoint.headers அதை மேலெழுதாத வரை Content-Type: application/json அமைக்கப்படும் — தனிப்பயன் Content-Type-க்கே முன்னுரிமை.

கோரிக்கை உடல்

POST / PUT / PATCH க்கு, body-யில் கருவி arguments மட்டுமே இருக்கும் (wrapper எதுவும் இல்லை); அவை நியமமான முறையில் வரிசைப்படுத்தப்படும் (வரிசைப்படுத்தப்பட்ட keys, சுருக்கமான பிரிப்பான்கள்):

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

GET / DELETE க்கு, arguments query parameters ஆக அனுப்பப்படும்; body காலியாக இருக்கும் — கையொப்பம் பின்னர் காலியான byte string மீது கணக்கிடப்படும். Webhook கையொப்பங்களைச் சரிபார்க்கவும் என்பதைப் பார்க்கவும்.

பதில்

கருவி முடிவுடன் ஒரு JSON பதிலைத் திருப்பி அனுப்பவும்:

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

பதில் வடிவமைக்கப்பட்டு, உரையாடலைத் தொடர AI-க்கு வழங்கப்படும். JSON அல்லாத பதில்கள் {"data": "<text>"} என மூடப்படும்; 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-ஐக் கொண்டிருக்கும். நேரடி endpoint அழைப்புகளைப் போலவே, கருவி முடிவை JSON ஆகப் பதிலளிக்கவும். மற்ற எல்லா webhook-களையும் போல, கோரிக்கை raw body மீது org webhook ரகசியத்தைக் கொண்டு கையொப்பமிடப்படும்.

கையொப்பச் சரிபார்ப்பு

நேரடி டூல் அழைப்புகள் webhooks போலவே கையொப்பமிடப்படுகின்றன:

• துல்லியமான கோரிக்கை-body பைட்களில் HMAC-SHA256 (கேனானிக்கல் JSON — வரிசைப்படுத்தப்பட்ட keys, கூடுதல் வெற்றிடங்கள் இல்லை)
• உங்கள் org webhook ரகசியத்தால் key செய்யப்படும்
• GET / DELETE டூல்கள் காலியான byte string-க்கு கையொப்பமிடும்

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 });
});

காலியான-body நிலை மற்றும் ரகசியம் இல்லாததற்கான எச்சரிக்கை உட்பட முழுமையான வழிமுறைகள் webhook கையொப்பங்களைச் சரிபார்க்கவும் பகுதியில் உள்ளன.

எடுத்துக்காட்டு: முழுமையான முன்பதிவு செயலோட்டம்

முழுமையான சந்திப்பு முன்பதிவு அமைப்பிற்கான டூல்களின் தொகுப்பு இதோ:

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

சிறந்த நடைமுறைகள்

தொடர்புடையவை