ਫੰਕਸ਼ਨ ਟੂਲ

ਫੰਕਸ਼ਨ ਟੂਲ ਤੁਹਾਡੇ AI ਏਜੰਟਾਂ ਨੂੰ ਫ਼ੋਨ ਕਾਲਾਂ ਦੌਰਾਨ ਬਾਹਰੀ API ਵਰਤਣ ਦੀ ਆਗਿਆ ਦਿੰਦੇ ਹਨ। ਇਨ੍ਹਾਂ ਦੀ ਵਰਤੋਂ ਗਾਹਕ ਡਾਟਾ ਲੱਭਣ, ਉਪਲਬਧਤਾ ਦੀ ਜਾਂਚ ਕਰਨ, ਮੁਲਾਕਾਤਾਂ ਬੁੱਕ ਕਰਨ ਜਾਂ ਤੁਹਾਡੇ ਬੈਕਐਂਡ ਵੱਲੋਂ ਸਮਰਥਿਤ ਕੋਈ ਵੀ ਕਾਰਵਾਈ ਕਰਨ ਲਈ ਕਰੋ।

ਇਹ ਕਿਵੇਂ ਕੰਮ ਕਰਦਾ ਹੈ

1. ਤੁਸੀਂ ਸਕੀਮਾ ਨਾਲ ਟੂਲ ਪਰਿਭਾਸ਼ਿਤ ਕਰਦੇ ਹੋ (ਟੂਲ ਕਿਹੜੇ ਆਰਗੂਮੈਂਟ ਸਵੀਕਾਰ ਕਰਦਾ ਹੈ)
2. ਤੁਸੀਂ ਇੱਕ endpoint ਕੌਂਫਿਗਰੇਸ਼ਨ ਦਿੰਦੇ ਹੋ (ThunderPhone ਤੁਹਾਡੀ API ਨੂੰ ਕਿੱਥੇ ਕਾਲ ਕਰਦਾ ਹੈ) — ਜਾਂ ਆਪਣੇ org ਵੈੱਬਹੁੱਕ 'ਤੇ ਟੂਲ ਕਾਲਾਂ ਪ੍ਰਾਪਤ ਕਰਨ ਲਈ ਇਸਨੂੰ ਛੱਡ ਦਿਓ
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 ਸਕਿੰਟ ਹੈ। ਹੈਂਡਲਰ ਤੇਜ਼ ਰੱਖੋ। ਮਿਲੀ-ਜੁਲੀ ਵਰਤੋਂ ਵੀ ਠੀਕ ਹੈ: ਜਿਸ ਕਾਲ ਦੇ org ਕੋਲ ਵੈੱਬਹੁੱਕ URL ਹੁੰਦਾ ਹੈ, ਉਸ ਵਿੱਚ endpoint ਵਾਲੇ ਟੂਲਾਂ ਨੂੰ ਸਿੱਧਾ ਕਾਲ ਕੀਤਾ ਜਾਂਦਾ ਹੈ ਅਤੇ ਬਾਕੀ ਵੈੱਬਹੁੱਕ 'ਤੇ ਵਾਪਸ ਜਾਂਦੇ ਹਨ।

ਸਿੱਧੀਆਂ 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, ਜੋ ਤੁਹਾਡੇ ਸੰਸਥਾ webhook ਸੀਕ੍ਰੇਟ ਨਾਲ ਕੀਅ ਕੀਤਾ ਗਿਆ ਹੈ
• X-ThunderPhone-Call-ID — ਮੌਜੂਦਾ ਕਾਲ ID

Content-Type: application/json ਸੈੱਟ ਹੁੰਦਾ ਹੈ ਜਦੋਂ ਤੱਕ ਤੁਹਾਡੇ endpoint.headers ਇਸਨੂੰ ਓਵਰਰਾਈਡ ਨਹੀਂ ਕਰਦੇ — ਕਸਟਮ Content-Type ਨੂੰ ਤਰਜੀਹ ਮਿਲਦੀ ਹੈ।

ਬੇਨਤੀ ਬਾਡੀ

