Özel araçlar

Sisteminizin API’si mi var? Bağlarız. Yok mu? Küçük bir webhook yazın — onu da bağlarız. Özel araçlar asistanın kendi sistemlerinizi çağırmasını sağlar; ör. “bir SKU’nun anlık stoğu ve bir sonraki teslim tarihi”.

Ayarlar → Entegrasyonlar → Özel araçlar’dan yönetilir.

İki tür

Tür	Nasıl çalışır	Ne zaman uygun
Webhook	HTTPS uç noktanıza imzalı bir zarf POST ederiz, siz cevaplarsınız.	Küçük bir uç nokta yazabiliyorsanız.
HTTP	Sitenizin mevcut arama ya da API’sini kendi biçiminde çağırırız. İmza yok.	API zaten varsa.

Araç tanımlama

1. Bir ad ve net bir açıklama verin — asistan aracı ne zaman çağıracağına açıklamadan karar verir.
2. Girdilerini JSON Schema olarak tanımlayın (parametreler).
3. Webhook için HTTPS uç noktanızı, HTTP için istek şablonunu girin.
4. Bir zaman aşımı belirleyin (varsayılan 10 saniye).
5. İsterseniz Çalıştırmadan önce bir insana sor’u açın — çağrı Konuşmalar’da onay kartı olarak bekler.
6. Test çağrısı yapın. Uç noktanıza bir gerçek çağrı başarılı olmadan araç yayına çıkamaz — ilk çağıran asistan olmamalı.

Webhook isteği

POST https://your-endpoint.example.com/tools
Content-Type: application/json
X-Fluxy-Signature: t=1760000000,v1=5f2b…

{
  "tool_call_id": "9c1e…",
  "tool": "stock_level",
  "arguments": { "sku": "SH-42-WHT" },
  "conversation_id": "c0ffee…"
}

JSON ile cevap verin; asistan cevabınızı okur.

İmzayı doğrulayın

Başlık, imzalandığı zaman damgasını taşır. Araç sırrınızla <t>.<ham gövde> üzerinde HMAC-SHA256’yı yeniden hesaplayın ve beş dakikadan eski her şeyi reddedin.

import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('=')));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

Yeniden denemeler

Her çağrı sabit bir tool_call_id taşır; yeniden deneme aynı id’yi kullanır, tekrarlanan id’yi aynı çağrı sayın (idempotent işleme).

Durum	Biz ne yaparız	Siz ne yaparsınız
Zaman aşımı (varsayılan 10 sn)	Aynı tool_call_id ile iki kez yeniden deneriz	Daha hızlı cevap verin
Uç noktanızdan 5xx	Aynı tool_call_id ile artan aralıklarla yeniden deneriz	İşlemi tekrar güvenli hâle getirin
Uç noktanızdan 4xx	Yeniden denemeyiz	Asistana çağrının başarısız olduğu söylenir, o da müşteriye açıkça söyler
Webhook 1 MB’tan büyük cevap verir	Yeniden denemeyiz	Daha küçük bir cevap döndürün
Adres herkese açık bir https:// adresi değil	Yeniden denemeyiz — çağrı hiç yapılmaz	Herkese açık bir HTTPS uç noktası kullanın

Bir çağrı tamamlanamadığında asistan yapılmış gibi davranmaz: müşteriye şu an yapılamadığını söyler ve bir kişinin dönmesini önerir.

Sınırlar

• Her adres herkese açık bir https:// adresi olmalı. Özel ya da iç ağdaki adresler reddedilir.
• Webhook: yönlendirmeler izlenmez; cevabınızın en çok 1 MB’ını okuruz.
• HTTP: en çok 5 yönlendirme izlenir ve her adım da herkese açık bir HTTPS adresi olmalı; cevabın en çok 5 MB’ını okuruz.