Funksjonsverktøy

Funksjonsverktøy lar AI-agentene dine kalle eksterne API-er under telefonsamtaler. Bruk dem til å slå opp kundedata, sjekke tilgjengelighet, bestille avtaler eller utføre enhver handling backend-en din støtter.

Slik fungerer det

Du definerer verktøy med et skjema (hvilke argumenter verktøyet godtar)
Du oppgir en endpoint-konfigurasjon (der ThunderPhone kaller API-et ditt) — eller utelater den for å motta verktøykall på organisasjonens webhook
Under en samtale avgjør AI-en når den skal bruke et verktøy basert på samtalen
ThunderPhone kaller endepunktet ditt med verktøyargumentene
API-svaret ditt mates tilbake til AI-en for å fortsette samtalen

Funksjonsverktøy er alternativet der du bruker ditt eget API. ThunderPhone leverer også plattformadministrerte verktøy som ikke trenger noe endepunkt: appkoblinger (HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, Cal.com), API-koblinger og MCP-servere.

Verktøyskjema

Hvert verktøy følger denne strukturen:

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

Funksjonsdefinisjon

Felt	Type	Påkrevd	Beskrivelse
`name`	string	Ja	Unik identifikator for verktøyet
`description`	string	Ja	Forklarer AI-en når dette verktøyet skal brukes
`parameters`	object	Ja	JSON Schema for verktøyargumenter

Endepunktkonfigurasjon

Felt	Type	Påkrevd	Beskrivelse
`url`	string	Ja	URL-en til API-endepunktet ditt
`method`	string	Nei	HTTP-metode (standard: `POST`)
`headers`	object	Nei	Egendefinerte headere som skal inkluderes

endpoint-konfigurasjonen sendes ikke til AI-modellen—den brukes bare av ThunderPhone til å utføre verktøykallet.

To kallingsveier

Hvilken forespørsel serveren din mottar, avhenger av om verktøyet har et endpoint:

	Verktøy med `endpoint`	Verktøy uten `endpoint`
