Kanallar: Web & Mobil.

Kanal Türleri ve Oluşturma

Bir Cxperium hesabı birden fazla kanala sahip olabilir. Kanalların tümü aynı bota, aynı kişi listesine ve aynı gelen kutusuna bağlanır; temsilciler hangi kanaldan gelirse gelsin sohbeti tek ekranda görür.

Yeni bir kanal oluşturmak için:

1. Kanallar sayfasını açın

   Sol menüden Kanallar'a girin ve sağ üstteki Ekle düğmesine basın.

2. Türü seçin

   Web sitenizdeki sohbet için Web, mobil uygulama ya da kendi istemciniz için Mobil kartını seçin.

3. Ad ve bot adresi verin

   Kanala bir ad yazın ve bu kanala gelen mesajların iletileceği bot adresini girin. Varsayılan dil isteğe bağlıdır. Kanal Ekle'ye basın.

4. Bağlantı bilgilerini alın

   Son adımda kanal anahtarı, secret ve (Web türünde) hazır kurulum kodu gösterilir. Bu bilgilere daha sonra Kanallar listesindeki Detay penceresinden de ulaşırsınız.

Web Kanalı: Widget Kurulumu

Web kanalı, sitenizin köşesine bir sohbet balonu ekler. Ziyaretçi balona tıklar, isterseniz adını yazar ve botla ya da temsilcinizle konuşmaya başlar. Kurulum tek bir kod parçasından ibarettir.

<!-- Cxperium chat -->
<script>
  window.cxperiumSettings = {
    channelKey: "ch_c727ccd3ef5112a1",
    secret: "f57b4e…",
    brand: "Acme Destek",
    color: "#7c3aed",
    launcherText: "Bize yazın",
    texts: { greetingMessage: "Merhaba! Size nasıl yardımcı olabiliriz?" }
  };
  // İsteğe bağlı: sitenizde oturum açmış kullanıcıyı tanıtın —
  // karşılama formu sorulmaz, sohbet doğrudan başlar:
  // window.cxperiumSettings.user = { name: "Ahmet Yılmaz", username: "ahmet.y" };
  (function (d) {
    var s = d.createElement("script");
    s.src = "https://cdn.cxperium.com/widget/v1/cxperium-widget.js";
    s.async = true;
    d.head.appendChild(s);
  })(document);
</script>

1. Kodu kopyalayın

   Kanal oluşturmanın son adımında ya da Kanallar → Detay penceresinde Kopyala'ya basın. Görünümü özelleştirdiyseniz kodu Widget Tasarımcısı'ndan kopyalayın; oradaki kod seçtiğiniz tasarımı içerir.

2. Siteye yapıştırın

   Sohbetin görünmesini istediğiniz her sayfada </body> etiketinden hemen önce yapıştırın. Sayfada yalnızca bir Cxperium kodu olmalı; eskisi varsa silin.

3. Sayfayı yenileyin

   Balon seçtiğiniz köşede görünmelidir. Görünmüyorsa sayfayı önbelleksiz yenileyin (Ctrl + F5).

Widget, ziyaretçinin kimliğini ve token'ını tarayıcıda saklar; ziyaretçi siteye geri döndüğünde önceki konuşmasına devam edebilir ya da yeni bir konuşma açabilir. Sitenizde oturum açmış kullanıcıyı user ayarıyla tanıtırsanız karşılama formu hiç sorulmaz.

Mobil uygulamada aynı widget: Custom kanalı bir WebView içinde de kullanabilirsiniz. Kanallar listesinde mobil kanalın WebView Özelleştirici ekranı, uygulamanıza gömeceğiniz sayfanın görünümünü ayarlar; böylece aşağıdaki SDK entegrasyonunu yazmadan sohbeti uygulamaya ekleyebilirsiniz.

Widget Görünümü (Widget Tasarımcısı)

Balonun rengini, konumunu, metinlerini ve markasını panelden değiştirirsiniz. Tasarımcı yalnızca Web türündeki kanallarda açılır.

