Geçici kullanıcı token’ları (mobil/sunucusuz)

Platformu bir mobil uygulamaya veya tam kontrol edemediğiniz herhangi bir istemciye gömüyorsanız sk_ anahtarınızı oraya koymamalısınız — o anahtar hesabınızın tamamına erişir. Doğru desen şu: arka ucunuz her son kullanıcı için kısa ömürlü, kapsamı sınırlı bir token (eut_ önekli) üretir ve istemciye onu verir.

Nasıl çalışır

1. 1Arka ucunuz sk_ anahtarıyla POST /v1/end-users/{external_id}/tokens çağırır.
2. 2Platform eut_ önekli, imzalı bir JWT döner — durumsuzdur, sizin tarafta saklamanız gerekmez.
3. 3Arka ucunuz token’ı mobil istemciye iletir.
4. 4İstemci Authorization: Bearer eut_... ile sohbet/ses uçlarını doğrudan çağırır.
5. 5Kullanım, token’ı üreten hesabın cüzdanından düşer.

external_id sizin son kullanıcı kimliğinizdir (örnek: user_42). Token’ın içine gömülür ve istemci tarafından değiştirilemez — yani bir kullanıcı başka bir kullanıcının kimliğine bürünemez.

Token üretmek

curl -X POST https://api.call2me.app/v1/end-users/user_42/tokens \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "expires_in": 3600,
    "scopes": ["chat", "voice"],
    "agent_ids": ["agent_abc"]
  }'

{
  "token": "eut_eyJhbGciOi...",
  "expires_in": 3600,
  "scopes": ["chat", "voice"],
  "external_id": "user_42"
}

İstek alanları

eut_ token neyi çağırabilir

Sabit bir izin listesiyle sınırlıdır. Listede olmayan her şey 403 döner.

Bir eut_ token yeni token üretemez, cüzdanı okuyamaz, asistan yönetemez ve hiçbir yapılandırma ucuna dokunamaz — hepsi 403 döner.

Oturumları kendi kullanıcılarınıza bağlamak

Sohbet ve ses oturumları isteğe bağlı external_user_id alanı ve serbest biçimli bir metadata nesnesi kabul eder.

curl -X POST https://api.call2me.app/v1/chats \
  -H "Authorization: Bearer eut_..." \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "agent_abc", "metadata": {"kaynak": "mobil"}}'

• eut_ token ile external_user_id token’dan otomatik alınır — istemci başka bir kullanıcının kimliğini gönderemez, bu yüzden gövdede göndermenize gerek yok (göndermemelisiniz).
• sk_ anahtarıyla (sunucu tarafında) external_user_id’yi açıkça geçin; sonra GET /v1/chats?external_user_id=user_42 ile geri sorgulayın.
• eut_ token’ın GET /v1/chats çağrısı her zaman kendi external_user_id değeriyle sınırlıdır — bir kullanıcı asla başkasının oturumlarını listeleyemez.

Asistan listesi (açık kartlar)

Uygulamanızda asistan seçici yapacaksanız önce her asistana açık kart bilgisi ekleyin (sk_ anahtarıyla):

curl -X PATCH https://api.call2me.app/v1/agents/agent_abc \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"public_metadata": {"emoji": "☎️", "title": {"tr": "Destek", "en": "Support"}, "order": 1, "visible": true}}'

Ardından mobil istemci (eut_ token ve agents:read kapsamıyla) listeyi çeker ve yalnızca kırpılmış açık kartları alır:

[
  { "agent_id": "agent_abc", "name": "Destek Asistanı", "language": "tr-TR",
    "voice_id": "v_alice",
    "public_metadata": { "emoji": "☎️", "title": {"tr": "Destek"}, "order": 1, "visible": true } }
]

Sistem talimatı, bilgi tabanı, webhook ve maliyet/yapılandırma alanları geçici token’a hiçbir zaman dönmez. public_metadata.visible değeri false olan asistanlar listelenmez, sonuçlar public_metadata.order alanına göre sıralanır.

Sesli oturumu geri okumak

Sesli oturum bittikten sonra oda adıyla detayını ve dökümünü çekebilirsiniz.

curl https://api.call2me.app/v1/voice/sessions/agent_x_ab12 \
  -H "Authorization: Bearer eut_..."

{
  "room_name": "agent_x_ab12",
  "status": "ended",
  "duration_sec": 143.2,
  "cost_usd": 0.24,
  "transcript": [
    { "role": "user", "text": "Faturamı öğrenmek istiyorum" },
    { "role": "agent", "text": "Hemen bakıyorum, bir saniye." }
  ],
  "external_user_id": "user_42"
}

Faturalama kime çıkar

Token’ı üreten hesap öder. eut_ token ile yapılan tüm sohbet, ses ve ses işleme kullanımı, sk_ anahtarının sahibi olan hesabın cüzdanından düşer — siz kendiniz aramış gibi. Son kullanıcınızın platformda bir cüzdanı yoktur.

Güvenlik notları

• Token’lar durumsuz imzalı JWT’dir; sunucu tarafında iptal mekanizması yoktur. expires_in değerini kısa tutun (varsayılan 1 saat) ve gerektiğinde yenisini üretin.
• external_id token’a bağlıdır; istemci başka bir kullanıcı gibi davranamaz.
• Sızan bir eut_ token, süresi dolana kadar yalnızca cüzdanınızdan sohbet/ses harcayabilir — tam hesap erişimine yükselemez.
• Kapsamı daraltın: uygulamanız yalnızca sohbet yapıyorsa voice kapsamını vermeyin.
• agent_ids ile sınırlayın: token yalnızca uygulamanızın kullandığı asistanlara erişsin.