POST / PUT / PATCH ਲਈ, ਬਾਡੀ ਵਿੱਚ ਸਿਰਫ਼ ਟੂਲ ਆਰਗੂਮੈਂਟ ਹੁੰਦੇ ਹਨ (ਕੋਈ ਰੈਪਰ ਨਹੀਂ), ਜੋ ਕੈਨੋਨਿਕਲ ਤਰੀਕੇ ਨਾਲ ਸੀਰੀਅਲਾਈਜ਼ ਹੁੰਦੇ ਹਨ (ਸੌਰਟ ਕੀਤੀਆਂ ਕੀਜ਼, ਸੰਖੇਪ ਸੈਪਰੇਟਰ):

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

GET / DELETE ਲਈ, ਆਰਗੂਮੈਂਟ ਕੁਏਰੀ ਪੈਰਾਮੀਟਰਾਂ ਵਜੋਂ ਭੇਜੇ ਜਾਂਦੇ ਹਨ ਅਤੇ ਬਾਡੀ ਖਾਲੀ ਹੁੰਦੀ ਹੈ — ਫਿਰ ਸਿਗਨੇਚਰ ਦੀ ਗਣਨਾ ਖਾਲੀ ਬਾਈਟ ਸਟ੍ਰਿੰਗ ਉੱਤੇ ਕੀਤੀ ਜਾਂਦੀ ਹੈ। ਵੇਖੋ webhook ਸਿਗਨੇਚਰਾਂ ਦੀ ਪੁਸ਼ਟੀ ਕਰੋ।

ਜਵਾਬ

ਟੂਲ ਨਤੀਜੇ ਦੇ ਨਾਲ ਇੱਕ JSON ਜਵਾਬ ਵਾਪਸ ਕਰੋ:

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

ਜਵਾਬ ਨੂੰ ਫਾਰਮੈਟ ਕਰਕੇ ਗੱਲਬਾਤ ਜਾਰੀ ਰੱਖਣ ਲਈ AI ਨੂੰ ਦਿੱਤਾ ਜਾਂਦਾ ਹੈ। ਗੈਰ-JSON ਜਵਾਬਾਂ ਨੂੰ {"data": "<text>"} ਵਜੋਂ ਰੈਪ ਕੀਤਾ ਜਾਂਦਾ ਹੈ; ਟਾਈਮਆਉਟ ਅਤੇ ਕਨੈਕਸ਼ਨ ਅਸਫਲਤਾਵਾਂ AI ਨੂੰ ਗਲਤੀਆਂ ਵਜੋਂ ਰਿਪੋਰਟ ਕੀਤੀਆਂ ਜਾਂਦੀਆਂ ਹਨ, ਤਾਂ ਜੋ ਏਜੰਟ ਰੁਕਣ ਦੀ ਬਜਾਏ ਮਾਫ਼ੀ ਮੰਗ ਕੇ ਅੱਗੇ ਵੱਧ ਸਕੇ।

Webhook-ਮੋਡ ਡਿਸਪੈਚ

endpoint ਤੋਂ ਬਿਨਾਂ ਟੂਲ ਤੁਹਾਡੀ ਸੰਸਥਾ ਦੇ ਲੈਗੇਸੀ 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 ਵਾਂਗ, ਰਾਅ ਬਾਡੀ ਉੱਤੇ ਸੰਸਥਾ ਦੇ webhook ਸੀਕ੍ਰੇਟ ਨਾਲ ਸਾਈਨ ਕੀਤਾ ਜਾਂਦਾ ਹੈ।

ਦਸਤਖਤ ਦੀ ਪੁਸ਼ਟੀ

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

• ਬਿਲਕੁਲ ਸਹੀ ਰਿਕਵੈਸਟ-ਬਾਡੀ ਬਾਈਟਾਂ ਉੱਤੇ HMAC-SHA256 (ਕੈਨੋਨਿਕਲ JSON — ਕ੍ਰਮਬੱਧ ਕੀਜ਼, ਕੋਈ ਵਾਧੂ ਵ੍ਹਾਈਟਸਪੇਸ ਨਹੀਂ)
• ਤੁਹਾਡੇ org ਵੈੱਬਹੁੱਕ ਸੀਕ੍ਰੇਟ ਨਾਲ ਕੀਡ
• 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" }
      }
    }
  ]
}

ਸਭ ਤੋਂ ਵਧੀਆ ਅਭਿਆਸ

ਸੰਬੰਧਿਤ