Funkční nástroje

Funkční nástroje umožňují vašim AI hlasovým agentům během telefonních hovorů volat externí rozhraní API. Použijte je k vyhledávání údajů o zákaznících, kontrole dostupnosti, rezervaci schůzek nebo provedení libovolné akce, kterou váš backend podporuje.

Jak to funguje

Definujete nástroje pomocí schématu (jaké argumenty nástroj přijímá)
Poskytnete konfiguraci endpoint (kam ThunderPhone volá vaše API) — nebo ji vynecháte, aby se volání nástrojů přijímala na webhooku vaší organizace
Během hovoru AI podle konverzace rozhodne, kdy nástroj použít
ThunderPhone zavolá váš endpoint s argumenty nástroje
Odpověď vašeho API se předá zpět AI, aby mohla pokračovat v konverzaci

Funkční nástroje představují cestu, při které používáte vlastní API. ThunderPhone také nabízí nástroje spravované platformou, které endpoint nepotřebují: připojení aplikací (HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, Cal.com), připojení API a servery MCP.

Schéma nástroje

Každý nástroj má tuto strukturu:

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

Definice funkce

Pole	Typ	Povinné	Popis
`name`	řetězec	Ano	Jedinečný identifikátor nástroje
`description`	řetězec	Ano	Vysvětluje AI, kdy tento nástroj použít
`parameters`	objekt	Ano	Schéma JSON pro argumenty nástroje

Konfigurace endpointu

Pole	Typ	Povinné	Popis
`url`	řetězec	Ano	Adresa URL endpointu vašeho API
`method`	řetězec	Ne	Metoda HTTP (výchozí: `POST`)
`headers`	objekt	Ne	Vlastní hlavičky, které se mají zahrnout

Konfigurace endpoint se modelu AI neodesílá — ThunderPhone ji používá pouze k provedení volání nástroje.

Dvě cesty vyvolání

To, jaký požadavek váš server obdrží, závisí na tom, zda nástroj má endpoint:

	Nástroj s `endpoint`	Nástroj bez `endpoint`
