Sohbet

Bu sayfa oyuncuların birbirine yazdığı kanal sohbetini (global, dünya, klan, parti ve birebir) anlatır. Oyuncu oturumuyla mesaj göndermek, geçmişi okumak ve canlı mesaj almak istiyorsanız okuyun.

Ne işe yarar

Sohbet modülü (chat) kanal tabanlı metin sohbeti sağlar. Mesajlar kalıcı arşive yazılır; canlı dağıtım ayrıca WebSocket ile yapılır. Aynı mesaj hem REST hem WebSocket üzerinden gönderilebilir ve ikisi de aynı kuralları (susturma, hız sınırı, küfür süzgeci, tekrar koruması) uygular.

Oyuncunun kendi oturumuyla çalışır. API anahtarıyla sohbet uçları çağrılamaz.

Modül kapalıysa uçlar 404 ve {"code":"module_disabled","module":"chat"} döner; sohbet soketi ise önce bir error çerçevesi (code: "module_disabled") gönderip kapanır. Modülü Oyun ayarları › Modüller sayfasından açın.

Panelde nerede

Not

Panelin “Şehir sohbeti” ekranı sahne eklentisinin sohbetini yönetir; bu sayfadaki kanal sohbeti için panelde mesaj okuma, silme ya da susturma ekranı henüz yoktur.

Veri modeli (düz dille)

• Kanal (channel): kind ile ayrılır:

  kind	reference_id	Kim girebilir
  global	yok	Ortamdaki herkes
  world	gerekli (dünya/harita UUID’si)	Referansı bilen oyuncular
  clan	gerekli (klan UUID’si)	Klanın üyeleri
  party	gerekli (parti UUID’si)	Partinin üyeleri
  direct	yok; direct_player_id gerekli	Yalnız iki oyuncu

  Aynı türde ve aynı referansta kanal bir kez kurulur; yeniden istemek var olan kanalı döndürür. direct kanalda diğer oyuncu kendiniz olamaz.

• Mesaj: id, channel_id, sender_player_id, client_message_id, body, sent_at_ms.

• client_message_id: İstemcinin ürettiği tekrar anahtarı (boş olamaz, en çok 200 karakter). Aynı kanalda aynı değerle ikinci gönderim yeni mesaj üretmez; var olan mesajı duplicate: true ile geri döner.

• Susturma: Oyuncunun all, global, world, clan, party ya da direct kapsamında susturulması. Susturulmuş oyuncunun gönderimi 403 döner.

Oyunun yaptığı çağrılar

Bütün sohbet uçları oyuncu oturumuyla çağrılır: oturum çerezi ya da opak oturum belirteci (Authorization: Bearer <oturum belirteci>) ve ortam başlığı:

x-crx-env: <ortam uuid>

Bu uçlarda x-csrf-token çift gönderimi ve Origin denetimi uygulanmaz; oturum çerezi ya da oturum belirteci yeterlidir (mağaza satın alma ucundan farklı olarak). Oturum kuralları: Oturumlar ve CSRF.

Not

TypeScript ve Unity SDK’larında sohbet için hazır istemci yoktur; uçlar ham REST ve WebSocket ile çağrılır. Bkz. TypeScript SDK.

Kanal kurmak

POST /v1/chat/channels
x-crx-env: <ortam uuid>
Content-Type: application/json

{ "kind": "clan", "reference_id": "0192f0aa-…" }

{ "channel": { "id": "0192f2bb-…", "environment_id": "…", "kind": "clan", "reference_id": "0192f0aa-…", "participant_a": null, "participant_b": null, "created_at_ms": 1790000000000 } }

Klan ya da parti üyesi olmayan oyuncunun o kanalı kurması ya da okuması reddedilir.

Mesaj göndermek

POST /v1/chat/channels/0192f2bb-…/messages
x-crx-env: <ortam uuid>
Content-Type: application/json

{ "client_message_id": "c-0001", "body": "Merhaba!" }