Tasarımcıya iki yerden ulaşırsınız: kanalı oluşturduğunuz anda son adımdaki Görünümü özelleştir düğmesinden ya da daha sonra Kanallar listesinde kanalın Detay penceresinden. Ekran üç parçadır: solda ayarlar, sağda canlı önizleme (Sohbet / Karşılama formu görünümleri), önizlemenin altında kurulum kodu. Kaydet düğmesi yoktur; her değişiklik yaklaşık yarım saniye içinde hem önizlemeye hem koda yansır.

Marka

Renkler ve yazı tipi

Yerleşim ve boyut

Metinler ve davranış

Kurulum kodunda yalnızca varsayılandan farklı ayarlar yer alır; bu yüzden kod kısa kalır. Üst çubuktaki Varsayılanlara dön tüm ayarları ve taslağı temizler.

Mobil Uygulama (Custom Kanal)

Mobil kanal (custom kanal), iOS, Android, React Native ya da Flutter uygulamanızı doğrudan Cxperium'a bağlar. Kullanıcı uygulamada mesaj yazar, bot ya da temsilci cevaplar, cevap anında uygulamaya düşer. Backend gerekmez.

İki kurulum yolu

Karar tek soruya bağlı: uygulamanız ile Cxperium arasına kendi sunucunuz girecek mi?

Backend'iniz yoksa A yolunu izleyin. Aşağıdaki adımlar A yolunu anlatır; B yolu için yalnızca kimlik başlığı değişir (bkz. "Sunucunuz varsa: imza").

Adım 1: Kayıt ol (ilk açılışta bir kez)

const res = await fetch("https://provider.cxperium.com/custom/ch_xxxxxxxx/register", {
  method: "POST",
  headers: { "apiKey": SECRET, "Content-Type": "application/json" },
  body: JSON.stringify({ user: { name: "Ahmet" } }),
}).then((r) => r.json());

// res = { status: 200, channelKey: "ch_xxxxxxxx",
//         contact: { id: "c_5d5cdeb1-…" }, token: "8abfc196…" }
sakla("contactId", res.contact.id);   // Keychain / EncryptedSharedPreferences
sakla("token", res.token);             // süresi dolmaz, bir kez alınır

Uygulama silinip yeniden kurulduysa ve saklı contactId elinizdeyse kayıt gövdesine user.id olarak ekleyin; aynı token döner ve sohbet kaldığı yerden devam eder. Kullanıcı kimliğinde & karakteri bulunamaz.

Adım 2: Bağlan ve geçmişi çek (her açılışta)

import { io } from "socket.io-client";

const socket = io("https://ws.cxperium.com/custom", {
  transports: ["websocket"],
  auth: { channelKey: "ch_xxxxxxxx", user: contactId, token },
});

socket.on("connect", async () => {
  // SIRA ÖNEMLİ: önce bağlan, SONRA geçmişi çek — tersi mesaj kaçırır.
  // Mesajları yerelde saklıyorsanız after = son görülen seq; saklamıyorsanız 0.
  let after = sakli("sonSeq") || 0;
  for (;;) {
    const h = await fetch(
      `https://provider.cxperium.com/custom/ch_xxxxxxxx/messages?user=${contactId}&after=${after}&limit=50`,
      { headers: { Authorization: `Bearer ${token}` } },
    ).then((r) => r.json());
    for (const m of h.messages) ekranaCiz(m);
    if (!h.hasMore) break;
    after = h.cursor;   // sayfanın cursor'ından ilerleyin, kendi sayacınızdan değil
  }
});

Geçmiş iki yönü birden döner: direction: "in" kullanıcının kendi mesajı (ekranda sağa), "out" bot ya da temsilci cevabı (sola). seq kullanıcı başına artan sıra numarasıdır.

Adım 3: Mesaj gönder, cevap al, teslim onayla

// Gönder — id tekrar korumasıdır: ağ hatasında aynı id ile yeniden yollayın
socket.emit("message.send",
  { user: { name: "Ahmet" }, message: { id: benzersizId(), type: "text", text: "merhaba" } },
  (ack) => { /* ack = { status: 202, messageId: "…" } */ });

// Al — m = { id, seq, ts, type, text, choices, media, link, form }
socket.on("message.created", (m) => {
  if (gorulenler.has(m.id)) return;   // aynı mesaj iki kez gelebilir
  gorulenler.add(m.id);
  ekranaCiz(m);
  sakla("sonSeq", m.seq);
  socket.emit("message.ack", { seq: m.seq }, () => {});   // seq'e kadar her şey teslim sayılır
});