Kam požadavek směřuje	Přímo na `endpoint.url`	Na starší adresu URL webhooku vaší organizace
Tělo	Pouhé argumenty nástroje	Obálka `telephony.tool` / `web.tool`
Hlavičky	Vaše `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
Podepisovací klíč	Tajný klíč webhooku organizace	Tajný klíč webhooku organizace

Obě cesty jsou blokující — AI uprostřed věty čeká na výsledek — s časovým limitem 20 s. Udržujte obslužné rutiny rychlé. Kombinace je v pořádku: při hovoru, jehož organizace má adresu URL webhooku, jsou nástroje s endpoint volány přímo a ostatní se vracejí k webhooku.

Přímá volání endpointu

Když AI vyvolá nástroj, který má endpoint, ThunderPhone odešle požadavek na vaši adresu URL:

Hlavičky požadavku

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

Vlastní hlavičky z vašeho endpoint.headers jsou vždy zahrnuty beze změny spolu se dvěma hlavičkami v prostoru názvů ThunderPhone:

X-ThunderPhone-Signature — HMAC-SHA256 přes přesné bajty těla požadavku s klíčem ve vašem tajemství webhooku organizace
X-ThunderPhone-Call-ID — ID aktuálního hovoru

Content-Type: application/json je nastaveno, pokud jej vaše endpoint.headers nepřepíší — vlastní Content-Type má přednost.

Podpis používá jako klíč tajemství webhooku na úrovni organizace z GET /v1/webhook. Pokud vaše organizace nikdy nenakonfigurovala starší webhook, žádné tajemství neexistuje a volání nástrojů obsahují pouze X-ThunderPhone-Call-ID — obslužná funkce, která selže při chybějícím podpisu, by je odmítla. Buď nakonfigurujte starší webhook, abyste získali tajemství, nebo do endpoint.headers vložte vlastní sdílené tajemství.

Tělo požadavku

Pro POST / PUT / PATCH obsahuje tělo pouze argumenty nástroje (bez obálky), serializované kanonicky (seřazené klíče, kompaktní oddělovače):

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

Pro GET / DELETE jsou argumenty odeslány jako parametry dotazu a tělo je prázdné — podpis se pak vypočítá přes prázdný bajtový řetězec. Viz Ověření podpisů webhooků.

Odpověď

Vraťte odpověď JSON s výsledkem nástroje:

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

Odpověď se naformátuje a poskytne AI, aby mohla pokračovat v konverzaci. Odpovědi jiné než JSON jsou zabaleny jako {"data": "<text>"}; časové limity a selhání připojení jsou AI nahlášeny jako chyby, takže se agent může omluvit a pokračovat, místo aby se zasekl.

Odesílání v režimu webhooku

Nástroje bez endpoint jsou odesílány na starší adresu URL webhooku vaší organizace jako podepsaný požadavek telephony.tool (telefonní hovory) nebo web.tool (webová volání). Na rozdíl od notifikací auditu doručovaných na endpointy webhooků po provedení je tento požadavek samotným provedením — vaše odpověď HTTP je výsledkem nástroje.

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

web.tool obsahuje origin_domain místo from_number / to_number. Odpovězte výsledkem nástroje ve formátu JSON — se stejným kontraktem odpovědi jako u přímých volání endpointu. Požadavek je podepsán tajemstvím webhooku organizace přes nezpracované tělo, stejně jako každý jiný webhook.

Odebírané endpointy webhooků navíc obdrží neblokující notifikaci telephony.tool / web.tool po provedení každého nástroje (bez ohledu na použitou cestu), včetně odpovědi nástroje — což je užitečné pro auditní záznamy. Viz katalog událostí.

Ověření podpisu

Přímá volání nástrojů se podepisují stejným způsobem jako webhooky:

HMAC-SHA256 přes přesné bajty těla požadavku (kanonický JSON — seřazené klíče, bez nadbytečných mezer)
S vaším tajným klíčem webhooku organizace
Nástroje GET / DELETE podepisují prázdný bajtový řetězec

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

Úplné postupy — včetně případu s prázdným tělem a upozornění na chybějící tajný klíč — najdete v části Ověření podpisů webhooků.

Příklad: Kompletní proces rezervace

Zde je sada nástrojů pro kompletní systém rezervace termínů:

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

Osvědčené postupy

Pište jasné popisy

Pole description pomáhá AI pochopit, kdy nástroj použít. Konkrétně popište, co nástroj dělá a kdy je vhodné ho použít.

Zpracovávejte chyby vhodně

Vracejte chybové zprávy, kterým AI rozumí: {"error": "No slots available for that date"} namísto obecných chyb 500.

Udržujte odpovědi stručné

Vracejte pouze to, co AI potřebuje k pokračování v konverzaci. Velké datové objemy zpomalují dobu odezvy.

Pole povinná k vyplnění používejte uvážlivě

Označujte pole jako required pouze tehdy, když je to skutečně nutné. AI před voláním nástroje požádá uživatele o požadované informace.

Související

Připojení aplikací

Nástroje spravované platformou pro HubSpot, Salesforce, Slack, Kalendář Google, Tabulky Google a Cal.com — není vyžadován žádný endpoint.

Servery MCP

Připojte server MCP a umožněte agentovi volat jeho nástroje.

Připojení API

Znovupoužitelné integrace REST, které můžete připojit k agentům.

Ověřování podpisů webhooků

Jeden pomocný nástroj pro ověřování webhooků a volání nástrojů.

Webhooks

Function Tools

Jak to funguje

Schéma nástroje

Definice funkce

Konfigurace endpointu

Dvě cesty vyvolání

Přímá volání endpointu

Hlavičky požadavku

Tělo požadavku

Odpověď

Odesílání v režimu webhooku

Ověření podpisu

Příklad: Kompletní proces rezervace

Osvědčené postupy

Související

Připojení aplikací

Servery MCP

Připojení API

Ověřování podpisů webhooků

​Jak to funguje

​Schéma nástroje

​Definice funkce

​Konfigurace endpointu

​Dvě cesty vyvolání

​Přímá volání endpointu

​Hlavičky požadavku

​Tělo požadavku

​Odpověď

​Odesílání v režimu webhooku

​Ověření podpisu

​Příklad: Kompletní proces rezervace

​Osvědčené postupy

​Související

Připojení aplikací

Servery MCP

Připojení API

Ověřování podpisů webhooků

Jak to funguje

Schéma nástroje

Definice funkce

Konfigurace endpointu

Dvě cesty vyvolání

Přímá volání endpointu

Hlavičky požadavku

Tělo požadavku

Odpověď

Odesílání v režimu webhooku

Ověření podpisu

Příklad: Kompletní proces rezervace

Osvědčené postupy

Související