Wiki Detay | wiki workcube

Bu sayfa, Workcube WAI Mesaj Kutusu üzerinden WhatsApp mesajlaşmasını devreye almak için yapılması gerekenleri adım adım anlatır. WhatsApp iki farklı sağlayıcı üzerinden bağlanabilir: Twilio veya Meta (WhatsApp Cloud API). Her şirket için aynı anda yalnızca bir sağlayıcı aktif olabilir.

1. Hangi sağlayıcıyı seçmeliyim?

Konu	Twilio	Meta (Cloud API)
Hızlı test	Sandbox ile birkaç dakikada, Meta hesabı gerekmez	Meta test numarası ile, Meta Business hesabı gerekir
Canlı kullanım	Ücretli (yükseltilmiş) Twilio hesabı ve Meta Business hesabı gerekir	Meta Business hesabı ve WhatsApp'a bağlanacak bir numara gerekir
Maliyet	Meta ücreti + Twilio'nun mesaj başı ek ücreti	Yalnızca Meta ücreti
Aynı hesapta sesli asistan	Evet (Twilio numarası ile)	Hayır (sesli asistan için ayrıca Twilio gerekir)
Instagram DM	Desteklenmez	Aynı Meta uygulaması ile bağlanabilir

2. Ortak ön koşullar

Workcube'e dışarıdan HTTPS ile erişilebiliyor olmalıdır. Twilio ve Meta, mesajları bu adrese gönderir.
Ayarlar WAI Çok Kanallı İletişim (Omnichannel) Ayarları ekranından girilir (settings.omni_channels). Üstteki Şirket seçimi hangi şirket için ayar yaptığınızı belirler.
Mesajlar WAI Mesaj Kutusu ekranında (workspace.meta_inbox) görüntülenir ve cevaplanır. Ekran yeni mesajları birkaç saniyede bir kendiliğinden yeniler; sayfayı yenilemeniz gerekmez.
Webhook adreslerini elle yazmayın. Ayar ekranındaki WhatsApp Webhook URL ve Meta Webhook Callback URL alanlarında sizin alan adınıza göre hazır olarak gösterilir, oradan kopyalayın.
SID, token, App Secret gibi gizli bilgileri e-posta veya sohbet ile paylaşmayın; yalnızca ayar ekranına girin.

A. Twilio ile Kurulum

A1. Twilio hesabı ve kimlik bilgileri

twilio.com üzerinden hesap açın. Deneme (trial) hesabı Sandbox testi için yeterlidir.
Twilio Console ana sayfasındaki Account Info bölümünden Account SID ve Auth Token değerlerini alın (Auth Token için Show).

A2. Sandbox ile test

Twilio Console'da Messaging → Try it out → Send a WhatsApp message sayfasını açın.
Sayfada gösterilen join mesajını, test yapacağınız telefondan Sandbox numarasına (+1 415 523 8886) WhatsApp ile gönderin. Onay mesajı gelmelidir.
Aynı sayfadaki Sandbox settings sekmesinde When a message comes in alanına ayar ekranındaki WhatsApp Webhook URL değerini yazın, yöntem POST olsun ve kaydedin.
Workcube ayar ekranında şu alanları doldurup kaydedin:
- WhatsApp Entegrasyonu Aktif mi?: Evet
- WhatsApp Sağlayıcısı: Twilio
- Twilio Account SID ve Twilio Auth Token: A1 adımındaki değerler
- Twilio WhatsApp Numarası: +14155238886
Telefondan Sandbox numarasına bir mesaj yazın. Mesaj birkaç saniye içinde Mesaj Kutusu'nun WhatsApp sekmesine düşmelidir. Oradan cevap verin; cevap telefona ulaşmalıdır.

Not: Sandbox yalnızca join mesajı göndermiş numaralarla konuşur. Uzun süre işlem yapılmazsa üyelik düşebilir; bu durumda join mesajını tekrar gönderin.
Not: Numarasını gizleyen WhatsApp kullanıcıları Twilio'dan telefon numarası yerine TR.2318… gibi bir kimlikle gelir. Bu normaldir; cevaplar bu kimliğe gönderilir.

A3. Canlı kullanım: onaylı WhatsApp gönderici (Sender)

Twilio hesabını Upgrade ile ücretli hesaba yükseltin (kredi kartı ve bakiye). Deneme hesabı ile gönderici kaydı ve numara alma yapılamaz.
Şirket adına bir Meta Business Portfolio (business.facebook.com) hazır olmalıdır. Kaydı yapacak kişi portföyde tam yetkili yönetici olmalıdır.
Twilio Console'da Messaging → Senders → WhatsApp senders üzerinden gönderici kaydını başlatın. Sihirbaz sizi Meta'ya yönlendirir; Business Portfolio'yu seçin ve izin verin.
WhatsApp'a bağlanacak numarayı belirleyin (Twilio'dan alınan numara ya da size ait bir numara). Numara WhatsApp veya WhatsApp Business uygulamasında kullanılıyorsa önce uygulamadan silinmelidir.
Görünen ad (Display name) girin; marka adınızla uyumlu olmalıdır, Meta onaylar.
Göndericinin ayarlarında gelen mesaj adresine yine WhatsApp Webhook URL değerini POST olarak girin.
Workcube ayar ekranında Twilio WhatsApp Numarası alanını onaylanan numara ile değiştirin (+90… biçiminde).
İşletme doğrulaması (Business Verification) ilk kullanım için şart değildir; mesaj limitlerinin artması ve görünen adın onayı için Meta tarafından istenir.

