Instrumente de funcții

Instrumentele de funcție le permit agenților dvs. AI să invoce API-uri externe în timpul apelurilor telefonice. Folosiți-le pentru a căuta date despre clienți, a verifica disponibilitatea, a programa întâlniri sau a efectua orice acțiune acceptată de backendul dvs.

Cum funcționează

Definiți instrumente cu o schemă (ce argumente acceptă instrumentul)
Furnizați o configurație endpoint (unde ThunderPhone apelează API-ul dvs.) — sau omiteți-o pentru a primi apeluri de instrumente pe webhookul organizației dvs.
În timpul unui apel, AI-ul decide când să utilizeze un instrument pe baza conversației
ThunderPhone apelează endpointul dvs. cu argumentele instrumentului
Răspunsul API-ului dvs. este transmis înapoi AI-ului pentru a continua conversația

Instrumentele de funcție reprezintă opțiunea în care vă furnizați propriul API. ThunderPhone oferă și instrumente gestionate de platformă, care nu necesită endpoint: conexiuni de aplicații (HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, Cal.com), conexiuni API și servere MCP.

Schema instrumentului

Fiecare instrument urmează această structură:

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

Definiția funcției

Câmp	Tip	Obligatoriu	Descriere
`name`	șir	Da	Identificator unic pentru instrument
`description`	șir	Da	Explică AI-ului când să utilizeze acest instrument
`parameters`	obiect	Da	Schemă JSON pentru argumentele instrumentului

Configurarea endpointului

Câmp	Tip	Obligatoriu	Descriere
`url`	șir	Da	URL-ul endpointului API-ului dvs.
`method`	șir	Nu	Metodă HTTP (implicit: `POST`)
`headers`	obiect	Nu	Antete personalizate de inclus

Configurația endpoint nu este trimisă modelului AI — este utilizată doar de ThunderPhone pentru a executa apelul instrumentului.

Două căi de invocare

Solicitarea pe care o primește serverul dvs. depinde de existența unui endpoint pentru instrument:

	Instrument cu `endpoint`	Instrument fără `endpoint`
Unde este trimisă solicitarea	Direct la `endpoint.url`	URL-ul webhookului legacy al organizației dvs.
Corp	Doar argumentele instrumentului	Plic `telephony.tool` / `web.tool`
Antete	`endpoint.headers` al dvs. + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
Cheie de semnare	Secretul webhookului organizației	Secretul webhookului organizației

Ambele căi sunt blocante — AI-ul așteaptă rezultatul în mijlocul propoziției — cu o expirare după 20 s. Mențineți handlerele rapide. O combinație este acceptată: într-un apel a cărui organizație are un URL de webhook, instrumentele cu un endpoint sunt apelate direct, iar celelalte revin la webhook.

Apeluri directe către endpoint

Când AI-ul invocă un instrument care are un endpoint, ThunderPhone trimite o solicitare către URL-ul dumneavoastră:

Antete de solicitare

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

Antetele personalizate din endpoint.headers sunt întotdeauna incluse literal, plus două antete cu spațiu de nume ThunderPhone:

X-ThunderPhone-Signature — HMAC-SHA256 al octeților exacți ai corpului solicitării, folosind ca cheie secretul webhook al organizației
X-ThunderPhone-Call-ID — ID-ul apelului curent

Content-Type: application/json este setat, cu excepția cazului în care endpoint.headers îl suprascrie — un Content-Type personalizat are prioritate.

Semnătura folosește ca cheie secretul webhook la nivel de organizație din GET /v1/webhook. Dacă organizația dumneavoastră nu a configurat niciodată webhook-ul vechi, nu există niciun secret, iar apelurile de instrumente conțin doar X-ThunderPhone-Call-ID — un gestionar care eșuează automat când lipsește o semnătură le-ar respinge. Configurați fie webhook-ul vechi pentru a obține un secret, fie introduceți propriul secret partajat în endpoint.headers.

Corpul solicitării

Pentru POST / PUT / PATCH, corpul conține doar argumentele instrumentului (fără înveliș), serializate canonic (chei sortate, separatori compacți):

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

Pentru GET / DELETE, argumentele sunt trimise ca parametri de interogare iar corpul este gol — semnătura este apoi calculată peste șirul gol de octeți. Consultați Verificarea semnăturilor webhook.

Răspuns

Returnați un răspuns JSON cu rezultatul instrumentului:

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

