Zana za Function

Wape ejenti zako za AI zana za function zinazopiga API za nje katikati ya mazungumzo — kupata data za wateja, kuweka miadi, kusasisha rekodi — zikiwa na vigezo vilivyoainishwa kwa aina.

Zana za vitendaji huruhusu ejenti zako za AI kuita API za nje wakati wa simu. Zitumie kutafuta data ya mteja, kuangalia upatikanaji, kuweka miadi, au kutekeleza hatua yoyote inayotumika kwenye backend yako.

Jinsi Inavyofanya Kazi#

1. Unafafanua zana kwa schema (hoja ambazo zana inakubali)
2. Unatoa usanidi wa endpoint (mahali ThunderPhone inapoita API yako) — au uiachie ili upokee miito ya zana kwenye webhook ya org yako
3. Wakati wa simu, AI huamua wakati wa kutumia zana kulingana na mazungumzo
4. ThunderPhone huita endpoint yako kwa hoja za zana
5. Jibu la API yako hurudishwa kwa AI ili kuendeleza mazungumzo

Schema ya Zana#

Kila zana hufuata muundo huu:

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

Usanidi wa Zana#

Ufafanuzi wa Kitendaji#

Usanidi wa Endpoint#

Njia mbili za kuita#

Ombi ambalo seva yako inapokea hutegemea ikiwa zana ina endpoint:

Njia zote mbili huzuia — AI inasubiri katikati ya sentensi kupata matokeo. Muda chaguo-msingi wa kuisha ni 20 s; weka timeout ya kiwango cha juu ya zana ili kuruhusu utekelezaji mrefu zaidi, hadi kiwango cha juu cha mfumo cha 180 s. Weka handler ziwe za haraka. Mchanganyiko unaruhusiwa: kwenye simu ambayo org yake ina URL ya webhook, zana zilizo na endpoint huitwa moja kwa moja na nyingine hurudi kwenye webhook.

Miito ya moja kwa moja ya endpoint#

Wakati AI inapoita zana yenye endpoint, ThunderPhone hutuma ombi kwenye URL yako:

Vichwa vya Ombi#

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

Vichwa maalum kutoka kwenye endpoint.headers yako hujumuishwa kila wakati kama yalivyo, pamoja na vichwa viwili vilivyo na nafasi ya majina ya ThunderPhone:

• X-ThunderPhone-Signature — HMAC-SHA256 ya baiti kamili za mwili wa ombi, inayotumia siri ya webhook ya shirika lako kama ufunguo
• X-ThunderPhone-Call-ID — Kitambulisho cha simu ya sasa

Content-Type: application/json huwekwa isipokuwa endpoint.headers yako iibadilishe — Content-Type maalum hupewa kipaumbele.

Mwili wa Ombi#

Kwa POST / PUT / PATCH, mwili una pekee hoja za zana (bila kifuniko), zilizoserialishwa kwa mpangilio thabiti (funguo zilizopangwa, vitenganishi finyu):

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

Kwa GET / DELETE, hoja hutumwa kama vigezo vya hoja na mwili huwa tupu — sahihi huhesabiwa juu ya mfuatano tupu wa baiti. Tazama Thibitisha sahihi za webhook.

Jibu#

Rudisha jibu la JSON lenye matokeo ya zana:

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

Jibu hupangwa na kupewa AI ili kuendeleza mazungumzo. Majibu yasiyo ya JSON hufunikwa kama {"data": "<text>"}; muda kuisha na hitilafu za muunganisho huripotiwa kwa AI kama hitilafu, hivyo ejenti inaweza kuomba msamaha na kuendelea badala ya kusita.

Uelekezaji wa hali ya webhook#

Zana zisizo na endpoint huelekezwa kwenye URL ya webhook ya zamani ya shirika lako kama ombi lililotiwa sahihi la telephony.tool (simu) au web.tool (miito ya wavuti). Tofauti na arifa za ukaguzi zinazowasilishwa kwenye endpoint za webhook baada ya utekelezaji, ombi hili ndilo utekelezaji — jibu lako la HTTP ndilo matokeo ya zana.

{
  "type": "telephony.tool",
  "data": {
    "call_id": 987654321,
    "tool_name": "search_appointments",
    "arguments": { "date": "2026-04-21" },
    "from_number": "+14155550199",
    "to_number": "+15551234567"
  }
}

web.tool hubeba origin_domain badala ya from_number / to_number. Jibu kwa matokeo ya zana kama JSON — mkataba sawa wa jibu kama miito ya moja kwa moja ya endpoint. Ombi hutiwa sahihi kwa siri ya webhook ya shirika juu ya mwili ghafi, kama webhook nyingine yoyote.

Uthibitishaji wa Sahihi#

Miito ya moja kwa moja ya zana husainiwa kwa njia ileile kama webhook:

• HMAC-SHA256 juu ya baiti halisi za ombi (JSON sanifu — funguo zilizopangwa, bila nafasi za ziada)
• Kwa kutumia siri ya webhook ya shirika lako kama ufunguo
• Zana za GET / DELETE husaini mfuatano wa baiti tupu

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 });
});

Maelekezo kamili — ikiwemo hali ya mwili tupu na tahadhari ya kutokuwa na siri — yapo katika Thibitisha sahihi za webhook.

Mfano: Mtiririko Kamili wa Kuhifadhi Miadi#

Hii ni seti ya zana za mfumo kamili wa kuhifadhi miadi:

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

Mbinu Bora#

Yanayohusiana#