WhatsApp Business (Cloud API)

Bu rehberde: WhatsApp işletme numaranızı OrqLabs'a bağlarsınız. Meta'da kalıcı bir erişim anahtarı üretir, OrqLabs'ta üç alanı doldurur ve gelen mesajlar için webhook kurarsınız.

⏱ 30 dakika

Kimlik kartı#

Ne işe yarar?#

WhatsApp Cloud API, Meta'nın barındırdığı resmi API'dir. Bağlandığında gelen müşteri mesajları Gelen Kutusu'nda konuşma olur ve iş akışınızı tetikler. AI Chatbot yanıt verir, müşteri bilgisi toplar, gerekirse insana devreder. Tekil mesaj ve onaylı şablonlarla kampanya gönderirsiniz.

Ön koşullar#

• Bir Meta Business Portfolio ve yönetici yetkisi.
• Meta for Developers hesabı ve "Business" türünde uygulama. Platform yöneticisinin META_APP_ID, META_APP_SECRET ve WHATSAPP_VERIFY_TOKEN tanımlamış olması.
• Başka bir WhatsApp hesabına kayıtlı olmayan bir telefon numarası. Numara şu an WhatsApp uygulamasında kullanılıyorsa önce o hesabı silmeniz gerekir.
• Canlı trafik için İşletme doğrulaması. Doğrulama olmadan test numarasıyla en fazla 5 alıcıya mesaj gönderebilirsiniz.

Adım adım kurulum#

A) Meta for Developers#

1. developers.facebook.com → My Apps → Create App → Other → Business → işletme portföyünüzü bağlayın.
2. ① Add products → WhatsApp → Set up.

3. WhatsApp → API Setup sayfasında ① Phone number ID ve ② WhatsApp Business Account ID değerlerini görürsünüz. Buradaki 24 saatlik geçici anahtarı yalnızca deneme için kullanın.
4. Kendi numaranızı eklemek için Add phone number → işletme adı, görünen ad, kategori, numara → SMS veya sesli doğrulama.
5. ③ Kalıcı anahtar üretin:
   1. business.facebook.com → Settings → Users → System users → Add. Rol: Admin.
   2. System user'ı seçin → Add assets → Apps → uygulamanızı seçin → Manage app açık.
   3. Accounts → WhatsApp accounts → hesabınızı ekleyip Manage yetkisi verin.
   4. Generate new token → uygulamanızı seçin → Token expiration: Never → izinler whatsapp_business_messaging, whatsapp_business_management → Generate token. Anahtar yalnızca bir kez gösterilir; kopyalayın.
6. Uygulamayı Live moda alın (üst çubuktaki App Mode). Development modunda yalnızca uygulama rollerindeki kişilere mesaj gider.

B) OrqLabs'ta bağlama#

1. Entegrasyonlar → WhatsApp Business (Cloud API) kartında Bağla.
2. ② Proje seçin.
3. Alanları doldurun:

4. ③ Bağla. OrqLabs numara bilgisini okuyarak doğrular; kart Bağlı olur.
5. Webhook adımını tamamlayın; webhook olmadan gelen mesajlar OrqLabs'a ulaşmaz.

Webhook kurulumu#

1. OrqLabs'ta WhatsApp kartını açın. ③ Webhook URL ve ④ Doğrulama token'ı değerlerini kopyalayın. Adres kalıbı: https://api.orqlabs.com/api/v1/webhooks/whatsapp/<hesap kimliği>.

2. Meta for Developers → WhatsApp → Configuration → Webhook → Edit.
3. ① Callback URL ve ② Verify token alanlarını yapıştırın → ③ Verify and save. Meta OrqLabs'a bir doğrulama isteği gönderir; eşleşirse kayıt tamamlanır.
4. ④ Webhook fields → Manage → messages alanında Subscribe. İsteğe bağlı: message_template_status_update, phone_number_quality_update.
5. Test: telefonunuzdan işletme numarasına "merhaba" yazın. Gelen Kutusu'nda yeni konuşma görünmeli.

Geliştirici notu: Yerel geliştirmede PUBLIC_WEBHOOK_URL için ngrok http 4000 adresini kullanın; adres değişince Meta'daki Callback URL'yi güncelleyin. Meta gelen isteği X-Hub-Signature-256 ile imzalar; OrqLabs META_APP_SECRET ile doğrular.

İzinler#

İşletme doğrulaması ve katmanlar#

• Business verification: Meta Business Suite → Settings → Security Center → Start verification. Belge yüklenir; 2-10 iş günü. Doğrulama olmadan 250 benzersiz alıcı / 24 saat sınırı vardır.
• Display name review: görünen ad işletme adıyla uyumlu olmalıdır.
• App Review gerekmez; kendi hesabınız için standart erişim yeterlidir.
• Mesajlaşma katmanları: doğrulanmış işletme 1.000 alıcı / 24 saat ile başlar; kalite yüksek kaldıkça 10.000 → 100.000 → sınırsız.

Limitler#

Ayrıntı: WhatsApp şablonları ve 24 saat penceresi.

Bağlantıyı test etme#

② Bağlantıyı test et numaranın görünen adını, doğrulama durumunu ve kalite puanını (yeşil / sarı / kırmızı) gösterir. Ardından Gelen Kutusu'ndan numaranıza test mesajı gönderin; pencere kapalıysa onaylı bir şablon gerekir.

Kimlik bilgilerini yenileme#

• System user anahtarı süresizdir; ama system user silinirse, uygulama secret'ı sıfırlanırsa veya izinler kaldırılırsa geçersiz olur. Kart "Yeniden yetkilendirme gerekli" olur.
• Yeni anahtar üretip entegrasyon kartı → Kimlik bilgileri → Güncelle → Permanent Access Token alanına yapıştırın; webhook adresi değişmez.
• Geçici anahtar kullandıysanız 24 saat içinde AUTH hatası alırsınız; kalıcıya geçin.

Sık karşılaşılan hatalar#

Sık sorulan sorular#

Mevcut WhatsApp numaramı kullanabilir miyim? Numara şu an WhatsApp veya WhatsApp Business uygulamasında kayıtlıysa önce o hesabı silmeniz gerekir. Çoğu işletme yeni bir numara alır.

Mesajlaşma ücretli mi? Meta konuşma bazlı ücret alır; OrqLabs yalnızca yapay zekâ maliyetini ölçer. Ayrıntı için Meta fiyat listesine bakın.

Müşteri yazmadan ona mesaj atabilir miyim? Yalnızca onaylı şablonla ve müşterinin önceden onayıyla (opt-in).

Sonraki adım#

• Chatbot kurulumu (WhatsApp + Telegram)
• WhatsApp şablonları ve 24 saat penceresi
• Broadcast kampanyaları ve izin yönetimi