Hvor forespørselen sendes	Direkte til `endpoint.url`	Organisasjonens eldre webhook-URL
Body	Kun verktøyargumenter	`telephony.tool` / `web.tool`-omslag
Headere	Dine `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
Signeringsnøkkel	Organisasjonens webhook-hemmelighet	Organisasjonens webhook-hemmelighet

Begge veier er blokkerende — AI-en venter midt i en setning på resultatet — med en tidsavbruddsgrense på 20 s. Hold handlerne raske. En blanding fungerer fint: i en samtale der organisasjonen har en webhook-URL, blir verktøy med et endpoint kalt direkte, mens resten faller tilbake til webhooken.

Direkte endepunktkall

Når AI-en kaller et verktøy som har et endpoint, sender ThunderPhone en forespørsel til URL-en din:

Forespørselsheadere

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

Egendefinerte headere fra endpoint.headers inkluderes alltid ordrett, i tillegg til to ThunderPhone-navngitte headere:

X-ThunderPhone-Signature — HMAC-SHA256 av de nøyaktige bytene i forespørselsbrødteksten, med organisasjonens webhook-hemmelighet som nøkkel
X-ThunderPhone-Call-ID — ID-en til den gjeldende samtalen

Content-Type: application/json angis med mindre endpoint.headers overstyrer den — en egendefinert Content-Type har forrang.

Signaturen bruker webhook-hemmeligheten på organisasjonsnivå fra GET /v1/webhook som nøkkel. Hvis organisasjonen din aldri har konfigurert den eldre webhooken, finnes det ingen hemmelighet, og verktøykall inneholder kun X-ThunderPhone-Call-ID — en behandler som feiler ved manglende signatur, vil avvise dem. Konfigurer enten den eldre webhooken for å få en hemmelighet, eller legg din egen delte hemmelighet i endpoint.headers.

Forespørselsbrødtekst

For POST / PUT / PATCH inneholder brødteksten kun verktøyargumentene (ingen innpakning), serialisert kanonisk (sorterte nøkler, kompakte skilletegn):

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

For GET / DELETE sendes argumentene som spørringsparametere, og brødteksten er tom — signaturen beregnes da over den tomme bytestrengen. Se Verifiser webhook-signaturer.

Svar

Returner et JSON-svar med verktøyresultatet:

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

Svaret formateres og gis til AI-en slik at den kan fortsette samtalen. Ikke-JSON-svar pakkes inn som {"data": "<text>"}; tidsavbrudd og tilkoblingsfeil rapporteres til AI-en som feil, slik at stemmeagenten kan beklage og gå videre i stedet for å stoppe opp.

Utsending i webhook-modus

Verktøy uten et endpoint sendes til organisasjonens eldre webhook-URL som en signert telephony.tool-forespørsel (telefonsamtaler) eller web.tool-forespørsel (nettsamtaler). I motsetning til revisjonsvarslingene som leveres til webhook-endepunkter etter kjøring, er denne forespørselen selve kjøringen — HTTP-svaret ditt er verktøyresultatet.

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

web.tool inneholder origin_domain i stedet for from_number / to_number. Svar med verktøyresultatet som JSON — samme svarkontrakt som for direkte endepunktkall. Forespørselen signeres med organisasjonens webhook-hemmelighet over den rå brødteksten, som alle andre webhooks.

Abonnerte webhook-endepunkter mottar i tillegg et ikke-blokkerende telephony.tool- / web.tool-varsel etter at hvert verktøy kjøres (uansett hvilken bane som kjørte det), inkludert verktøyets svar — nyttig for revisjonsspor. Se hendelseskatalogen.

Signaturverifisering

Direkte verktøykall signeres på samme måte som webhooks:

HMAC-SHA256 over de nøyaktige byteverdiene i forespørselskroppen (den kanoniske JSON-en — sorterte nøkler, ingen ekstra mellomrom)
Med organisasjonens webhook-hemmelighet som nøkkel
GET- / DELETE-verktøy signerer den tomme byte-strengen

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

Fullstendige eksempler — inkludert tilfellet med tom forespørselskropp og forbeholdet om manglende hemmelighet — finner du i Verifiser webhook-signaturer.

Eksempel: Komplett bestillingsflyt

Her er et sett med verktøy for et komplett system for timebestilling:

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

Beste praksis

Skriv tydelige beskrivelser

Feltet description hjelper AI-en med å forstå når verktøyet skal brukes. Vær spesifikk om hva det gjør, og når det er passende å bruke det.

Håndter feil på en god måte

Returner feilmeldinger som AI-en kan forstå: {"error": "No slots available for that date"} i stedet for generiske 500-feil.

Hold svarene konsise

Returner bare det AI-en trenger for å fortsette samtalen. Store nyttelaster gir tregere responstider.

Bruk obligatoriske felt med omhu

Merk felt som required bare når det virkelig er nødvendig. AI-en vil be brukeren om obligatorisk informasjon før den kaller verktøyet.

Relatert

Appkoblinger

Plattformadministrerte verktøy for HubSpot, Salesforce, Slack, Google Kalender, Google Sheets og Cal.com — ingen endepunkt kreves.

MCP-servere

Koble til en MCP-server, og la agenten kalle verktøyene dens.

API-koblinger

Gjenbrukbare REST-integrasjoner som du kan koble til agenter.

Bekreft webhook-signaturer

Én bekreftelseshjelper for webhooks og verktøykall.

Webhooks

Function Tools

Slik fungerer det

Verktøyskjema

Funksjonsdefinisjon

Endepunktkonfigurasjon

To kallingsveier

Direkte endepunktkall

Forespørselsheadere

Forespørselsbrødtekst

Svar

Utsending i webhook-modus

Signaturverifisering

Eksempel: Komplett bestillingsflyt

Beste praksis

Relatert

Appkoblinger

MCP-servere

API-koblinger

Bekreft webhook-signaturer

​Slik fungerer det

​Verktøyskjema

​Funksjonsdefinisjon

​Endepunktkonfigurasjon

​To kallingsveier

​Direkte endepunktkall

​Forespørselsheadere

​Forespørselsbrødtekst

​Svar

​Utsending i webhook-modus

​Signaturverifisering

​Eksempel: Komplett bestillingsflyt

​Beste praksis

​Relatert

Appkoblinger

MCP-servere

API-koblinger

Bekreft webhook-signaturer

Slik fungerer det

Verktøyskjema

Funksjonsdefinisjon

Endepunktkonfigurasjon

To kallingsveier

Direkte endepunktkall

Forespørselsheadere

Forespørselsbrødtekst

Svar

Utsending i webhook-modus

Signaturverifisering

Eksempel: Komplett bestillingsflyt

Beste praksis

Relatert