Enter tuşuna basın.
Verilerinizi alın.

Hızlı başlangıç

Sıfırdan ilk cevaba üç adım. Her istek bir widget'a bağlanır ve bir taşıyıcı jetonla doğrulanır.

1. Bir jeton düzenleyinKontrol Paneli → API belirteçleri: bir ad, isteğe bağlı bir süre sonu ve ihtiyacınız olan kapsamlar. Bir jeton tam olarak bir widget'a aittir. Düz metin belirteci bir kez gösterilir; Smartbtn yalnızca tek yönlü bir hash saklar, dolayısıyla kayıp bir token kurtarılamaz; yalnızca iptal edilir ve yeniden verilir.
2. Widget API'sini açınWidget ayarlarında «Widget API'sine izin ver (JS ve REST)» seçeneğini açın. Bir jeton yayınlamak sizin için bu anahtarı çevirmez.
3. İlk isteği gönderBelirteç yalnızca Yetkilendirme başlığına gider; asla URL'ye girmez.

# widget'ın sohbetlerini listele
curl -H "Authorization: Bearer $SMARTBTN_TOKEN" \
     https://smartbtn.me/api/v1/chats

// 200 OK · imleç sayfalandırması
{
  "data": [ { "id": 48211, "status": "open", "last_message_at": "2026-10-17T09:41:12+03:00" }, … ],
  "next_cursor": "eyJpZCI6NDgyMTB9"   // null — son sayfada
}

Kimlik doğrulama

Kimin kimi aradığına bağlı olarak üç yol. Erişim varsayılan olarak reddedilir: kapsam yok - çağrı yok.

İnsanların unuttuğu anahtar

Widget ayarlarında «Widget API'sine izin ver (JS ve REST)» seçeneği hem REST API'yi hem de widget JS API'sini açar. Bir jetonun verilmesi bunu etkinleştirmez. Mevcut bir anahtarın kapsamları, kontrol panelinde (API belirteçleri → anahtar → Kapsamları düzenle) yeniden yayınlamaya gerek kalmadan düzenlenebilir; entegrasyonlar çalışmaya devam eder.

Ön ayarlar

Kapsamlar

53 rota kapsamı artı bir koşullu ve bir ayrılmış. Bir istek yalnızca belirtecin rota kapsamını (veya listelenen bir alternatifi) içermesi durumunda başarılı olur.

Uç noktalar

Tüm halka açık yüzey tek bir listede. Kaynağa göre filtreleyin, yola göre arayın, hazır bir kıvrımı kopyalamak için bir satırı tıklayın.

Yollar https://smartbtn.me/api ile ilişkilidir. Yazma işlemleri için Content‑Type: application/json ve X‑Smartbtn‑Idempotency‑Key gerekir. compat grubu, başka bir sohbet platformundan geçiş yapan ekipler için bir uyumluluk katmanıdır.

Web kancaları

Abone olunan bir etkinlik gerçekleştiğinde URL'nize imzalı bir JSON POST gönderilir. Abonelikleri /v1/webhook‑subscriptions aracılığıyla veya kontrol panelinden yönetin.

{
  "id": "evt_01JAB3K9Q7",
  "type": "ticket.created",
  "data": {
    "button_guid": "b_3f9c2e",
    "ticket_number": 10482,
    "chat_id": 48211,
    "client_id": 9134,
    "reason": "human_request",
    "priority": "high",
    "sla_hours": 4,
    "source": "chat",
    "created_at": "2026-10-17T10:15:00+03:00"
  }
}

Teslimat başlıkları

İmza doğrulama

Uç nokta sırrınızla birlikte ham gövdenin HMAC‑SHA256'sı (JSON ayrıştırmasından önce alınan bayt sayısı); sabit zamanda karşılaştırın. Bu sır, abonelik oluşturulduğunda bir kez gösterilir; POST /v1/webhook‑subscriptions/{id}/rotate‑secret ile döndürün.

// Node.js · örneğin, sır bir yer tutucudur
import crypto from 'node:crypto';

