ਫੰਕਸ਼ਨ ਟੂਲਜ਼

ਆਪਣੇ 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 ਸਕਿੰਟ ਹੈ; ਲੰਬੇ ਐਗਜ਼ੀਕਿਊਸ਼ਨ ਦੀ ਆਗਿਆ ਦੇਣ ਲਈ ਟੂਲ ਦਾ ਟੌਪ-ਲੈਵਲ timeout ਸੈੱਟ ਕਰੋ, ਜੋ ਪਲੇਟਫਾਰਮ ਦੀ ਵੱਧ ਤੋਂ ਵੱਧ 180 ਸਕਿੰਟ ਸੀਮਾ ਤੱਕ ਹੋ ਸਕਦਾ ਹੈ। ਹੈਂਡਲਰ ਤੇਜ਼ ਰੱਖੋ। ਮਿਸ਼ਰਣ ਠੀਕ ਹੈ: ਜਿਸ ਕਾਲ ਦੀ ਸੰਸਥਾ ਕੋਲ ਵੈੱਬਹੁੱਕ 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

Content-Type: application/json ਸੈੱਟ ਕੀਤਾ ਜਾਂਦਾ ਹੈ, ਜਦੋਂ ਤੱਕ ਤੁਹਾਡੇ endpoint.headers ਇਸਨੂੰ ਓਵਰਰਾਈਡ ਨਾ ਕਰਨ — ਕਸਟਮ 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 ਵਜੋਂ ਜਵਾਬ ਵਿੱਚ ਦਿਓ — ਸਿੱਧੀਆਂ ਐਂਡਪੌਇੰਟ ਕਾਲਾਂ ਵਾਲਾ ਹੀ ਜਵਾਬ ਇਕਰਾਰਨਾਮਾ। ਬੇਨਤੀ ਨੂੰ ਹਰ ਹੋਰ ਵੈੱਬਹੁੱਕ ਵਾਂਗ, ਕੱਚੀ ਬਾਡੀ ਉੱਤੇ ਸੰਗਠਨ ਦੇ ਵੈੱਬਹੁੱਕ ਸੀਕ੍ਰੇਟ ਨਾਲ ਸਾਈਨ ਕੀਤਾ ਜਾਂਦਾ ਹੈ।

ਦਸਤਖਤ ਤਸਦੀਕ#

ਸਿੱਧੀਆਂ ਟੂਲ ਕਾਲਾਂ ਨੂੰ webhooks ਵਾਂਗ ਹੀ ਸਾਈਨ ਕੀਤਾ ਜਾਂਦਾ ਹੈ:

• ਬਿਲਕੁਲ ਸਹੀ ਬੇਨਤੀ-ਬਾਡੀ ਬਾਈਟਾਂ ਉੱਤੇ HMAC-SHA256 (canonical 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 });
});

ਪੂਰੀਆਂ ਵਿਧੀਆਂ — ਖਾਲੀ-ਬਾਡੀ ਮਾਮਲੇ ਅਤੇ 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" }
      }
    }
  ]
}

ਸਭ ਤੋਂ ਵਧੀਆ ਤਰੀਕੇ#

ਸੰਬੰਧਿਤ#