Facebook & Instagram API Kurulumu

Instance yöneticileri için adım adım anlatım: Meta for Developers portal'da tek bir Meta app oluştur ve hem Facebook hem Instagram kanal bağlantıları için kullan.

Bu admin tarafı dokümanıdır. Son-kullanıcı akışı için Bağlantılar → Facebook ve Bağlantılar → Instagram.

Genel bakış

Facebook ve Instagram tek bir Meta app'i paylaşır — Sosyabot her ikisi için aynı kimlik bilgilerini kullanır. /admin/api-integration/facebook admin formu şunları yazar:

Form alanı	Options anahtarı
App ID	facebook_app-id
App Secret	facebook_app-secret
Status (Etkinleştir / Devre Dışı)	facebook_integration_status

ENV fallback: FACEBOOK_APP_ID + FACEBOOK_APP_SECRET. Ayrı bir INSTAGRAM_* env bloku yoktur — Instagram aynı Meta kimlik bilgilerini requireFacebookCreds() ile çözer.

Instagram için admin paneli (/admin/api-integration/instagram) bilgilendirme amaçlıdır ve Facebook anahtarlarını yeniden kullanır; tek bir kez yapılandırma yeterli.

developers.facebook.com adım adım

1. Meta geliştirici hesabı oluştur

https://developers.facebook.com adresine git, app'in sahibi olmasını istediğin Facebook hesabıyla giriş yap ve geliştirici kaydını tamamla (telefon doğrulama).

2. Yeni app oluştur

My Apps → Create App. App type olarak Business seç (sayfa-yayınlama scope'ları için zorunlu). Bir ad ve iletişim e-postası ver.

3. Ürün ekle

Yeni app dashboard'unda şu ürünleri ekle:

• Facebook Login for Business — OAuth akışı için zorunlu.
• Instagram Graph API — Instagram Business / Creator yayını için zorunlu.
• (Opsiyonel) Threads — sonra Threads de yapılandıracaksan.

4. OAuth redirect URI yapılandır

Facebook Login for Business → Settings'i aç:

• Valid OAuth Redirect URIs:

  https://app.sosyabot.com/api/v1/auth/facebook/callback
  https://app.sosyabot.com/api/v1/auth/instagram/callback

  Self-hoster'lar: kendi BASE_URL'inle değiştir. Her iki ürünün çalışması için iki yol da gerekli.
• Kaydet.

5. Doğru izinleri talep et

App Review → Permissions and Features. Sosyabot şunlara ihtiyaç duyar:

• pages_show_list, pages_read_engagement, pages_manage_posts, publish_video (Facebook yayını)
• instagram_basic, instagram_content_publish, instagram_manage_insights (Instagram yayını)

Development modunda App Roles tester'larıyla bunları anında kullanabilirsin. Live'a geçmek her izin için App Review gerektirir — Meta her iznin nasıl kullanıldığını gösteren bir screencast ister.

6. App ID + App Secret'ı al

App dashboard'unda Settings → Basic'i aç. App ID ve App Secret'ı kopyala (Secret'ta Show'a tıkla).

App Secret rotasyonu

Meta App Secret'ı istediğin zaman yeniden generate etmene izin verir. Bunu yapmak Sosyabot'ta saklanan her token'ı geçersiz kılar ve her bağlı kullanıcıyı yeniden bağlanmaya zorlar. Yalnızca zorunlu kalırsan rotate et.

Sosyabot admin paneline yapıştırma

/admin/api-integration/facebook'i aç:

1. App ID: Settings → Basic'ten yapıştır.
2. App Secret: Show'la görünen secret'ı yapıştır.
3. Status: Enable.
4. Save → Test credentials. Başarılı yanıt App ID prefix'i + çözülmüş callback URL'i döner.

Hata mesajları:

• Facebook integration disabled: app id/secret not configured → admin panel ve ENV boş.

Instagram bu ayarları miras alır

Facebook yapılandırıldıktan sonra /admin/api-integration/instagram'de hiçbir şey doldurman gerekmez — aynı kimlik bilgileri her iki konektör tarafından okunur.

Doğrulama — uçtan uca smoke testi

1. /app/channels'tan bir Facebook Page bağla (admin/editor olduğun bir sayfa).
2. Scope'ları onayla → geri dön, sayfa active olarak listelensin.
3. /app/publishing'ten tek satırlık test gönderi yayınla; sayfanın public timeline'ında doğrula.
4. Bir Facebook Page'e bağlı Instagram Business / Creator hesabıyla tekrarla.

Sorun giderme

Belirti	Sebep	Çözüm
Facebook integration disabled: app id/secret not configured	Admin + ENV boş	5–6. adımları tamamla.
Invalid OAuth redirect URI	Redirect URI allow-list'te değil	Facebook Login → Settings'te tam …/api/v1/auth/facebook/callback (ve …/instagram/callback) ekle.
Instagram bağlantı başarılı ama hesap çıkmıyor	Facebook kullanıcısı Page admin'i olduğu Instagram Business / Creator hesabı yok	Instagram hesabını Business / Creator'a çevir ve bir Facebook Page'e bağla.
App Development modunda ve harici kullanıcılar başarısız	Mod App Roles ile sınırlı	App Roles altında tester ekle veya Live'a geç (App Review gerektirir).
Aniden 190 — Error validating access token	Token invalidate (şifre değişimi, güvenlik olayı, App Secret rotate edildi)	Etkilenen kullanıcılar /app/channels'tan reconnect yapmalı.

ENV fallback (self-hosters)

FACEBOOK_APP_ID=<app id'in>
FACEBOOK_APP_SECRET=<app secret'in>

backend/src/config/env.ts'den boot'ta okunur. Admin panel her zaman kazanır. .env düzenledikten sonra ./service.sh restart api çalıştır.

İlgili

OAuth Kimlik Bilgileri genel

Facebook kullanıcı bağlantı

Instagram kullanıcı bağlantı