WebSocket kopuksa aynı gövde REST'e de atılabilir: POST /custom/<KEY>/messages ve POST /custom/<KEY>/ack, Authorization: Bearer <token> başlığıyla. socket.io kopan bağlantıyı kendisi yeniler; connect geldiğinde Adım 2'deki geçmiş çekmeyi tekrar çalıştırın, arada kaçan mesajlar gelir.

• contactId ve token'ı kalıcı saklayın — uygulama kapanınca kaybolmasın.
• Önce WebSocket, sonra geçmiş — ters sıra aradaki saniyelerde gelen mesajı kaçırır.
• Mesajları id ile tekilleştirin — sistem "en az bir kez teslim" garantisi verir, "tam bir kez" değil.
• Sayfalarken after'ı cevaptaki cursor'dan ilerletin — kendi tuttuğunuz sayaçtan değil.
• Kopunca panik yok — yeniden bağlanınca geçmişi çekin; mesaj kaybolmaz.

Sunucunuz varsa: imza (B yolu)

Uygulama sizin sunucunuza, sunucunuz Cxperium'a gider. Secret uygulamaya inmez. Her isteğe X-Cxperium-Signature: t=<unix saniye>,v1=<hex> başlığı eklenir; v1 = HMAC-SHA256(secret, "<t>.<içerik>"). İçerik POST isteklerinde gövdenin ham JSON metni, WebSocket bağlantısında ve geçmiş sorgusunda "<channelKey>:<userId>" dizesidir. İmza 300 saniye geçerlidir; her istekte yeniden üretin.

const crypto = require("crypto");
function imzala(icerik) {
  const t = Math.floor(Date.now() / 1000);
  const v1 = crypto.createHmac("sha256", CHANNEL_SECRET).update(`${t}.${icerik}`).digest("hex");
  return `t=${t},v1=${v1}`;
}

// WebSocket'te auth STATİK OBJE DEĞİL, FONKSİYON olmalı — yeniden bağlanmada imza tazelenir
const socket = io("https://ws.cxperium.com/custom", {
  transports: ["websocket"],
  auth: (cb) => cb({ channelKey: CHANNEL_KEY, user: userId, signature: imzala(`${CHANNEL_KEY}:${userId}`) }),
});

Mesaj Tipleri ve Formlar

Aynı mesaj gövdesi WebSocket message.created olayında, geçmiş sorgusunda ve teslim webhook'unda birebir aynıdır. Tanımadığınız bir type gelirse text alanını gösterin; yeni tipler zamanla eklenir ve text her zaman doludur.

Kullanıcıdan bota gönderebilecekleriniz

Konum (location) tipi henüz desteklenmez; gönderirseniz 202 alırsınız ama işlenmez.

Bottan kullanıcıya gelebilecekler

Formlar (Flow)

Bot, WhatsApp'taki Flow ile aynı kodla custom kanala da form gönderebilir. Form tanımı mesajın içinde form.screens olarak gelir; ekranlar Meta Flow JSON biçimindedir (TextInput, Dropdown, RadioButtonsGroup, CheckboxGroup, DatePicker, Footer). form.screen ile başlayın; form.data ilk ekranın verisidir. Form çizemiyorsanız en azından text alanını gösterin.

• Cevap: Son ekranın Footer aksiyonu complete ise doldurulan alanları form tipinde normal mesaj olarak gönderin; token zorunludur.
• Sunucudan ekran isteme: Footer aksiyonu data_exchange ise POST /custom/<KEY>/flows/exchange çağırın; yanıt { "version": "3.0", "screen": "…", "data": { … } } döner. screen değeri SUCCESS ise formu kapatıp data.extension_message_response.params nesnesini cevap olarak gönderin.
• Hazır uygulama: Web widget'ı bu bölümün tamamını uygular; WebView entegrasyonunda ek iş gerekmez.

Sorun Giderme

En sık karşılaşılan durumlar ve çözümleri.

Web widget'ı

Custom kanal (mobil)