Funkciju rīki

Funkciju rīki ļauj jūsu balss aģentiem tālruņa zvanu laikā izsaukt ārējas API. Izmantojiet tos, lai meklētu klientu datus, pārbaudītu pieejamību, rezervētu tikšanās vai veiktu jebkuru darbību, ko atbalsta jūsu aizmugursistēma.

Kā tas darbojas

Definējiet rīkus ar shēmu (kādus argumentus rīks pieņem)
Norādiet endpoint konfigurāciju (kur ThunderPhone izsauc jūsu API) — vai neiekļaujiet to, lai rīku izsaukumus saņemtu organizācijas webhook
Zvanu laikā AI, pamatojoties uz sarunu, izlemj, kad izmantot rīku
ThunderPhone izsauc jūsu galapunktu ar rīka argumentiem
Jūsu API atbilde tiek nodota atpakaļ AI, lai turpinātu sarunu

Funkciju rīki ir iespēja izmantot savu API. ThunderPhone piedāvā arī platformas pārvaldītus rīkus, kuriem nav nepieciešams galapunkts: lietotņu savienojumi (HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, Cal.com), API savienojumi un MCP serveri.

Rīka shēma

Katrs rīks izmanto šādu struktūru:

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

Funkcijas definīcija

Lauks	Tips	Obligāts	Apraksts
`name`	string	Jā	Unikāls rīka identifikators
`description`	string	Jā	Norāda AI, kad izmantot šo rīku
`parameters`	object	Jā	JSON shēma rīka argumentiem

Galapunkta konfigurācija

Lauks	Tips	Obligāts	Apraksts
`url`	string	Jā	Jūsu API galapunkta URL
`method`	string	Nē	HTTP metode (noklusējums: `POST`)
`headers`	object	Nē	Iekļaujamās pielāgotās galvenes

endpoint konfigurācija AI modelim netiek nosūtīta — ThunderPhone to izmanto tikai rīka izsaukuma izpildei.

Divi izsaukšanas ceļi

Tas, kuru pieprasījumu saņem jūsu serveris, ir atkarīgs no tā, vai rīkam ir endpoint:

	Rīks ar `endpoint`	Rīks bez `endpoint`