Răspunsul este formatat și furnizat AI-ului pentru a continua conversația. Răspunsurile non-JSON sunt încapsulate ca {"data": "<text>"}; expirările și erorile de conexiune sunt raportate AI-ului ca erori, astfel încât agentul să poată să își ceară scuze și să continue, în loc să se blocheze.

Direcționare în modul webhook

Instrumentele fără un endpoint sunt direcționate către URL-ul webhook vechi al organizației dumneavoastră ca o solicitare semnată telephony.tool (apeluri telefonice) sau web.tool (apeluri web). Spre deosebire de notificările de audit livrate către endpoint-uri webhook după execuție, această solicitare este execuția — răspunsul dumneavoastră HTTP este rezultatul instrumentului.

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

web.tool conține origin_domain în loc de from_number / to_number. Răspundeți cu rezultatul instrumentului ca JSON — același contract de răspuns ca pentru apelurile directe către endpoint. Solicitarea este semnată cu secretul webhook al organizației peste corpul brut, la fel ca orice alt webhook.

Endpoint-urile webhook abonate primesc suplimentar o notificare neblocantă telephony.tool / web.tool după executarea fiecărui instrument (indiferent de calea care l-a executat), inclusiv răspunsul instrumentului — utilă pentru piste de audit. Consultați catalogul de evenimente.

Verificarea semnăturii

Apelurile directe de instrumente sunt semnate în același mod ca webhookurile:

HMAC-SHA256 peste octeții exacți ai corpului cererii (JSON-ul canonic — chei sortate, fără spații suplimentare)
Folosind secretul webhook al organizației dumneavoastră
Instrumentele GET / DELETE semnează șirul de octeți gol

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

Rețetele complete — inclusiv cazul corpului gol și avertismentul privind absența unui secret — sunt disponibile în Verificarea semnăturilor webhook.

Exemplu: flux complet de programare

Iată un set de instrumente pentru un sistem complet de programare a întâlnirilor:

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

Bune practici

Scrieți descrieri clare

Câmpul description ajută AI-ul să înțeleagă când să utilizeze instrumentul. Specificați clar ce face și când este potrivit să fie utilizat.

Gestionați erorile în mod corespunzător

Returnați mesaje de eroare pe care AI-ul le poate înțelege: {"error": "No slots available for that date"} în locul erorilor 500 generice.

Păstrați răspunsurile concise

Returnați doar informațiile de care AI-ul are nevoie pentru a continua conversația. Încărcăturile utile mari încetinesc timpii de răspuns.

Utilizați câmpurile obligatorii cu discernământ

Marcați câmpurile ca required numai atunci când este cu adevărat necesar. AI-ul va cere utilizatorului informațiile obligatorii înainte de a apela instrumentul.

Resurse conexe

Conexiuni de aplicații

Instrumente gestionate de platformă pentru HubSpot, Salesforce, Slack, Google Calendar, Google Sheets și Cal.com — nu este necesar niciun endpoint.

Servere MCP

Atașați un server MCP și permiteți agentului să îi apeleze instrumentele.

Conexiuni API

Integrări REST reutilizabile pe care le puteți atașa agenților.

Verificați semnăturile webhook

Un singur ajutor de verificare pentru webhook-uri și apeluri de instrumente.

Webhooks

Function Tools

Instrumente de funcții

Cum funcționează

Schema instrumentului

Definiția funcției

Configurarea endpointului

Două căi de invocare

Apeluri directe către endpoint

Antete de solicitare

Corpul solicitării

Răspuns

Direcționare în modul webhook

Verificarea semnăturii

Exemplu: flux complet de programare

Bune practici

Resurse conexe

Conexiuni de aplicații

Servere MCP

Conexiuni API

Verificați semnăturile webhook

​Cum funcționează

​Schema instrumentului

​Definiția funcției

​Configurarea endpointului

​Două căi de invocare

​Apeluri directe către endpoint

​Antete de solicitare

​Corpul solicitării

​Răspuns

​Direcționare în modul webhook

​Verificarea semnăturii

​Exemplu: flux complet de programare

​Bune practici

​Resurse conexe

Conexiuni de aplicații

Servere MCP

Conexiuni API

Verificați semnăturile webhook

Cum funcționează

Schema instrumentului

Definiția funcției

Configurarea endpointului

Două căi de invocare

Apeluri directe către endpoint

Antete de solicitare

Corpul solicitării

Răspuns

Direcționare în modul webhook

Verificarea semnăturii

Exemplu: flux complet de programare

Bune practici

Resurse conexe