B. Meta (WhatsApp Cloud API) ile Kurulum

B1. Ön koşullar

Şirket adına bir Meta Business Portfolio ve portföyde tam yetkili yönetici olan bir Facebook hesabı.
Bu hesapla developers.facebook.com üzerinde bir kez geliştirici kaydı (telefon doğrulaması istenebilir).

B2. Uygulamayı oluşturma

developers.facebook.com → My Apps → Create App.
Uygulama adı ve e-posta girin (örnek: Workcube WAI).
Kullanım senaryosu olarak Connect with customers through WhatsApp seçin.
Şirketin Business Portfolio'sunu seçin ve Create app ile tamamlayın.

B3. Numara ve kimlikler

Uygulama panelinde WhatsApp → API Setup sayfasını açın. Meta, test için ücretsiz bir test numarası ve test WhatsApp Business hesabı oluşturur.
Şu değerleri not alın:
- Phone number ID → ayar ekranındaki WhatsApp Phone Number ID
- WhatsApp Business Account ID → ayar ekranındaki WhatsApp Business Account ID (WABA ID)
Test numarası kullanıyorsanız To → Manage phone number list ile test yapacağınız telefonları ekleyin (en fazla 5 numara) ve WhatsApp'a gelen kodla doğrulayın.
Canlı kullanım için aynı sayfadan Add phone number ile kendi numaranızı ekleyin. Numara WhatsApp uygulamasında kullanılıyorsa önce silinmelidir. Doğrulama kodu SMS veya sesli arama ile gelir; sabit hat da kullanılabilir.

B4. App Secret

App settings → Basic sayfasında App secret yanındaki Show düğmesine basın (Facebook şifreniz istenir).
Değeri ayar ekranındaki Meta App Secret alanına girin. Aynı sayfadaki App ID değeri de Meta App ID alanına girilir.

B5. Kalıcı erişim anahtarı (System User token)

API Setup sayfasındaki geçici token 24 saat sonra geçersiz olur. Kalıcı token şöyle alınır:

business.facebook.com → Ayarlar → Kullanıcılar → Sistem kullanıcıları → Ekle. Ad örneğin workcube-wai, rol Yönetici (Admin).
Sistem kullanıcısını seçip Varlık ata (Assign assets):
- Uygulamalar: oluşturduğunuz uygulama, tam yetki
- WhatsApp hesapları: B3'teki WhatsApp Business hesabı, tam yetki
Yeni token oluştur (Generate new token): uygulamanızı seçin, süre Hiçbir zaman (Never), izinler whatsapp_business_messaging ve whatsapp_business_management.
Token bir daha gösterilmez; hemen ayar ekranındaki Meta Access Token (System User) alanına girin.

