Fonksiyon Araçları

İşlev araçları, yapay zeka ajanlarınızın telefon görüşmeleri sırasında harici API’leri çağırmasına olanak tanır. Bunları müşteri verilerini sorgulamak, uygunluk durumunu kontrol etmek, randevu oluşturmak veya arka ucunuzun desteklediği herhangi bir işlemi gerçekleştirmek için kullanın.

Nasıl Çalışır

Araçları bir şemayla tanımlarsınız (aracın kabul ettiği argümanlar)
Bir endpoint yapılandırması sağlarsınız (ThunderPhone’un API’nizi çağırdığı yer) veya araç çağrılarını kuruluşunuzun webhook’unda almak için bunu boş bırakırsınız
Görüşme sırasında yapay zeka, konuşmaya göre ne zaman araç kullanacağına karar verir
ThunderPhone, araç argümanlarıyla birlikte endpoint’inizi çağırır
API yanıtınız, konuşmanın devam etmesi için yapay zekaya geri iletilir

İşlev araçları, kendi API’nizi kullanma seçeneğidir. ThunderPhone ayrıca endpoint gerektirmeyen, platform tarafından yönetilen araçlar da sunar: uygulama bağlantıları (HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, Cal.com), API bağlantıları ve MCP sunucuları.

Araç Şeması

Her araç bu yapıyı izler:

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

İşlev Tanımı

Alan	Tür	Zorunlu	Açıklama
`name`	dize	Evet	Araç için benzersiz tanımlayıcı
`description`	dize	Evet	Yapay zekaya bu aracı ne zaman kullanacağını açıklar
`parameters`	nesne	Evet	Araç argümanları için JSON Şeması

Endpoint Yapılandırması

Alan	Tür	Zorunlu	Açıklama
`url`	dize	Evet	API endpoint URL’niz
`method`	dize	Hayır	HTTP yöntemi (varsayılan: `POST`)
`headers`	nesne	Hayır	Dahil edilecek özel üst bilgiler

endpoint yapılandırması yapay zeka modeline gönderilmez; yalnızca ThunderPhone tarafından araç çağrısını yürütmek için kullanılır.

İki çağırma yolu

Sunucunuzun aldığı isteğin türü, aracın bir endpoint değeri olup olmamasına bağlıdır:

	`endpoint` olan araç	`endpoint` olmayan araç
İsteğin gittiği yer	Doğrudan `endpoint.url`	Kuruluşunuzun eski webhook URL’si
Gövde	Yalın araç argümanları	`telephony.tool` / `web.tool` zarfı
Üst bilgiler	`endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature`	`Content-Type` + `X-ThunderPhone-Signature`
İmzalama anahtarı	Kuruluş webhook gizli anahtarı	Kuruluş webhook gizli anahtarı

Her iki yol da bloklayıcıdır — yapay zeka cümle ortasında sonucu bekler — ve 20 sn zaman aşımına sahiptir. İşleyicileri hızlı tutun. Karma kullanım mümkündür: kuruluşunda webhook URL’si bulunan bir görüşmede, endpoint içeren araçlar doğrudan çağrılır, diğerleri ise webhook’a geri döner.

Doğrudan endpoint çağrıları

Yapay zeka bir endpoint içeren bir aracı çağırdığında ThunderPhone, URL’nize bir istek gönderir:

İstek Başlıkları

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

endpoint.headers içindeki özel başlıklar her zaman aynen eklenir; bunlara ek olarak ThunderPhone ad alanına ait iki başlık bulunur:

X-ThunderPhone-Signature — kuruluş webhook gizli anahtarınızla anahtarlanmış, tam istek gövdesi baytlarının HMAC-SHA256 değeri
X-ThunderPhone-Call-ID — Geçerli çağrı kimliği

endpoint.headers ile geçersiz kılınmadığı sürece Content-Type: application/json ayarlanır — özel bir Content-Type önceliklidir.

İmza, GET /v1/webhook içindeki kuruluş düzeyindeki webhook gizli anahtarıyla anahtarlanır. Kuruluşunuz eski webhook’u hiç yapılandırmadıysa gizli anahtar yoktur ve araç çağrıları yalnızca X-ThunderPhone-Call-ID içerir — eksik bir imzada kesin olarak başarısız olan bir işleyici bu çağrıları reddeder. Gizli anahtar edinmek için eski webhook’u yapılandırın veya kendi paylaşılan gizli anahtarınızı endpoint.headers içine ekleyin.

İstek Gövdesi

POST / PUT / PATCH için gövde, kanonik olarak serileştirilmiş (sıralanmış anahtarlar, sıkıştırılmış ayırıcılar) yalnızca araç bağımsız değişkenlerini içerir (sarmalayıcı yoktur):

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

GET / DELETE için bağımsız değişkenler sorgu parametreleri olarak gönderilir ve gövde boştur — imza bu durumda boş bayt dizisi üzerinden hesaplanır. Bkz. Webhook imzalarını doğrulama.

Yanıt

Araç sonucunu içeren bir JSON yanıtı döndürün:

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

