Bu rehberde: Facebook Sayfanızın Messenger gelen kutusunu OrqLabs'a bağlarsınız. AI Chatbot yanıtlar; gerekirse insana devreder. Instagram DM'leri bu kapsamda değildir.
⏱ 20 dakika
Kimlik kartı
| Alan | Değer |
|---|---|
| Sağlayıcı anahtarı | MESSENGER |
| Kategori | Mesajlaşma |
| Kimlik doğrulama | İzin ekranı (Meta, sayfa izni) |
| Kapsam | Proje bazlı |
| Webhook | Evet (Meta doğrulaması + mesajlar) |
| Yetenekler | Mesaj gönderme, mesaj alma |
| Kullanan kutular | Mesaj geldi, Mesaj gönder, İnsana devret |
| Kullanan ajanlar | AI Chatbot |
Ön koşullar
- Yönetici olduğunuz Facebook Sayfası ve Facebook Page rehberindeki Meta uygulaması (
META_APP_ID,META_APP_SECRET). - Sayfa ayarlarında Mesajlaşma açık.
- Herkese açık HTTPS adres.
Adım adım kurulum
A) Meta for Developers
- Uygulamanızda ① Add products → Messenger → Set up.
- Facebook Login for Business → Settings → Valid OAuth Redirect URIs → ①
https://api.orqlabs.com/api/v1/integrations/oauth/messenger/callback.
- ① Use cases → Customize:
pages_messaging,pages_manage_metadata,pages_show_list. - Messenger → Messenger API Settings → Configure webhooks: ② Callback URL ve ③ Verify token (OrqLabs'tan; aşağıda) → Verify and save. ④ Webhook fields:
messages,messaging_postbacks,messaging_optins; isteğe bağlımessage_deliveries,message_reads.
- ① App ID ve ② App secret Facebook Page ile aynıdır. ③ Gizlilik politikası ve App domains dolu olsun.
B) OrqLabs'ta bağlama
- Entegrasyonlar → Facebook Messenger → Bağla → ① Proje → ② Bağla.
- Meta izin ekranında Sayfayı seçip izinleri onaylayın.
- Geri dönüşte bu bağlantının sayfasını seçin. OrqLabs sayfa iznini alır ve sayfayı webhook'a abone eder.
- Webhook adresini Meta'ya girmediyseniz şimdi girin (aşağıda).
- Sayfanıza Messenger'dan mesaj gönderin; Gelen Kutusu'nda konuşma oluşmalı.
Webhook kurulumu
- ③ Callback URL:
https://api.orqlabs.com/api/v1/webhooks/messenger/<hesap kimliği>. - ④ Verify Token: panelde gösterilen değer.
- Meta istekleri
X-Hub-Signature-256ile imzalar; OrqLabsMETA_APP_SECRETile doğrular. - Aynı uygulamada WhatsApp da varsa her ürün kendi Callback URL'sini kullanır.
İzinler ve kapsamlar
| Kapsam | Neden gerekli |
|---|---|
pages_messaging | Sayfa adına mesaj gönderme ve alma |
pages_manage_metadata | Webhook aboneliği |
pages_show_list | Sayfaları listeleme |
Uygulama incelemesi
Dikkat: Development mode'da yalnızca uygulama rollerindeki kişilerin mesajları webhook'u tetikler. "Mesajlar düşmüyor" şikâyetinin en yaygın nedeni budur.
- Live mode:
pages_messagingiçin App Review ve Business verification. - 24 saat penceresi: kullanıcı mesajından sonra 24 saat serbest yanıt; sonrasında yalnızca özel etiketler (ayrıca izin gerekir). Pencere dışında Mesaj gönder
INVALID(kod 10) döner.
Limitler
| Konu | Sınır |
|---|---|
| Gönderim | ~250 mesaj/saniye; pratikte 20-40/dk |
| Metin | 2.000 karakter |
| Medya | Görsel 8 MB, video/dosya 25 MB |
| Kişi kimliği | Sayfa başına farklıdır; aday eşleştirmesi e-posta/telefonla |
Bağlantıyı test etme
② Bağlantıyı test et sayfa adını ve webhook aboneliğini doğrular. Sayfaya test mesajı gönderin; chatbot şablonunda Mesaj geldi kanallarına Messenger ekleyin.
Kimlik bilgilerini yenileme
Sayfa izni Facebook Page kurallarına tabidir → Yeniden yetkilendir. Webhook aboneliği otomatik yenilenir.
Sık karşılaşılan hatalar
| Hata | Olası neden | Çözüm |
|---|---|---|
| Webhook "couldn't be validated" | Adres erişilemez, token farklı | HTTPS; token'ı panelden kopyalayın |
| Mesajlar düşmüyor | Development modda ve gönderen rolde değil; messages seçilmemiş | Live moda alın / Tester ekleyin |
AUTH – kod 190 | İzin geçersiz | Yeniden yetkilendir |
INVALID – kod 10 | 24 saat penceresi kapandı | Kullanıcının yazmasını bekleyin |
INVALID – kod 200 | Advanced Access yok | App Review |
INVALID – kod 551 | Kullanıcı engelledi | Adaya unreachable etiketi |
RATE_LIMIT – kod 613 / 4 | Hız sınırı | Bekleme süresini artırın |
| İmza 401 | META_APP_SECRET yanlış | Yönetici düzeltir |
Sık sorulan sorular
Instagram DM'leri de gelir mi? Hayır. Bu entegrasyon yalnızca Facebook Sayfası Messenger'ı kapsar.
Pazarlama mesajı gönderebilir miyim? Yalnızca 24 saat penceresi içinde. Pencere dışı pazarlama Meta politikasına aykırıdır.
Test ederken mesajım neden düşmedi? Uygulama Development modda ise yalnızca uygulama rollerindeki kişilerin mesajları gelir. Hesabınızı Tester olarak ekleyin.