X (Twitter) API Kurulumu
Instance yöneticileri için adım adım anlatım: bir X (eski adıyla Twitter) Developer App oluştur, OAuth 2.0 kimlik bilgilerini Sosyabot'un /admin/api-integration/x-twitter sayfasına yapıştır ve gerçek bir hesap bağlantısını uçtan uca doğrula.
Bu admin tarafı dokümanıdır. Son-kullanıcı akışı (bir kullanıcının Bağlan → X'e tıklaması) için Bağlantılar → X (Twitter)'ye bak.
Genel bakış
Sosyabot X kimlik bilgilerini çalışma zamanında şu sırayla çözer: admin panel override (Options koleksiyonu) → ENV değişkeni. /admin/api-integration/x-twitter admin formu şunları yazar:
| Form alanı | Options anahtarı |
|---|---|
| Client ID | x-twitter_client-id |
| Client Secret | x-twitter_client-secret |
| Status (Etkinleştir / Devre Dışı) | x-twitter_integration_status |
ENV fallback (admin panel boş olduğunda kullanılır): TWITTER_CLIENT_ID + TWITTER_CLIENT_SECRET. Bkz. ENV Referansı.
Bu işi dağıtım başına yalnızca bir kez yapman yeter — değerler instance geneli, çalışma alanı bazlı değil.
Fiyatlandırma & tier
X ücretli-API modeline geçti. 2026 itibarıyla aktif tier'lar:
| Tier | Maliyet | Notlar |
|---|---|---|
| Pay-Per-Use (yeni hesaplarda varsayılan) | ~yazma başına $0.01, okuma başına ~$0.005 | OAuth 2.0 dahil; bugün kayıt olursan bu olur. |
| Basic (legacy) | $200/ay | Yeni kayıtlara kapalı; mevcut abonelere açık. |
| Pro (legacy) | $5.000/ay | Yalnızca mevcut abonelere. |
| Enterprise | $42.000+/ay | X satış ekibiyle iletişim. |
Sosyabot OAuth 2.0 user-authorization akışını kullanır; bu akış her tier'da mevcuttur — auth-flow tier kısıtı yoktur. Tier yalnızca istek hacmini ve çağrı başı faturalandırmayı kontrol eder.
Free tier yok
Free tier yeni kayıtlara Şubat 2026'da kapatıldı. Yeni geliştirici hesapları, API üzerinden tweet göndermeden önce Pay-Per-Use'da faturalandırma açmak zorundadır.
developer.x.com adım adım
1. Geliştirici hesabı için kayıt ol
https://developer.x.com adresine git, app'in sahibi olmasını istediğin X hesabıyla giriş yap ve Developer Agreement'i kabul et. (Eski developer.twitter.com URL'si hâlâ redirect ediyor.)
2. Bir Project, sonra içine bir App oluştur
App yönetimi https://console.x.com adresinde.
- Projects & Apps → Create Project. Bir ad ver, kullanım amacı seç ("Making a bot", "Building tools for businesses" vb.) ve kısa bir açıklama yaz.
- Yeni Project'in içinde Create App'e tıkla. Global olarak benzersiz bir app adı seç.
3. Kullanıcı kimlik doğrulamasını yapılandır
App'i aç ve User authentication settings → Set up'a tıkla. Doldur:
- Type of App: Web App, Automated App or Bot (bu Confidential client seçeneğidir — Sosyabot'un sunucu-tarafı OAuth akışı için zorunludur). Native App veya Public Client seçme — ikisi de başarısız olur.
- App permissions: Read and write. (Sonra DM özellikleri istersen Direct messages ekleyebilirsin.)
- Callback URI / Redirect URL:Self-hoster'lar: kendi
https://app.sosyabot.com/api/v1/auth/twitter/callbackBASE_URL'inle değiştir. Yol (/api/v1/auth/twitter/callback) sabittir. - Website URL:
https://sosyabot.com(veya kendi tanıtım siten).
Formu kaydet. X kaydetme anında callback URL'ini doğrular — yanlış yazarsan kaydetme anında başarısız olur.
Yalnızca Confidential client
Sosyabot entegrasyonu confidential OAuth 2.0 client kullanır. Public Client / Native App seçenekleri client-secret takasını tamamen atlar ve Sosyabot her callback'te 401 Unauthorized döner.
4. Client ID + Client Secret'ı al
Kaydettikten sonra App'in Keys and tokens sekmesini aç. OAuth 2.0 Client ID and Client Secret altında her iki değeri de kopyala.
Client Secret yalnızca bir kez gösterilir
X secret'ı bir tek kez gösterir. Modal'ı kaydetmeden kapatırsan yeniden generate etmek zorundasın (bu eskisini geçersiz kılar ve mevcut Sosyabot bağlantılarını bozar). Sayfadan ayrılmadan ikisini bir şifre yöneticisinde sakla.
- adımda set ettiğin callback URL de burada doğrulama amacıyla görünür.
Sosyabot admin paneline yapıştırma
/admin/api-integration/x-twitter'i aç (Yönetim Paneli → OAuth Kimlik Bilgileri → X (Twitter)).
- Client ID: Keys and tokens sekmesindeki OAuth 2.0 Client ID'yi yapıştır.
- Client Secret: OAuth 2.0 Client Secret'ı yapıştır. Sosyabot bunu
Optionsanahtarıx-twitter_client-secretaltında saklar (depolama config'ine göre at-rest şifreli). - Status: Enable. Disable, kullanıcıya yönelik kanal sayfasındaki Connect butonunu gizler; mevcut bağlantılar token'ları expire olana kadar çalışmaya devam eder.
- Save'e tıkla.
- Test credentials'a tıkla. Başarılı yanıt Client ID'nin ilk 6 karakterini ve Sosyabot'un X'e göndereceği tam callback URL'ini gösterir. Başarısızlık şunlardan birini gösterir:
Twitter integration disabled: client id/secret not configured→ hem admin panel hem ENV boş.X (Twitter) integration disabled by admin→ status toggle Disable.
Restart gerekmez
Twitter passport stratejisi credentials değiştiğinde kendini yeniden yükleyecek şekilde bağlanmıştır. Save'den sonra ./service.sh restart api'a ihtiyacın yok — bir sonraki OAuth callback yeni değerleri kullanır.
Doğrulama — uçtan uca smoke testi
/app/channels'i normal bir çalışma alanı kullanıcısı olarak (veya kendin) aç.- Connect → X (Twitter) → OAuth'a tıkla.
- X scope onay ekranını açar. Onayla.
/app/channels'a geri dönmelisin ve X hesabı active olarak listelenmeli./app/publishing'i aç, yeni kanalı hedefleyen tek satırlık bir test tweet'i taslakla, Publish now'a bas.- Tweet'in birkaç saniye içinde X hesabının public timeline'ında göründüğünü doğrula.
Herhangi bir adım başarısız olursa aşağıdaki Sorun giderme'ye bak.
Sorun giderme
| Belirti | Sebep | Çözüm |
|---|---|---|
Test'te Twitter integration disabled: client id/secret not configured | Admin panel boş VE ENV boş | Yukarıdaki 3-4. adımları tamamla. |
Test'te X (Twitter) integration disabled by admin | Status toggle Disable'da | Status'ü Enable yap ve kaydet. |
Callback'te 401 Unauthorized | Yanlış Client ID/Secret VEYA app type Public Client | Keys and tokens'tan değerleri yeniden kopyala; app type'ın Confidential (Web App, Automated App or Bot) olduğunu doğrula. |
Onay ekranında Callback URL mismatch | Portal'daki Callback URI Sosyabot'un gönderdiği URL ile bire bir eşleşmiyor | Trailing slash dahil tam string'leri karşılaştır. |
Yayında 429 Too Many Requests | X rate limit | POST /2/tweets tavanları: kullanıcı başına 100/15dk, app başına 10.000/24sa. x-rate-limit-reset yanıt header'ı reset epoch'u verir. |
Bağlı kanal aniden needs_reconnect gösteriyor | Access token expire oldu | Sosyabot offline.access scope'unu talep etmez, yani otomatik refresh yoktur — son kullanıcı /app/channels'tan reconnect yapmalıdır. |
offline.access kararı bu build'de bilinçlidir — gerekçe için kullanıcı tarafı Bağlantılar → X sayfasına bak (cookie-connect modu uzun ömürlü alternatif olarak sunulur).
ENV fallback (self-hosters)
Secret'ları admin panel yerine .env'de yapılandırmayı tercih edersen:
TWITTER_CLIENT_ID=<client id'in>
TWITTER_CLIENT_SECRET=<client secret'in>Bunlar backend/src/config/env.ts'den boot anında okunur ve admin panel boş olduğunda fallback olarak hareket eder. Admin panel her zaman kazanır — ikisini birden ayarlamak güvenlidir.
.env'i düzenledikten sonra ./service.sh restart api çalıştırmalısın (ENV süreç başlangıcında bir kez okunur; admin-panel yazımları restart gerektirmez).
Cookie connect alternatifi
X ayrıca bir cookie-tabanlı connect yolu (POST /api/v1/auth/twitter/unofficial) sunar; bu yol OAuth client'ı tamamen atlar ve giriş yapmış bir tarayıcının auth_token + ct0 cookie'lerini kullanır. Geliştirici uygulaması kaydetmek istemediğin kişisel handle'lar için yararlıdır. Kullanıcı yönergeleri için Bağlantılar → X'e bak.
Cookie connect hiçbir admin yapılandırması gerektirmez — bu sayfadaki kimlik bilgileri yalnızca OAuth yolunu etkiler.