Fonksiyonlar: asistana araç verin

Fonksiyonlar, asistanın konuşmanın ötesinde bir şey yapmasını sağlar: randevu açmak, sipariş durumu sorgulamak, insana aktarmak. Aracı siz tanımlarsınız, çağırma kararını model verir, ağ işini platform yürütür.

Zihinsel model

Bir fonksiyon aslında bir HTTP ucu ve onun parametrelerini anlatan bir JSON Schema’dan ibarettir. Model şemayı ve kullanıcının niyetini okur, çağırmanın anlamlı olduğu anı seçer.

Arayan : "4521 numaralı siparişim ne durumda?"
Model  : get_order_status({"order_id": "4521"}) çağırmaya karar verir
Platform: https://sizin-api.com/siparis-durumu adresine POST eder
Sizin API: {"status": "kargoda", "eta": "2026-08-19"} döner
Platform: sonucu modele geri verir
Model  : "Siparişiniz kargoda, 19 Ağustos’ta teslim edilmesi bekleniyor."

HTTP isteği havada beklerken asistan bir dolgu cümlesi söyler ("hemen kontrol ediyorum") — böylece sessizlik hat kopmuş gibi hissedilmez.

Fonksiyon tanımlamak

Panelde Asistanlar → Düzenle → Fonksiyonlar bölümünden ekleyebilirsiniz. API tarafında fonksiyon listesi asistanın response_engine bloğu içinde tutulur; PATCH ile güncellenir.

curl -X PATCH https://api.call2me.app/v1/agents/agent_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "response_engine": {
      "functions": [{
        "name": "get_order_status",
        "description": "Sipariş numarasıyla kargo durumunu ve tahmini teslim tarihini sorgular. Müşteri sipariş numarası verdiğinde kullan.",
        "url": "https://sizin-api.com/siparis-durumu",
        "method": "POST",
        "headers": { "X-Api-Key": "..." },
        "parameters": {
          "type": "object",
          "properties": {
            "order_id": { "type": "string", "description": "Sipariş numarası, yalnızca rakam" }
          },
          "required": ["order_id"]
        }
      }]
    }
  }'

Alanlar ne işe yarar

Ucunuza ne gelir

POST https://sizin-api.com/siparis-durumu
Content-Type: application/json
X-Call2Me-Call-Id: call_xyz789
X-Call2Me-Agent-Id: agent_abc123

{ "order_id": "4521" }

Bir JSON nesnesi dönün. Döndürdüğünüz her alan modele sunulur; model bunu arayan için özetler ve konuşmaya devam eder.

{
  "status": "kargoda",
  "carrier": "Yurtiçi Kargo",
  "tracking_number": "1234567890",
  "eta": "2026-08-19"
}

Hazır fonksiyonlar

Bazı fonksiyonlar platform tarafından sağlanır; bunlar için kendi ucunuzu yazmanız gerekmez.

Bunlar asistanın builtin_functions listesine ad yazılarak açılır; url alanı gerekmez. Aktarmada operatör tarafını platform yönetir — SIP tarafıyla uğraşmanız gerekmez.

curl -X PATCH https://api.call2me.app/v1/agents/agent_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "builtin_functions": ["end_call", "transfer_call", "schedule_callback"],
    "transfer_targets": [{"name": "Muhasebe", "number": "+908502345678"}]
  }'

Gecikme bütçesi

Telefon konuşması affetmez. İnsan kulağı bir saniyelik sessizliği bile arıza gibi okur. Hedefiniz şu aralıklar olmalı:

Gelen aramada arayanın kim olduğunu numarasından bilebiliyorsanız, verisini konuşmanın ortasında sorgulamak yerine arama başlamadan çekip dinamik değişken olarak geçirin. En hızlı fonksiyon, hiç çağrılmayan fonksiyondur.

Çalışma zamanı sınırları

• HTTP zaman aşımı 8 saniyedir; aşılırsa modele zaman aşımı bilgisi döner ve konuşma devam eder.
• Yanıt metni 1500 karaktere kırpılır — model bağlamını şişirmemek için. Uzun listeler yerine özet dönün.
• Tek görüşmede en fazla 10 fonksiyon çağrısı yapılır. Bu sınıra dayanan bir akış neredeyse her zaman bir döngü hatasıdır.
• Yönlendirmeler (redirect) izlenir; GET’te parametreler sorgu dizesine, diğer metotlarda JSON gövdeye konur.

Hata yönetimi

Ucunuz zaman aşımına düşerse, erişilemezse veya 4xx/5xx dönerse platform sonucu modele metin olarak iletir — konuşma kesilmez.

Error: webhook timed out after 8.0s — please try a different option
Error: webhook unreachable
Webhook returned status 503: {"detail":"upstream down"}

Asistanın talimatında bu durumda ne yapacağı yazılı olmalı. Örnek bir satır: "Bir araç çağrısı başarısız olursa kısaca özür dile ve arayanı bir yetkiliye aktarmayı teklif et." Bu tek cümle, tek bir arka uç hıçkırığının tüm görüşmeyi bozmasını engeller.

Güvenlik: iç ağ korumalı

Test etmek

Fonksiyon ucunuzu gerçek aramaya girmeden deneyebilirsiniz. Test ucu isteği sizin adresinize gönderir ve dönen yanıtı olduğu gibi gösterir — şema ve kimlik doğrulama hatalarını burada yakalarsınız.

curl -X POST https://api.call2me.app/v1/agents/agent_abc123/test-function \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://sizin-api.com/siparis-durumu",
    "method": "POST",
    "headers": {"X-Api-Key": "..."},
    "sample_args": {"order_id": "4521"}
  }'

{ "ok": true, "status_code": 200, "elapsed_ms": 312, "body_preview": "{\"status\":\"kargoda\"...}" }

Bu test, canlı aramanın kullandığı aynı güvenlik ve yürütme yolundan geçer: yalnızca HTTPS, SSRF koruması, 8 saniye zaman aşımı, kırpılmış yanıt. Test 200 dönüyorsa çalışma zamanı çağrısı da çalışacaktır.