ફંક્શન ટૂલ્સ

તમારા AI એજન્ટોને એવા ફંક્શન ટૂલ્સ આપો જે વાતચીત દરમિયાન બાહ્ય API ને કૉલ કરે — ગ્રાહક ડેટા મેળવે, એપોઇન્ટમેન્ટ બુક કરે, રેકોર્ડ અપડેટ કરે — પ્રકાર-નિર્ધારિત પેરામીટરો સાથે.

ફંક્શન ટૂલ્સ તમારા AI એજન્ટ્સને ફોન કૉલ્સ દરમિયાન બાહ્ય APIs ઇન્વોક કરવાની મંજૂરી આપે છે. ગ્રાહક ડેટા શોધવા, ઉપલબ્ધતા તપાસવા, એપૉઇન્ટમેન્ટ બુક કરવા અથવા તમારું બેકએન્ડ સપોર્ટ કરતું કોઈપણ કાર્ય કરવા માટે તેનો ઉપયોગ કરો.

તે કેવી રીતે કાર્ય કરે છે#

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"
    }
  },
  "timeout": 120
}

ટૂલ કૉન્ફિગરેશન#

ફંક્શન વ્યાખ્યા#

એન્ડપૉઇન્ટ કૉન્ફિગરેશન#

ઇન્વોકેશનના બે માર્ગો#

તમારા સર્વરને કઈ રિક્વેસ્ટ મળે છે તે ટૂલ પાસે 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
• 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 વિનાના ટૂલ્સ તમારી સંસ્થાના લેગસી વેબહૂક 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 તરીકે પ્રતિસાદ આપો — સીધા એન્ડપૉઇન્ટ કૉલ્સ જેવો જ પ્રતિસાદ કરાર. દરેક અન્ય વેબહૂકની જેમ વિનંતી પર રૉ બૉડી વડે સંસ્થાના વેબહૂક સિક્રેટથી સહી કરવામાં આવે છે.

સહીની ચકાસણી#

સીધા ટૂલ કૉલ્સ વેબહુક્સની જેમ જ સહી કરવામાં આવે છે:

• ચોક્કસ request-body બાઇટ્સ પર HMAC-SHA256 (કેનોનિકલ JSON — સૉર્ટ કરેલી કીઝ, વધારાની ખાલી જગ્યા વિના)
• તમારા org webhook secret સાથે કીડ
• 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 });
});

ખાલી-body કેસ અને secret ન હોવાની ચેતવણી સહિતની સંપૂર્ણ રેસીપી 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" }
      }
    }
  ]
}

શ્રેષ્ઠ પદ્ધતિઓ#

સંબંધિત#