Kur tiek nosūtīts pieprasījums	Tieši uz `endpoint.url`	Jūsu organizācijas mantotā webhook URL
Pamatteksts	Tikai rīka argumenti	`telephony.tool` / `web.tool` aploksne
Galvenes	Jūsu `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
Parakstīšanas atslēga	Organizācijas webhook noslēpums	Organizācijas webhook noslēpums

Abi ceļi ir bloķējoši — AI rezultātu gaida teikuma vidū — un tiem ir 20 s noildze. Nodrošiniet ātru apstrādātāju darbību. Var izmantot abus: zvanā, kura organizācijai ir webhook URL, rīki ar endpoint tiek izsaukti tieši, bet pārējiem tiek izmantots webhook.

Tiešie galapunktu izsaukumi

Kad AI izsauc rīku, kuram ir endpoint, ThunderPhone nosūta pieprasījumu uz jūsu URL:

Pieprasījuma galvenes

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

Pielāgotās galvenes no jūsu endpoint.headers vienmēr tiek iekļautas burtiski, kā arī divas ThunderPhone vārdtelpas galvenes:

X-ThunderPhone-Signature — precīzo pieprasījuma pamatteksta baitu HMAC-SHA256, izmantojot jūsu organizācijas tīmekļa aizķeres noslēpumu
X-ThunderPhone-Call-ID — pašreizējās sarunas ID

Content-Type: application/json tiek iestatīts, ja vien jūsu endpoint.headers to nepārraksta — pielāgots Content-Type ir noteicošais.

Parakstam tiek izmantots organizācijas līmeņa tīmekļa aizķeres noslēpums no GET /v1/webhook. Ja jūsu organizācija nekad nav konfigurējusi mantoto tīmekļa aizķeri, noslēpuma nav, un rīku izsaukumos ir tikai X-ThunderPhone-Call-ID — apstrādātājs, kas pārtrauc darbu, ja paraksta nav, tos noraidīs. Vai nu konfigurējiet mantoto tīmekļa aizķeri, lai iegūtu noslēpumu, vai ievietojiet savu koplietojamo noslēpumu sadaļā endpoint.headers.

Pieprasījuma pamatteksts

POST / PUT / PATCH pieprasījumiem pamattekstā ir tikai rīka argumenti (bez aplauka), kas serializēti kanoniski (sakārtotas atslēgas, kompakti atdalītāji):

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

GET / DELETE pieprasījumiem argumenti tiek nosūtīti kā vaicājuma parametri, un pamatteksts ir tukšs — paraksts tad tiek aprēķināts tukšajai baitu virknei. Skatiet Tīmekļa aizķeres parakstu pārbaude.

Atbilde

Atgrieziet JSON atbildi ar rīka rezultātu:

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

Atbilde tiek formatēta un nodota AI, lai turpinātu sarunu. Atbildes, kas nav JSON, tiek ietītas kā {"data": "<text>"}; par noildzēm un savienojuma kļūmēm AI tiek ziņots kā par kļūdām, lai balss aģents varētu atvainoties un turpināt, nevis apstāties.

Nosūtīšana tīmekļa aizķeres režīmā

Rīki bez endpoint tiek nosūtīti uz jūsu organizācijas mantotās tīmekļa aizķeres URL kā parakstīts telephony.tool (tālruņa zvani) vai web.tool (tīmekļa zvani) pieprasījums. Atšķirībā no audita paziņojumiem, kas pēc izpildes tiek piegādāti tīmekļa aizķeres galapunktiem, šis pieprasījums ir izpilde — jūsu HTTP atbilde ir rīka rezultāts.

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

web.tool satur origin_domain, nevis from_number / to_number. Atbildiet ar rīka rezultātu JSON formātā — tas ir tas pats atbildes līgums kā tiešajiem galapunktu izsaukumiem. Pieprasījums tiek parakstīts ar organizācijas tīmekļa aizķeres noslēpumu, izmantojot neapstrādāto pamattekstu, tāpat kā katra cita tīmekļa aizķere.

Abonētie tīmekļa aizķeres galapunkti papildus saņem neblokējošu telephony.tool / web.tool paziņojumu pēc katra rīka izpildes (neatkarīgi no ceļa, kas to izpildīja), tostarp rīka atbildi — noderīgi audita pierakstiem. Skatiet notikumu katalogu.

Paraksta verificēšana

Tiešie rīku izsaukumi tiek parakstīti tāpat kā tīmekļa aizķeres:

HMAC-SHA256, izmantojot precīzus pieprasījuma pamatteksta baitus (kanoniskais JSON — sakārtotas atslēgas, bez papildu atstarpēm)
Ar jūsu organizācijas tīmekļa aizķeres noslēpumu
GET / DELETE rīki paraksta tukšu baitu virkni

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

Pilnas receptes — tostarp tukša pamatteksta gadījumam un situācijai, kad nav noslēpuma, — ir pieejamas sadaļā Tīmekļa aizķeres parakstu verificēšana.

Piemērs: pilnīga rezervēšanas plūsma

Šeit ir rīku kopa pilnīgai pierakstu rezervēšanas sistēmai:

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

Paraugprakse

Rakstiet skaidrus aprakstus

Lauks description palīdz MI saprast, kad izmantot rīku. Konkrēti norādiet, ko tas dara un kad to ir lietderīgi izmantot.

Kļūdas apstrādājiet korekti

Atgrieziet MI saprotamus kļūdu ziņojumus: {"error": "No slots available for that date"} vispārīgu 500 kļūdu vietā.

Saglabājiet atbildes īsas

Atgrieziet tikai to, kas MI nepieciešams sarunas turpināšanai. Lielas datu paketes palēnina atbildes laiku.

Pārdomāti izmantojiet obligātos laukus

Atzīmējiet laukus kā required tikai tad, ja tas patiešām ir nepieciešams. Pirms rīka izsaukšanas MI lūgs lietotājam norādīt obligāto informāciju.

Saistītā informācija

Lietotņu savienojumi

Platformas pārvaldīti rīki HubSpot, Salesforce, Slack, Google Calendar, Google Sheets un Cal.com — galapunkts nav nepieciešams.

MCP serveri

Pievienojiet MCP serveri un ļaujiet balss aģentam izsaukt tā rīkus.

API savienojumi

Atkārtoti izmantojamas REST integrācijas, ko varat pievienot balss aģentiem.

Pārbaudiet tīmekļa aizķeres parakstus

Viens pārbaudes palīgrīks tīmekļa aizķerēm un rīku izsaukumiem.

Webhooks

Function Tools

Kā tas darbojas

Rīka shēma

Funkcijas definīcija

Galapunkta konfigurācija

Divi izsaukšanas ceļi

Tiešie galapunktu izsaukumi

Pieprasījuma galvenes

Pieprasījuma pamatteksts

Atbilde

Nosūtīšana tīmekļa aizķeres režīmā

Paraksta verificēšana

Piemērs: pilnīga rezervēšanas plūsma

Paraugprakse

Saistītā informācija

Lietotņu savienojumi

MCP serveri

API savienojumi

Pārbaudiet tīmekļa aizķeres parakstus

​Kā tas darbojas

​Rīka shēma

​Funkcijas definīcija

​Galapunkta konfigurācija

​Divi izsaukšanas ceļi

​Tiešie galapunktu izsaukumi

​Pieprasījuma galvenes

​Pieprasījuma pamatteksts

​Atbilde

​Nosūtīšana tīmekļa aizķeres režīmā

​Paraksta verificēšana

​Piemērs: pilnīga rezervēšanas plūsma

​Paraugprakse

​Saistītā informācija

Lietotņu savienojumi

MCP serveri

API savienojumi

Pārbaudiet tīmekļa aizķeres parakstus

Kā tas darbojas

Rīka shēma

Funkcijas definīcija

Galapunkta konfigurācija

Divi izsaukšanas ceļi

Tiešie galapunktu izsaukumi

Pieprasījuma galvenes

Pieprasījuma pamatteksts

Atbilde

Nosūtīšana tīmekļa aizķeres režīmā

Paraksta verificēšana

Piemērs: pilnīga rezervēšanas plūsma

Paraugprakse

Saistītā informācija