Zana za Function

Zana za function 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 na backend yako.

Jinsi Inavyofanya Kazi

1. Unafafanua zana kwa schema (hoja ambazo zana inakubali)
2. Unatoa usanidi wa endpoint (mahali ambapo ThunderPhone huita API yako) — au uache 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 hurejeshwa 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"
    }
  }
}

Ufafanuzi wa Function

Usanidi wa Endpoint

Njia mbili za kuita

Ombi ambalo seva yako inapokea hutegemea ikiwa zana ina endpoint:

Njia zote mbili husubiri — AI inasubiri katikati ya sentensi kwa ajili ya matokeo — zikiwa na muda wa kuisha wa sekunde 20. Weka handler ziwe za haraka. Mchanganyiko unaruhusiwa: kwenye simu ambayo org yake ina URL ya webhook, zana zenye endpoint huitwa moja kwa moja na zilizobaki hurudi kutumia webhook.

Simu za moja kwa moja za endpoint

AI inapoitisha zana iliyo na endpoint, ThunderPhone hutuma ombi kwa 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 bila kubadilishwa, pamoja na vichwa viwili vyenye nafasi ya majina ya ThunderPhone:

• X-ThunderPhone-Signature — HMAC-SHA256 ya baiti halisi za mwili wa ombi, iliyotumia 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 kanga), zilizoratibiwa kwa kanuni (funguo zilizopangwa, vitenganishi vilivyobanwa):

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

Kwa GET / DELETE, hoja hutumwa kama vigezo vya hoja na mwili huwa tupu — sahihi huhesabiwa kwenye 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 kutolewa kwa AI ili kuendeleza mazungumzo. Majibu yasiyo JSON hufungwa kama {"data": "<text>"}; muda ukiisha na hitilafu za muunganisho huripotiwa kwa AI kama hitilafu, hivyo ejenti inaweza kuomba radhi na kuendelea badala ya kusimama.

Usambazaji wa hali ya webhook

Zana zisizo na endpoint hutumwa kwa URL ya webhook ya zamani ya shirika lako kama ombi lililosainiwa la telephony.tool (simu) au web.tool (simu za wavuti). Tofauti na arifa za ukaguzi zinazopelekwa kwa 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 uleule wa jibu kama simu za moja kwa moja za endpoint. Ombi husainiwa kwa siri ya webhook ya shirika kwenye mwili ghafi, kama kila webhook nyingine.

Uthibitishaji wa Sahihi

Miito ya moja kwa moja ya zana husainiwa kwa njia sawa na webhooks:

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

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

Mapishi kamili — ikijumuisha hali ya mwili tupu na tahadhari ya kukosekana kwa 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