ഫംഗ്ഷൻ ടൂളുകൾ

സംഭാഷണത്തിനിടയിൽ ബാഹ്യ API-കളെ വിളിക്കുന്ന ഫംഗ്ഷൻ ടൂളുകൾ നിങ്ങളുടെ AI ഏജന്റുകൾക്ക് നൽകുക — ഉപഭോക്തൃ ഡാറ്റ നേടുക, അപ്പോയിന്റ്മെന്റുകൾ ബുക്ക് ചെയ്യുക, റെക്കോർഡുകൾ അപ്ഡേറ്റ് ചെയ്യുക — ടൈപ്പ് ചെയ്ത പാരാമീറ്ററുകളോടെ.

ഫംഗ്ഷൻ ടൂളുകൾ നിങ്ങളുടെ AI ഏജന്റുകൾക്ക് ഫോൺ കോളുകൾക്കിടെ ബാഹ്യ API-കൾ പ്രവർത്തിപ്പിക്കാൻ അനുവദിക്കുന്നു. ഉപഭോക്തൃ ഡാറ്റ കണ്ടെത്താനും, ലഭ്യത പരിശോധിക്കാനും, അപ്പോയിന്റ്മെന്റുകൾ ബുക്ക് ചെയ്യാനും, അല്ലെങ്കിൽ നിങ്ങളുടെ ബാക്കെൻഡ് പിന്തുണയ്ക്കുന്ന ഏതെങ്കിലും പ്രവർത്തനം നടത്താനും അവ ഉപയോഗിക്കുക.

ഇത് എങ്ങനെ പ്രവർത്തിക്കുന്നു#

1. നിങ്ങൾ ഒരു സ്കീമ ഉപയോഗിച്ച് ടൂളുകൾ നിർവചിക്കുന്നു (ടൂൾ സ്വീകരിക്കുന്ന ആർഗ്യുമെന്റുകൾ)
2. നിങ്ങൾ ഒരു endpoint കോൺഫിഗറേഷൻ നൽകുന്നു (ThunderPhone നിങ്ങളുടെ API വിളിക്കുന്ന സ്ഥലം) — അല്ലെങ്കിൽ നിങ്ങളുടെ ഓർഗനൈസേഷൻ വെബ്ഹുക്കിൽ ടൂൾ കോളുകൾ ലഭിക്കാൻ ഇത് ഒഴിവാക്കുക
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 ഒരു വാക്യത്തിന്റെ മധ്യത്തിൽ കാത്തിരിക്കുന്നു. സ്ഥിരസ്ഥിതി ടൈംഔട്ട് 20 s ആണ്; കൂടുതൽ സമയം നിർവഹിക്കാൻ അനുവദിക്കുന്നതിന് ടൂളിന്റെ മുകളിലത്തെ തലത്തിലെ timeout സജ്ജമാക്കുക, പ്ലാറ്റ്ഫോമിന്റെ 180 s പരമാവധി വരെ. ഹാൻഡ്‌ലറുകൾ വേഗത്തിൽ നിലനിർത്തുക. ഒരു മിശ്രണം ഉപയോഗിക്കാം: വെബ്ഹുക്ക് URL ഉള്ള ഓർഗനൈസേഷനിലെ കോളിൽ, 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 — കൃത്യമായ അഭ്യർത്ഥന-ബോഡി ബൈറ്റുകളുടെ HMAC-SHA256, നിങ്ങളുടെ org വെബ്ഹുക്ക് രഹസ്യം കീ ആയി ഉപയോഗിച്ചത്
• X-ThunderPhone-Call-ID — നിലവിലെ കോൾ ID

നിങ്ങളുടെ endpoint.headers അത് ഓവർറൈഡ് ചെയ്യുന്നില്ലെങ്കിൽ Content-Type: application/json സജ്ജീകരിക്കും — കസ്റ്റം Content-Type-നാണ് മുൻഗണന.

അഭ്യർത്ഥന ബോഡി#

