Bu rehberde: X hesabınızı OrqLabs'a bağlarsınız. Platform yöneticisi X Developer Portal'da bir uygulama oluşturur; siz Bağla deyip izin verirsiniz. Erişim katmanlarını ve sınırları öğrenirsiniz.
⏱ 20 dakika (uygulama oluşturma dahil)
Kimlik kartı
| Alan | Değer |
|---|---|
| Sağlayıcı anahtarı | X |
| Kategori | Sosyal medya |
| Kimlik doğrulama | İzin ekranı (OAuth 2.0 PKCE) |
| Kapsam | Proje bazlı; her marka hesabı için ayrı bağlantı |
| Webhook | Hayır |
| Yetenekler | Gönderi yayınlama, metrik okuma, yorum okuma, yorum yanıtlama |
| Kullanan kutular | Yayınla, Zamanla, Metrik al, Yorumları al, Yanıtla |
| Kullanan ajanlar | Content Creator, Social Publisher, Community Manager |
Ne işe yarar?
- Metin, görsel ve video gönderileri yayınlar. 280 karakteri aşan içerik birden fazla gönderiden oluşan bir dizi (thread) olarak zincirlenir.
- Son gönderilerin gösterim, beğeni, yanıt, repost ve tıklama sayılarını çeker.
- Markanızdan bahseden gönderileri ve yanıtları toplar; Community Manager marka sesiyle yanıt verir.
İzin bir kez verilir; OrqLabs erişimi (2 saat geçerli) otomatik yeniler.
Ön koşullar
- Yayın yapacak X hesabı ve bu hesaba giriş yapabilen bir kişi. İzni hangi hesapla verirseniz gönderiler o hesaptan çıkar.
- developer.x.com üzerinde bir geliştirici hesabı.
- Hacminize uygun bir erişim katmanı (Free, Basic, Pro). Aşağıya bakın.
- Platform yöneticisinin
X_CLIENT_IDveX_CLIENT_SECRETdeğerlerini tanımlamış olması. Boşsa kartta "platformda yapılandırılmamış" uyarısı görünür. - OrqLabs'ta Sahip veya Yönetici rolü.
Adım adım kurulum
A) X Developer Portal (platform yöneticisi, bir kez)
- developer.x.com → Developer Portal ile giriş yapın. İlk kez giriyorsanız Sign up for Free Account seçin, kullanım amacınızı yazın ve sözleşmeyi kabul edin.
- Görseldeki ① + Create Project ile proje adı, kullanım senaryosu ve açıklama girin. Free katmanda hazır bir proje gelebilir.
- ② Add App ile bir uygulama ekleyin (ortam: Production).
- ③ Settings sekmesinde User authentication settings → Set up düğmesine basın.
- ① App permissions: Read and write seçin. Salt okunur izinle yayın 403 ile başarısız olur.
- ② Type of App: Web App, Automated App or Bot. Bu seçenek Client Secret üretir; OrqLabs sunucu tarafında çalıştığı için gereklidir.
- ① Callback URI / Redirect URL alanına şunu yapıştırın:
https://api.orqlabs.com/api/v1/integrations/oauth/x/callback. Tam adresi Entegrasyonlar sayfasındaki bağlantı penceresinden kopyalayın. En fazla 10 adres ekleyebilirsiniz. - ② Website URL: panelinizin adresi (
https://app.orqlabs.com). İsteğe bağlı: kuruluş adı, hizmet şartları, gizlilik politikası. - ③ Save. Kaydetmeden çıkarsanız yetkilendirme "Something went wrong" verir.
- Keys and tokens sekmesinde OAuth 2.0 Client ID and Client Secret bölümünden ① Client ID ve ② Client Secret değerlerini kopyalayın. Secret yalnızca üretildiği anda gösterilir; kaybettiyseniz Regenerate. Aynı sayfadaki "Consumer Keys" OAuth 1.0a içindir; OrqLabs kullanmaz.
- Yönetici bu değerleri
X_CLIENT_IDveX_CLIENT_SECRETolarak tanımlar ve API'yi yeniden başlatır.
B) OrqLabs'ta bağlama
- Entegrasyonlar sayfasında X (Twitter) kartında Bağla düğmesine basın.
- ①'de bu hesabın ait olduğu Proje'yi seçin.
- ② Bağla düğmesine basın. X'in Authorize app ekranı açılır. Ekranın üstünde hangi hesapla giriş yaptığınız yazar; kişisel hesabınız görünüyorsa önce x.com'da marka hesabına geçin.
- İzinleri inceleyip Authorize app düğmesine basın. Yetkilendirme kodu yaklaşık 30 saniye geçerlidir; ekranı uzun süre açık bırakmayın.
- OrqLabs'a geri dönersiniz. Kart Bağlı görünür ve hesabın
@kullaniciadideğerini gösterir. - Bağlantıyı test et ile doğrulayın. Aynı projeye ikinci bir X hesabı bağlamak için işlemi tekrarlayın.
İzinler ve kapsamlar
| Kapsam | Neden gerekli |
|---|---|
tweet.read | Gönderileri, bahsetmeleri ve metrikleri okuma |
tweet.write | Gönderi, dizi ve yanıt oluşturma |
users.read | Bağlı hesabın kimliğini okuma; bağlantı testi |
media.write | Görsel ve video yükleme |
offline.access | Yenileme izni. Bu olmadan erişim 2 saat sonra dolar |
Erişim katmanları
X, OAuth için ayrı bir uygulama incelemesi yapmaz. Ne yapabileceğinizi uygulamanın erişim katmanı belirler. Güncel değerleri Developer Portal'daki Products sayfasından kontrol edin. Yaklaşık değerler:
| Katman | Aylık ücret | Yazma | Okuma | Kimler için |
|---|---|---|---|---|
| Free | Ücretsiz | ~500 gönderi/ay | ~100 okuma/ay | Kurulum testi, çok düşük hacim |
| Basic | ~200 USD | ~3.000 gönderi/ay (kullanıcı), 50.000 (uygulama) | ~10.000 okuma/ay | Düzenli yayın + metrik ve bahsetme takibi |
| Pro | ~5.000 USD | ~300.000 gönderi/ay | ~1.000.000 okuma/ay | Ajans ve yüksek hacim |
Dikkat: Free katmanda bahsetme okuma ya kapalıdır ya da çok düşük kotalıdır. Community Manager ve Yorumları al kutusu için en az Basic gerekir.
- Metrik okuma her gönderi için okuma kotasından düşer; gün sayısını gereksiz büyütmeyin.
- Aylık kota dolunca X 429
UsageCapExceededdöndürür. - Aynı metni tekrar tekrar göndermek ve spam benzeri davranış hesabın kilitlenmesine yol açar.
Limitler
| Konu | Sınır |
|---|---|
| Metin | 280 karakter; her adres 23 karakter sayılır. OrqLabs doğrulayıcısı 280'e göre çalışır |
| Hashtag | 3 (OrqLabs doğrulaması) |
| Dizi (thread) | 280'i aşan metin birden fazla gönderi olarak zincirlenir; ilk gönderinin kimliği saklanır |
| Görsel | Gönderi başına en fazla 4; JPEG/PNG/WEBP 5 MB, GIF 15 MB |
| Video | MP4, 512 MB, standart hesaplarda ~140 saniye |
| Hız limitleri | 15 dakikalık pencerelerde kullanıcı başına |
| Aynı içerik | Kısa sürede birebir aynı metin 403 "duplicate content" |
| Medya adresi | Herkese açık olmalı; OrqLabs dosyayı indirip X'e yükler |
Bağlantıyı test etme
② Bağlantıyı test et hesabın @kullaniciadi, görünen adı ve iznin kalan süresini döndürür. Ardından bir iş akışında Yayınla kutusunu test modunda çalıştırın: metin uzunluğu, hashtag sayısı ve medya biçimi yayın yapılmadan doğrulanır.
Kimlik bilgilerini yenileme
- Erişim 2 saat geçerlidir; OrqLabs otomatik yeniler.
- Hesap sahibi x.com'da Settings → Security → Apps and sessions → Connected apps altından uygulamayı kaldırırsa kart "Yeniden yetkilendirme gerekli" olur. Yeniden yetkilendir aynı kaydı korur.
- Developer Portal'da izinler değiştiyse (Read → Read and write) tüm X bağlantılarını yeniden yetkilendirin.
- Client Secret yenilendiğinde yönetici
.env'i günceller ve tüm X bağlantıları yeniden yetkilendirilir.
Sık karşılaşılan hatalar
| Hata | Olası neden | Çözüm |
|---|---|---|
AUTH – 401 "Invalid or expired token" | İzin iptal edilmiş veya secret yenilenmiş | Yeniden yetkilendir |
| "Value passed for the authorization code was invalid" | Kod süresi dolmuş (~30 sn) veya Callback URI eşleşmiyor | Hızlı onaylayın; adresi bağlantı penceresinden kopyalayın |
| "Something went wrong" | Client ID yanlış, Callback URI kayıtlı değil, ayarlar kaydedilmemiş | User authentication settings'i kontrol edin |
| 403 "not permitted to perform this action" | Salt okunur izin | Read and write, sonra yeniden yetkilendir |
| 403 kod 453 "subset of X API V2 endpoints" | Uç nokta katmanda kapalı (Free'de bahsetme) | Basic veya üst katman |
| 403 "duplicate content" | Aynı metin kısa süre önce gönderilmiş | Metni değiştirin |
INVALID – 400 "Tweet text is too long" | 280 aşıldı | Kısaltın veya dizi olarak yayınlayın |
RATE_LIMIT – 429 | 15 dakikalık pencere | Otomatik yeniden deneme; metrik sıklığını azaltın |
| 429 "UsageCapExceeded" | Aylık katman kotası | Kota sıfırlanmasını bekleyin veya katman yükseltin |
| 403 medya yüklemede | Medya biçimi desteklenmiyor | JPEG/PNG/MP4 kullanın; boyut sınırlarına uyun |
| Hesap kilitli | Otomasyon kuralları tetiklenmiş | x.com'da hesabı doğrulayın; sıklığı azaltın |
UPSTREAM – 5xx | X tarafında kesinti | Otomatik tekrar; status.x.com |
Sık sorulan sorular
Free katman yeterli mi? Yalnızca kurulum testi ve çok düşük hacimli yayın için. Bahsetme okuma ve düzenli metrik için Basic gerekir.
Kişisel hesabımla mı marka hesabıyla mı izin vermeliyim? Marka hesabıyla. İzni hangi hesap verirse gönderiler o hesaptan çıkar.
Uzun metin nasıl yayınlanır? 280'i aşan metin otomatik olarak dizi (thread) hâline gelir.