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

உங்கள் AI ஏஜென்ட்களுக்கு உரையாடலின் நடுவில் வெளிப்புற API-களை அழைக்கும் செயல்பாட்டு கருவிகளை வழங்குங்கள் — வாடிக்கையாளர் தரவைப் பெறுங்கள், சந்திப்புகளைப் பதிவு செய்யுங்கள், பதிவுகளைப் புதுப்பியுங்கள் — வகை குறிப்பிடப்பட்ட அளவுருக்களுடன்.

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

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

1. நீங்கள் ஒரு schema-வுடன் கருவிகளை வரையறுக்கிறீர்கள் (கருவி ஏற்கும் arguments என்ன)
2. நீங்கள் endpoint உள்ளமைவை வழங்குகிறீர்கள் (ThunderPhone உங்கள் API-ஐ எங்கு அழைக்கும்) — அல்லது உங்கள் நிறுவன webhook-இல் கருவி அழைப்புகளைப் பெற அதை விடலாம்
3. அழைப்பின் போது, உரையாடலின் அடிப்படையில் கருவியை எப்போது பயன்படுத்த வேண்டும் என்பதை AI தீர்மானிக்கிறது
4. ThunderPhone கருவி arguments-உடன் உங்கள் endpoint-ஐ அழைக்கிறது
5. உரையாடலைத் தொடர உங்கள் API பதில் மீண்டும் AI-க்கு வழங்கப்படுகிறது

கருவி Schema#

ஒவ்வொரு கருவியும் இந்த அமைப்பைப் பின்பற்றுகிறது:

{
  "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, வாக்கியத்தின் நடுவில் முடிவுக்காகக் காத்திருக்கிறது. இயல்புநிலை நேர முடிவு 20 s; நீண்ட செயல்பாட்டு நேரத்தை அனுமதிக்க, கருவியின் மேல்நிலை timeout-ஐ அமைக்கவும்; தளத்தின் அதிகபட்சம் 180 s வரை அனுமதிக்கப்படுகிறது. கையாளிகளை வேகமாக வைத்திருக்கவும். கலவையாகப் பயன்படுத்தலாம்: 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 — உங்கள் நிறுவன webhook ரகசியத்தை விசையாகக் கொண்டு, துல்லியமான கோரிக்கை-உடல் பைட்களின் HMAC-SHA256
• X-ThunderPhone-Call-ID — தற்போதைய அழைப்பு ID

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

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

POST / PUT / PATCH-க்கு, உடலில் மட்டும் கருவி வாதங்கள் இருக்கும் (wrapper இல்லை); அவை நியமமான வடிவில் (வரிசைப்படுத்தப்பட்ட விசைகள், சுருக்கமான பிரிப்பான்கள்) வரிசைப்படுத்தப்படும்:

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

GET / DELETE-க்கு, வாதங்கள் வினவல் அளவுருக்களாக அனுப்பப்படும்; உடல் காலியாக இருக்கும் — பின்னர் கையொப்பம் காலியான பைட் சரத்தின் மீது கணக்கிடப்படும். பார்க்கவும் webhook கையொப்பங்களைச் சரிபார்க்கவும்.

பதில்#

கருவி முடிவுடன் JSON பதிலை வழங்கவும்:

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

பதில் வடிவமைக்கப்பட்டு, உரையாடலைத் தொடர AI-க்கு வழங்கப்படும். JSON அல்லாத பதில்கள் {"data": "<text>"} எனச் சுற்றிவைக்கப்படும்; நேரம் முடிதல் மற்றும் இணைப்புத் தோல்விகள் AI-க்கு பிழைகளாகத் தெரிவிக்கப்படும், எனவே ஏஜென்ட் மன்னிப்பு கேட்டு நின்றுபோகாமல் தொடர முடியும்.

Webhook-முறை அனுப்புதல்#

endpoint இல்லாத கருவிகள், உங்கள் நிறுவனத்தின் பழைய 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-ஐப் போலவே, கோரிக்கையும் மூல உடலின் மீது நிறுவன webhook ரகசியத்துடன் கையொப்பமிடப்படும்.

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

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

• துல்லியமான request-body பைட்டுகளின் மீது HMAC-SHA256 (நியம JSON — வரிசைப்படுத்தப்பட்ட keys, கூடுதல் whitespace இல்லை)
• உங்கள் org webhook secret-ஐப் பயன்படுத்தி key செய்யப்படுகிறது
• GET / DELETE tools காலியான 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 நிகழ்வு மற்றும் secret இல்லாதபோதான எச்சரிக்கை உட்பட முழுமையான வழிமுறைகள் webhook கையொப்பங்களைச் சரிபார்க்கவும் என்பதில் உள்ளன.

எடுத்துக்காட்டு: முழுமையான முன்பதிவு ஓட்டம்#

முழுமையான appointment முன்பதிவு அமைப்பிற்கான tools தொகுப்பு இதோ:

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

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

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