POST / PUT / PATCH എന്നിവയ്ക്കായി, ബോഡിയിൽ റാപ്പറില്ലാതെ ടൂൾ ആർഗ്യുമെന്റുകൾ മാത്രമേ ഉണ്ടാകൂ; അവ കാനോനിക്കലായി സീരിയലൈസ് ചെയ്യപ്പെടും (സോർട്ട് ചെയ്ത കീകൾ, കോംപാക്റ്റ് സെപ്പറേറ്ററുകൾ):

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

GET / DELETE എന്നിവയ്ക്കായി, ആർഗ്യുമെന്റുകൾ ക്വറി പാരാമീറ്ററുകളായി അയയ്ക്കുകയും ബോഡി ശൂന്യമായിരിക്കുകയും ചെയ്യും — അപ്പോൾ സിഗ്നേച്ചർ ശൂന്യമായ ബൈറ്റ് സ്ട്രിങ്ങിൽ കണക്കാക്കും. കാണുക വെബ്ഹുക്ക് സിഗ്നേച്ചറുകൾ പരിശോധിക്കുക.

പ്രതികരണം#

ടൂൾ ഫലത്തോടുകൂടിയ ഒരു JSON പ്രതികരണം നൽകുക:

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

സംഭാഷണം തുടരുന്നതിനായി പ്രതികരണം ഫോർമാറ്റ് ചെയ്ത് AI-ക്ക് നൽകും. JSON അല്ലാത്ത പ്രതികരണങ്ങൾ {"data": "<text>"} ആയി റാപ്പ് ചെയ്യും; ടൈംഔട്ടുകളും കണക്ഷൻ പരാജയങ്ങളും AI-ക്ക് പിശകുകളായി റിപ്പോർട്ട് ചെയ്യും, അതിനാൽ ഏജന്റിന് ക്ഷമ ചോദിച്ച് തടസ്സപ്പെടാതെ മുന്നോട്ട് പോകാനാകും.

വെബ്ഹുക്ക്-മോഡ് ഡിസ്പാച്ച്#

endpoint ഇല്ലാത്ത ടൂളുകൾ നിങ്ങളുടെ org-ന്റെ ലെഗസി വെബ്ഹുക്ക് URL-ലേക്ക് സൈൻ ചെയ്ത telephony.tool (ഫോൺ കോൾകൾ) അല്ലെങ്കിൽ web.tool (വെബ് കോൾകൾ) അഭ്യർത്ഥനയായി ഡിസ്പാച്ച് ചെയ്യപ്പെടും. നിർവഹണത്തിന് ശേഷം വെബ്ഹുക്ക് എൻഡ്പോയിന്റുകളിലേക്ക് എത്തിക്കുന്ന ഓഡിറ്റ് അറിയിപ്പുകളിൽ നിന്ന് വ്യത്യസ്തമായി, ഈ അഭ്യർത്ഥന തന്നെയാണ് നിർവഹണം — നിങ്ങളുടെ 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 ആയി പ്രതികരിക്കുക — നേരിട്ടുള്ള എൻഡ്പോയിന്റ് കോൾകൾക്കുള്ള അതേ പ്രതികരണ കരാർ. മറ്റെല്ലാ വെബ്ഹുക്കുകളെയും പോലെ, റോ ബോഡിയിൽ org വെബ്ഹുക്ക് രഹസ്യം ഉപയോഗിച്ചാണ് അഭ്യർത്ഥന സൈൻ ചെയ്യുന്നത്.

സിഗ്നേച്ചർ പരിശോധന#

നേരിട്ടുള്ള ടൂൾ കോളുകൾ വെബ്ഹുക്കുകൾക്ക് സമാനമായ രീതിയിൽ സൈൻ ചെയ്യപ്പെടുന്നു:

• കൃത്യമായ റിക്വസ്റ്റ്-ബോഡി ബൈറ്റുകൾക്ക് മേലുള്ള 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" }
      }
    }
  ]
}

മികച്ച രീതികൾ#

ബന്ധപ്പെട്ടവ#