{ "message": { "id": "…", "channel_id": "0192f2bb-…", "sender_player_id": "…", "client_message_id": "c-0001", "body": "Merhaba!", "sent_at_ms": 1790000000123 }, "duplicate": false }

Kurallar, sırasıyla:

1. client_message_id boş ya da 200 karakterden uzunsa 400.
2. Gövde 1–2000 Unicode karakter olmalı ve en az bir boşluk dışı karakter içermelidir; aksi 400.
3. Oyuncu o kanal için susturulmuşsa 403.
4. Hız sınırı: oyuncu başına 10 saniyede en çok 20 mesaj; aşımı 429 döner.
5. Küfür süzgeci: mesajda yasaklı bir sözcük (boşlukla ayrılmış tam sözcük, büyük/küçük harf duyarsız) varsa 422 döner.
6. Mesaj arşive yazılır, ardından canlı abonelere dağıtılır. Dağıtım başarısız olsa bile arşivlenmiş mesaj silinmez.

Arşivi okumak

GET /v1/chat/channels/{channel_id}/messages?before_ms=1790000000000&limit=50 yanıtı { "messages": [ … ] } döner. before_ms, bu Unix milisaniyesinden eski mesajları ister; bir sonraki sayfa için en eski mesajın sent_at_ms değerini verin.

Canlı sohbet (WebSocket)

GET /v1/chat/ws adresine bağlanırken x-crx-env ve oturum kimliği (çerez ya da Authorization: Bearer) başlık olarak gönderilir. Kimlik doğrulanmadan yükseltme yapılmaz (401); modül kapalıysa 404.

Uyarı

Tarayıcıdaki WebSocket API’si özel başlık (x-crx-env) gönderemez; bu nedenle chat soketine tarayıcıdan doğrudan bağlanılamaz. Tarayıcı oyunları REST ile yoklayabilir; native istemciler (örneğin Unity masaüstü/mobil) başlık ekleyerek bağlanabilir. Başlık yerine sorgu parametresi ya da alt protokol henüz desteklenmez.

İstemci çerçeveleri (JSON; type alanı küçük camelCase, diğer alanlar snake_case):

Sunucu çerçeveleri:

Bir soket aynı anda tek kanala abonedir. Tanınmayan alan içeren çerçeve invalid_frame alır. Modül sonradan kapanırsa açık soket de kapatılır. Genel gerçek zamanlı yüzey için bkz. Gerçek zamanlı: genel bakış.

Sürümleme ve tekrar güvenliği

• Mesaj gönderiminde Idempotency-Key başlığı yoktur; tekrar güvenliği client_message_id ile sağlanır. Ağ hatasında aynı değerle yeniden gönderin: mesaj bir kez görünür (duplicate: true).
• If-Match kullanılmaz.

Olaylar

Sohbet olayı webhook olarak gönderilmez; webhook olay türleri arasında sohbet yoktur. Canlı akış için WebSocket kullanın.

Sınırlar

• Mesaj gövdesi 1–2000 karakter; client_message_id en çok 200 karakter.
• Gönderim hızı: oyuncu başına 10 saniyede 20 mesaj.
• Arşiv sayfası 1–100 mesaj.
• Bir WebSocket aynı anda tek kanala abone olabilir.

Sık görülen hatalar

Çalışan örnek

Oturum çerezi (cookies.txt) ile REST üzerinden bir kanala yazıp geçmişi okuma:

curl -X POST "$API/v1/chat/channels/$CHANNEL/messages" \
  -H "x-crx-env: $ENV" \
  -H "Content-Type: application/json" -b cookies.txt \
  -d '{"client_message_id":"c-0001","body":"Merhaba!"}'

curl "$API/v1/chat/channels/$CHANNEL/messages?limit=20" \
  -H "x-crx-env: $ENV" -b cookies.txt

İlgili sayfalar

• Klanlar ve partiler · Gerçek zamanlı: genel bakış
• Oturumlar ve CSRF · Hatalar