ફંક્શન ટૂલ્સ

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

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

1. તમે સ્કીમા સાથે ટૂલ્સ નિર્ધારિત કરો છો (ટૂલ કયા આર્ગ્યુમેન્ટ્સ સ્વીકારે છે)
2. તમે endpoint કૉન્ફિગરેશન આપો છો (ThunderPhone તમારી API ને ક્યાં કૉલ કરે છે) — અથવા તમારી સંસ્થાના webhook પર ટૂલ કૉલ્સ મેળવવા માટે તેને છોડો
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 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 — તમારા org webhook secret વડે કી કરાયેલા ચોક્કસ વિનંતી-બોડી બાઇટ્સનો HMAC-SHA256
• X-ThunderPhone-Call-ID — વર્તમાન કૉલ ID

જ્યાં સુધી તમારા endpoint.headers તેને ઓવરરાઇડ ન કરે ત્યાં સુધી Content-Type: application/json સેટ કરવામાં આવે છે — કસ્ટમ Content-Type ને પ્રાધાન્ય મળે છે.

વિનંતી બોડી

POST / PUT / PATCH માટે, બોડીમાં માત્ર ટૂલ arguments હોય છે (કોઈ wrapper નહીં), અને તે કેનોનિકલી સિરિયલાઇઝ થયેલા હોય છે (સૉર્ટ કરેલી કીઝ, કોમ્પેક્ટ separators):

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

GET / DELETE માટે, arguments query parameters તરીકે મોકલવામાં આવે છે અને બોડી ખાલી હોય છે — ત્યારબાદ સિગ્નેચર ખાલી બાઇટ સ્ટ્રિંગ પર ગણવામાં આવે છે. જુઓ webhook સિગ્નેચર્સ ચકાસો.

પ્રતિસાદ

ટૂલ પરિણામ સાથે JSON પ્રતિસાદ પરત કરો:

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

પ્રતિસાદને ફોર્મેટ કરીને વાતચીત ચાલુ રાખવા માટે AI ને આપવામાં આવે છે. નોન-JSON પ્રતિસાદો {"data": "<text>"} તરીકે રૅપ કરવામાં આવે છે; ટાઇમઆઉટ્સ અને કનેક્શન નિષ્ફળતાઓ AI ને errors તરીકે રિપોર્ટ કરવામાં આવે છે, જેથી એજન્ટ અટકી જવાને બદલે માફી માગીને આગળ વધી શકે.

Webhook-મોડ ડિસ્પૅચ

endpoint વિનાનાં ટૂલ્સ તમારી org ના લેગસી webhook URL પર સાઇન કરેલી telephony.tool (ફોન કૉલ્સ) અથવા web.tool (વેબ કૉલ્સ) વિનંતી તરીકે ડિસ્પૅચ થાય છે. એક્ઝિક્યુશન પછી webhook endpoints પર મોકલવામાં આવતી ઓડિટ સૂચનાઓ થી વિપરીત, આ વિનંતી જ એક્ઝિક્યુશન છે — તમારો 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 તરીકે પ્રતિસાદ આપો — સીધી endpoint કૉલ્સ જેવો જ પ્રતિસાદ કરાર. દરેક અન્ય webhook ની જેમ, વિનંતી org webhook secret વડે raw body પર સાઇન કરવામાં આવે છે.

સહીની ચકાસણી

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

• ચોક્કસ request-body બાઇટ્સ પર 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 });
});

ખાલી-body કેસ અને સિક્રેટ ન હોવાની ચેતવણી સહિતની સંપૂર્ણ રેસીપી વેબહુક સહી ચકાસો માં છે.

ઉદાહરણ: સંપૂર્ણ બુકિંગ ફ્લો

સંપૂર્ણ એપોઇન્ટમેન્ટ બુકિંગ સિસ્ટમ માટે ટૂલ્સનો એક સેટ અહીં છે:

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

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

સંબંધિત