function verify(rawBody, header, secret) {
  const expected = 'sha256=v1:' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  const a = Buffer.from(expected), b = Buffer.from(header || '');
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

// PHP
$expected = 'sha256=v1:' . hash_hmac('sha256', file_get_contents('php://input'), $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_SMARTBTN_SIGNATURE'] ?? '')) { http_response_code(401); exit; }

Yeniden denemeler ve sipariş

• En fazla 4 deneme (ilk gönderme artı 3 yeniden deneme), geri alma dak(60, 2^deneme × 5) saniye — yaklaşık 10, 20, 40 saniye.
• 2xx olmayan veya zaman aşımı başarısız bir girişim olarak sayılır. Başarısız teslimatlar POST /v1/webhook‑subscriptions/{id}/redeliver ile yeniden gönderilebilir - aynı idempotency anahtarı, yeni teslimat kimliği.
• Teslimat en az bir kez yapılır ve sipariş edilmez. Yükler minimum düzeydedir; tam kayıtlar değil, kimlikler; REST API aracılığıyla ayrıntıları alın.

JS API

Ziyaretçi hakkında bildiklerinizi doğrudan temsilciye iletin. Aramalar yalnızca widget ayarlarında belirlenen alan adından kabul edilir.

smartbtn_widget_api.setContactInfo(info)

Ziyaretçinin iletişim verilerini ayarlar. Temsilci, ziyaretçinin giriş formunu doldurmuş gibi görür. Ad, telefon ve e‑posta Smartbtn'de özel bir rol oynar; dolayısıyla ayrı bir yöntemdir.

Smartbtn_api.setClientInfo({
  name: "Alex Morgan",
  email: "email@example.com",
  phone: "+17584987855",
  description: "Description text"
});

smartbtn_widget_api.setCustomData(fields)

Temsilci uygulamasının sağındaki bilgi paneline ilişkin ekstra veriler. İstediğiniz sıklıkta arayın; açık bir iletişim kutusunda panel gerçek zamanlı olarak güncellenir. Alanlar dizi sırasına göre gösterilir.

Smartbtn_api.setClientCustomData([
  { title: "Order", content: "#10482 · 3 items", link: "https://shop.example/orders/10482" },
  { title: "Actions", content: "Open customer profile", link: "https://crm.example/c/9134" }
]);

smartbtn_widget_api.setSkin(skin, opts) · open() · close()

Sayfayı yeniden yüklemeden widget temasını anında değiştirin (klasik, minimal, kapsül, sıvı) veya sohbet penceresini programlı olarak kontrol edin. Proje bazında kalıcı özelleştirme için aynı alanları PATCH /v1/widget/settings'e iletin.

// JS API · sayfadaki görünümü gerçek zamanlı olarak değiştirin
smartbtn_widget_api.setSkin("minimal");
smartbtn_widget_api.setSkin("capsule", { capsuleTitle: "Smartbtn AI", capsuleSubtitle: "Yanıt ~1 saniye içinde" });

// REST API · PATCH /v1/widget/settings (kapsam widget:write)
{
  "skin": "minimal",
  "widget_header_align": "center",
  "widget_show_operator_avatars": false,
  "widget_show_tabs_bar": false,
  "chat_bg": "#FAF8F5",
  "capsule_title": "Smartbtn AI",
  "capsule_subtitle": "7/24 Çevrimiçi"
}

Support‑agent API

Otomatik bir destek temsilcisi, bilet kuyruğunu ve müşteri sohbetlerini yönetir: sohbeti alır, insan destek operatörünüz olarak yanıt verir ve bildirimi kapatır. Widget sahibi onu açana kadar kapalıdır.

curl -X POST https://smartbtn.me/api/v1/support/chats/48211/reply \
  -H "Authorization: Bearer $AGENT_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $(uuidgen)" \
  -d '{"text":"Bitti, erişim yeniden sağlandı."}'

AI API'si

Kontrol panelinin AI bölümünün yaptığı her şey: asistanlar, kendi sağlayıcı anahtarlarınız, bilgi tabanınız, geri alma ile kendi kendine öğrenme, dilekler, sorunlar, talep sinyalleri ve uygulamanızın içindeki bir asistan.

Oran sınırları

Belirteç başına iki sayaç: okuma ve yazma işlemleri ayrı ayrı sayılır, bu nedenle yoklama hiçbir zaman yazma bütçesini tüketmez.

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "status": 429, "title": "Too Many Requests", "reason": "rate_limited" }

/v1/ai/assistant/tickets/status ve /v1/ai/assistant/account‑link'in kendi sayaçları vardır; destek aracısı API'si, widget başına geçersiz kılmaya sahip olabilir.

Hatalar

Her hata RFC‑7807 application/problem+json'dur: makine tarafından okunabilen bir durum ve neden, insan tarafından okunabilen bir ayrıntı.

HTTP/1.1 403 · Content-Type: application/problem+json
{
  "type": "https://smartbtn.me/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Token lacks scope chats:write.",
  "required_scopes": [
    "chats:write"
  ],
  "hint": "Dashboard → API tokens → key → Edit scopes"
}

Gerekli_kapsamların gövde adları ve bunların nereye verileceği. Anahtarı yeniden vermenize gerek yok.

iktidarsızlık

Ağlar başarısız oluyor. Bir anahtar, yeniden denenen yazmayı güvenli hale getirir: aynı işlem hiçbir zaman iki kez uygulanmaz.

• Her POST / PATCH / PUT / DELETE'de X‑Smartbtn‑Idempotency‑Key gönderin: yeni bir işlem için yeni bir UUID, aynı işlemin yeniden denenmesi için aynı anahtar.
• OpenAPI'de x‑idempotency: gerekli olarak işaretlenen işlemler: anahtar yok → 400, anahtar 24 saat içinde yeniden kullanıldı → 409 (önbelleğe alınmış bir başarı değil).
• Geçtiğinden emin değil misiniz? Önce durumu okuyun. Anahtarı asla otomatik olarak değiştirmeyin; Yeniden Dene‑Sonra'ya saygı gösterin.
• Yukarı akış sağlayıcısından gelen bir 502 anahtarı serbest bırakır; aynı anahtarla yeniden deneyin.

KEY=$(uuidgen)
curl -X PATCH https://smartbtn.me/api/v1/widget/settings \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Smartbtn-Idempotency-Key: $KEY" \
  -d '{"language":"ru"}'
# ağ hatası mı? aynı $KEY ile tekrarlayın

Changelog

2026'da genel API ve web kancalarında yapılacak değişiklikler. Aşağıdaki her şey ekleme niteliğindedir ve v1'de kalır.

WordPress eklentisi

Tema koduna dokunmadan bir WordPress sitesindeki widget.

Kod örnekleri

İmleci sonuna kadar takip ederek, son anketinizden bu yana gerçekleşen tüm sohbet etkinliklerini listeleyin.

# ilk sayfa
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "updated_since=2026-10-17T09:00:00+03:00"

# next - yanıttaki next_cursor ile
curl -G https://smartbtn.me/api/v1/chats \
  -H "Authorization: Bearer $SMARTBTN_TOKEN" \
  --data-urlencode "cursor=eyJpZCI6NDgyMDd9"