B6. Workcube ayarları (webhook'tan ÖNCE)

Aşağıdaki alanları doldurup kaydedin. Webhook doğrulaması bu ayarlara bakar; kaydetmeden B7'ye geçerseniz doğrulama başarısız olur.

WhatsApp Entegrasyonu Aktif mi?: Evet
WhatsApp Sağlayıcısı: Meta (WhatsApp Cloud API)
Meta App ID, Meta App Secret
Meta Access Token (System User)
WhatsApp Phone Number ID, WhatsApp Business Account ID (WABA ID)
Görünen WhatsApp Telefon Numarası (bilgi amaçlı)
Webhook Verify Token: kendi belirlediğiniz uzun, rastgele bir metin (B7'de aynısı girilecek)

B7. Webhook

Uygulama panelinde WhatsApp → Configuration → Webhook → Edit.
Callback URL: ayar ekranındaki Meta Webhook Callback URL değeri.
Verify token: B6'da girdiğiniz Webhook Verify Token ile birebir aynı.
Verify and save. Başarılı olmalıdır.
Webhook fields listesinde messages satırına Subscribe deyin.

B8. Test

Kayıtlı telefondan WhatsApp numaranıza (test numarası veya kendi numaranız) bir mesaj yazın.
Mesaj birkaç saniye içinde Mesaj Kutusu'nun WhatsApp sekmesine düşmelidir.
Oradan cevap yazın; cevap telefona ulaşmalıdır.

C. Sağlayıcı Değiştirme ve Kurallar

Sağlayıcı, ayar ekranındaki WhatsApp Sağlayıcısı alanından değiştirilir. Aynı anda tek sağlayıcı aktiftir.
Aynı kişi Twilio'dan ve Meta'dan farklı kimliklerle gelir (Twilio'da TR.… ya da numara, Meta'da numara). Bu nedenle Mesaj Kutusu'nda aynı kişi için iki ayrı konuşma görünebilir.
Bir konuşma aktif olmayan sağlayıcı üzerinden geldiyse sistem cevap göndermez ve "Bu konuşma X üzerinden geldi, ancak aktif WhatsApp sağlayıcısı Y" uyarısını gösterir. Cevap vermek için sağlayıcıyı o konuşmanın geldiği sağlayıcıya çevirin ya da kişinin aktif numaraya yeniden yazmasını bekleyin.
24 saat kuralı: Müşterinin son mesajından sonraki 24 saat içinde serbest metinle cevap verilebilir. Bu süre dolduktan sonra veya konuşmayı sizin başlatmanız gerektiğinde yalnızca Meta onaylı mesaj şablonları gönderilebilir.
WhatsApp API'si yalnızca birebir konuşmaları destekler. Telefondaki mevcut WhatsApp grupları Workcube'e alınamaz.
Gelen mesajlarda WAI Analiz düğmesi ile mesajın niyeti, aciliyeti ve önerilen ERP aksiyonu çıkarılır. Mesajların yanındaki kutucuklarla belirli mesajlar seçilirse analiz yalnızca seçilen mesajlar üzerinden yapılır.

D. Kontrol Listesi

☐ Ayar ekranında doğru Şirket seçili
☐ WhatsApp Entegrasyonu Aktif mi? = Evet
☐ WhatsApp Sağlayıcısı doğru seçili
☐ Sağlayıcının tüm zorunlu alanları dolu (Mesaj Kutusu eksik alanları listeler)
☐ Webhook adresi Twilio / Meta paneline ayar ekranından kopyalanarak girildi
☐ (Meta) Webhook doğrulandı ve messages alanına abone olundu
☐ Test telefonundan gelen mesaj Mesaj Kutusu'na düştü
☐ Mesaj Kutusu'ndan gönderilen cevap telefona ulaştı

E. Sık Karşılaşılan Sorunlar

Belirti	Olası sebep	Çözüm
Twilio: 11200, HTTP 500, "Cookie name $Version is a reserved token"	Sunucu, Twilio'nun geri gönderdiği eski biçimli çerezi reddediyor	Sunucuda Tomcat çerez filtresi (DollarCookieFilter) kurulu olmalı; sistem yöneticisine iletin
Twilio: HTTP 403, mesaj Mesaj Kutusu'na düşmüyor	İmza doğrulanamadı: Auth Token yanlış ya da Twilio'daki webhook adresi ayar ekranındakiyle birebir aynı değil	Auth Token'ı yeniden girin; webhook adresini ayar ekranından kopyalayın (https, aynı alan adı, sonunda boşluk yok)
Twilio: 21211 "The 'To' number … is not a valid phone number"	Alıcı kimliği bozuk (eski kayıtlarda TR. öneki silinmiş olabilir)	Kişinin yeni mesajıyla açılan konuşmadan cevap verin
Twilio: 63015 "Channel Sandbox can only send messages to phone numbers that have joined the Sandbox"	Alıcı Sandbox'a katılmamış ya da konuşma Meta'dan gelmiş	Telefondan join mesajını tekrar gönderin; konuşma Meta'dan geldiyse sağlayıcıyı Meta yapın
Meta: Verify and save başarısız	Verify Token eşleşmiyor ya da ayarlar kaydedilmedi	Önce ayar ekranını kaydedin, token'ı birebir aynı girin
Meta: mesajlar gelmiyor	messages aboneliği yok, Phone Number ID veya App Secret yanlış	Webhook fields'da messages aboneliğini kontrol edin; Phone Number ID ve App Secret'ı yeniden girin
Meta: gönderim bir gün sonra durdu	Geçici token kullanılmış, süresi doldu	B5 adımıyla kalıcı System User token alın
Meta: 131047 / "Re-engagement message"	24 saatlik pencere dolmuş	Müşterinin yeniden yazmasını bekleyin ya da onaylı şablon kullanın
"Bu konuşma X üzerinden geldi, ancak aktif WhatsApp sağlayıcısı Y"	Konuşma, aktif olmayan sağlayıcıdan gelmiş	Bölüm C'ye bakın
Mesaj Kutusu'nda "henüz kullanıma hazır değil" uyarısı	Seçili sağlayıcının zorunlu alanlarından biri boş	Uyarıda listelenen alanları ayar ekranında doldurun

Geri Bildirim

Bu içeriği faydalı buldunuz mu?

Geri Bildirimizi Lütfen Yazınız!

Ad*

Soyad*

E-posta *