Yanıt biçimlendirilir ve konuşmaya devam etmesi için yapay zekaya sağlanır. JSON olmayan yanıtlar {"data": "<text>"} olarak sarmalanır; zaman aşımları ve bağlantı hataları yapay zekaya hata olarak bildirilir; böylece ajan duraklamak yerine özür dileyip devam edebilir.

Webhook modu dağıtımı

endpoint içermeyen araçlar, kuruluşunuzun eski webhook URL’sine imzalı bir telephony.tool (telefon çağrıları) veya web.tool (web çağrıları) isteği olarak gönderilir. Yürütmeden sonra webhook endpoint’lerine teslim edilen denetim bildirimlerinden farklı olarak, bu istek yürütmenin kendisidir — HTTP yanıtınız araç sonucudur.

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

web.tool, from_number / to_number yerine origin_domain taşır. Araç sonucuyla JSON olarak yanıt verin — doğrudan endpoint çağrılarıyla aynı yanıt sözleşmesi geçerlidir. İstek, diğer tüm webhook’lar gibi, ham gövde üzerinden kuruluş webhook gizli anahtarıyla imzalanır.

Abone olunan webhook endpoint’leri, her araç yürütmesinden sonra (hangi yol yürüttüyse yürütülsün) aracın yanıtını da içeren, engellemeyen bir telephony.tool / web.tool bildirimi ek olarak alır — denetim izleri için kullanışlıdır. Bkz. olay kataloğu.

İmza Doğrulama

Doğrudan araç çağrıları, webhook’larla aynı şekilde imzalanır:

Tam istek gövdesi baytları üzerinden HMAC-SHA256 (kanonik JSON — sıralanmış anahtarlar, ek boşluk olmadan)
Kuruluşunuzun webhook gizli anahtarıyla anahtarlanır
GET / DELETE araçları boş bayt dizisini imzalar

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

Boş gövde durumu ve gizli anahtar olmamasıyla ilgili uyarı da dahil olmak üzere tüm örnekler Webhook imzalarını doğrulama bölümünde yer alır.

Örnek: Eksiksiz Randevu Akışı

Eksiksiz bir randevu rezervasyon sistemi için araç seti aşağıdadır:

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

En İyi Uygulamalar

Açık açıklamalar yazın

description alanı, yapay zekanın aracı ne zaman kullanacağını anlamasına yardımcı olur. Aracın ne yaptığını ve ne zaman uygun olduğunu açıkça belirtin.

Hataları zarif bir şekilde ele alın

Genel 500 hataları yerine yapay zekanın anlayabileceği hata mesajları döndürün: {"error": "No slots available for that date"}

Yanıtları kısa tutun

Yalnızca yapay zekanın konuşmaya devam etmek için ihtiyaç duyduğu bilgileri döndürün. Büyük yükler yanıt sürelerini yavaşlatır.

Zorunlu alanları dikkatli kullanın

Alanları yalnızca gerçekten gerekli olduğunda required olarak işaretleyin. Yapay zeka, aracı çağırmadan önce kullanıcıdan gerekli bilgileri isteyecektir.

İlgili

Uygulama bağlantıları

HubSpot, Salesforce, Slack, Google Calendar, Google Sheets ve Cal.com için platform tarafından yönetilen araçlar — uç nokta gerekmez.

MCP sunucuları

Bir MCP sunucusu bağlayın ve ajanın araçlarını çağırmasına izin verin.

API bağlantıları

Ajanlara bağlayabileceğiniz yeniden kullanılabilir REST entegrasyonları.

Webhook imzalarını doğrulayın

Webhook’lar ve araç çağrıları için tek bir doğrulama yardımcısı.

Webhooks

Function Tools

Nasıl Çalışır

Araç Şeması

İşlev Tanımı

Endpoint Yapılandırması

İki çağırma yolu

Doğrudan endpoint çağrıları

İstek Başlıkları

İstek Gövdesi

Yanıt

Webhook modu dağıtımı

İmza Doğrulama

Örnek: Eksiksiz Randevu Akışı

En İyi Uygulamalar

İlgili

Uygulama bağlantıları

MCP sunucuları

API bağlantıları

Webhook imzalarını doğrulayın

​Nasıl Çalışır

​Araç Şeması

​İşlev Tanımı

​Endpoint Yapılandırması

​İki çağırma yolu

​Doğrudan endpoint çağrıları

​İstek Başlıkları

​İstek Gövdesi

​Yanıt

​Webhook modu dağıtımı

​İmza Doğrulama

​Örnek: Eksiksiz Randevu Akışı

​En İyi Uygulamalar

​İlgili

Uygulama bağlantıları

MCP sunucuları

API bağlantıları

Webhook imzalarını doğrulayın

Nasıl Çalışır

Araç Şeması

İşlev Tanımı

Endpoint Yapılandırması

İki çağırma yolu

Doğrudan endpoint çağrıları

İstek Başlıkları

İstek Gövdesi

Yanıt

Webhook modu dağıtımı

İmza Doğrulama

Örnek: Eksiksiz Randevu Akışı

En İyi Uygulamalar

İlgili