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

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

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

1. നിങ്ങൾ ഒരു സ്കീമ ഉപയോഗിച്ച് ടൂളുകൾ നിർവചിക്കുന്നു (ടൂൾ സ്വീകരിക്കുന്ന ആർഗ്യുമെന്റുകൾ)
2. നിങ്ങൾ ഒരു endpoint കോൺഫിഗറേഷൻ നൽകുന്നു (ThunderPhone നിങ്ങളുടെ API എവിടെ വിളിക്കുന്നു) — അല്ലെങ്കിൽ നിങ്ങളുടെ ഓർഗ് വെബ്ഹുക്കിൽ ടൂൾ കോളുകൾ ലഭിക്കാൻ ഇത് ഒഴിവാക്കുക
3. ഒരു കോളിനിടെ, സംഭാഷണത്തെ അടിസ്ഥാനമാക്കി ടൂൾ എപ്പോൾ ഉപയോഗിക്കണമെന്ന് AI തീരുമാനിക്കുന്നു
4. ടൂൾ ആർഗ്യുമെന്റുകൾ ഉപയോഗിച്ച് ThunderPhone നിങ്ങളുടെ എൻഡ്പോയിന്റ് വിളിക്കുന്നു
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 ഉണ്ടോ എന്നതിനെ ആശ്രയിച്ചിരിക്കും:

രണ്ട് പാതകളും ബ്ലോക്കിംഗ് ആണ് — AI വാക്യത്തിനിടയിൽ ഫലത്തിനായി കാത്തിരിക്കും — കൂടാതെ 20 സെക്കൻഡ് ടൈംഔട്ട് ഉണ്ട്. ഹാൻഡ്‌ലറുകൾ വേഗത്തിൽ നിലനിർത്തുക. മിശ്രിതം സാധ്യമാണ്: ഓർഗിന് വെബ്ഹുക്ക് 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 — നിങ്ങളുടെ org വെബ്ഹുക്ക് സീക്രട്ട് കീ ആയി ഉപയോഗിച്ചുള്ള, കൃത്യമായ അഭ്യർത്ഥന-ബോഡി ബൈറ്റുകളുടെ HMAC-SHA256
• 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" }
      }
    }
  ]
}

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

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