WhatsApp Business API CRM Entegrasyonu: Teknik Rehber (2026)

WhatsApp Business API, müşterilerle doğrudan iletişim kurmak için güçlü bir kanal sunar. Ancak bu kanalı CRM sisteminizden bağımsız işlettiğinizde iki temel sorunla karşılaşırsınız: müşteri geçmişi bölünür ve takip edilemeyen konuşmalar satış fırsatına dönüşemez.

Bir müşteri WhatsApp'tan satın alma sorusu sorduğunda bu konuşma CRM'deki hesabıyla ilişkilendirilmezse, temsilci değişiminde bilgi sıfırlanır. Takip eden mesaj şablonu zamanında gönderilemez; lider nitelikli bir konuşma kayıt dışı kalır. Entegrasyon, tam olarak bu kopukluğu giderir.

Meta'nın WhatsApp Business Platform'u (eski adıyla Business API), ticari mesajlaşma altyapısını doğrudan iş sistemlerine bağlamak için tasarlanmıştır. 2026 itibarıyla BSP (Business Solution Provider) iş ortaklarının büyük çoğunluğu CRM entegrasyonu için standart webhook desteği sunuyor. Bu rehber, teknik mimariden KVKK uyumuna kadar üç farklı entegrasyon yolunu karşılaştırır.

Teknik entegrasyona geçmeden önce platformun kurallarını anlamak gerekir; çünkü bu kurallar sistem tasarımını doğrudan etkiler.

24 Saatlik Mesajlaşma Penceresi: Bir müşteri size mesaj gönderdiğinde 24 saatlik bir "oturum" başlar. Bu pencere içinde herhangi bir içerik gönderebilirsiniz. Pencere dolduktan sonra yalnızca Meta onaylı şablon mesajlar (HSM — Highly Structured Messages) kullanılabilir. Şablon mesajlar önceden Meta'nın onayına tabi tutulur ve belirli bir ücret kategorisine (marketing, utility, authentication, service) göre faturalandırılır.

İnsan Temsilci Etiketi (Human Agent Tag): Otomatik yanıt akışlarında, bir AI ajanı veya bot konuşmayı yönetiyorsa bu durum kullanıcıya açık olmalıdır. Meta'nın politikası, tamamen otomatik akışlarda belirli içerik türlerini kısıtlar ve müşterinin gerçek bir insanla bağlantı kurma talebini reddeden sistemlere izin vermez. CRM entegrasyonunuzun bu kuralı teknik olarak uygulaması, yani bot'un canlı temsilciye devir yeteneğine sahip olması zorunludur.

Bu iki kural, entegrasyon mimarinizde `session_expires_at` alanını takip eden bir zamanlayıcı ve `is_human_handoff` bayrağı gerektiren bir iş akışı tasarımına yol açar.

Ne Zaman Kullanılır? Kullandığınız CRM (Salesforce, HubSpot, Zoho, Freshdesk vb.) zaten Meta onaylı bir WhatsApp entegrasyon paketi sunuyorsa bu yol en hızlı başlangıçtır.

Nasıl Çalışır? CRM'in marketplace veya entegrasyon panelinden Meta uygulamasını aktif edersiniz. Phone Number ID ve kalıcı erişim token'ınızı girdinizde, CRM otomatik olarak bir webhook endpoint oluşturur ve bunu Meta'ya kaydeder. Gelen WhatsApp mesajları doğrudan CRM içinde bilet veya konuşma kaydına dönüşür.

Kurulum Karmaşıklığı: Düşük. Ortalama kurulum süresi 30 dakika ile 2 saat arasındadır. Yazılım geliştirme gerektirmez.

Sınırlamalar: - Veri akışı ve alan eşleme tamamen CRM'in belirlediği şemaya bağlıdır; özel alanlar desteklenmeyebilir. - Karmaşık iş akışları (ajanlar arası devir, koşullu şablon seçimi) native connector'da kısıtlı kalır. - İki farklı CRM arasında mesaj geçmişini senkronize etmek için genellikle ek geliştirme gerekir.

Veri Senkronu Güvenliği: CRM vendor'ının güvenlik altyapısına bağımlısınız. Token rotasyonu ve webhook imzası doğrulaması CRM tarafından yönetilir, ancak denetimi doğrulamak güçtür.

Bu yöntem, tam kontrol isteyen ve özel iş akışı kurmak isteyen ekipler için en çok tercih edilen yaklaşımdır.

Teknik Mimari:

``` Meta Cloud API → POST /webhook (HMAC-SHA256 imzalı) → Middleware (Node.js / Python) → Doğrulama + dönüşüm → CRM REST API → Lead kaydı güncelleme → Temsilci notu oluşturma ```

Adım Adım Kurulum:

1. Meta Developer Console'da bir uygulama oluşturun ve WhatsApp ürününü ekleyin. `WABA_ID` ve `Phone Number ID` değerlerini not alın. 2. Webhook endpoint'inizi HTTPS üzerinden yayınlayın. Meta bu endpoint'e doğrulama amacıyla `GET` isteği atar; `hub.verify_token` değerinizi döndürmeniz gerekir. 3. Her gelen mesaj için imzayı doğrulayın: `X-Hub-Signature-256` başlığındaki değeri kendi `APP_SECRET` ile hesapladığınız HMAC-SHA256 ile karşılaştırın. Eşleşmiyorsa 403 döndürün. 4. Mesaj nesnesini ayrıştırın: `entry[0].changes[0].value.messages[0]` yolunda `id` (conversation ID), `from` (telefon numarası), `timestamp` ve `text.body` veya `type` (media, interactive vb.) bulunur. 5. CRM API'sine `PATCH /contacts/{crm_contact_id}` veya `POST /notes` isteği atın. `wa_conversation_id` alanını custom field olarak eşleyin.

Conversation ID → Lead Kaydı → Temsilci Notu Zinciri:

• `wamid` (WhatsApp Message ID) ve `conversation_id` her mesajda gelir. Bu iki alan, aynı konuşmaya ait mesajları gruplamanızı sağlar.
• Middleware, telefon numarasını CRM'de arar. Eşleşme varsa mevcut lead kaydına not olarak ekler; eşleşme yoksa yeni bir lead oluşturur ve kaydeder (`source: whatsapp`, `channel_type: inbound`).
• Temsilci atama: Middleware'de round-robin veya beceri bazlı atama mantığı kurabilirsiniz. CRM'e `owner_id` alanını güncelleyen bir `PATCH` isteği yeterlidir.

Kurulum Karmaşıklığı: Orta. En az bir backend geliştirici gerektirir. Ancak özelleştirme kapasitesi çok yüksektir.

Veri Senkronu Güvenliği: - Webhook imzası zorunlu doğrulayın. - Token'ları environment variable'larla yönetin, kaynak koduna gömmekten kaçının. - Yeniden deneme (retry) mantığı ekleyin: Meta webhook başarısız olursa yeniden dener, middleware'inizin idempotent olması gerekir (`wamid` üzerinden tekrar işlemi önleyin). - İletim sırasında TLS 1.2+ zorunlu; depolanan mesaj içeriği şifrelenmiş olmalı.

WhatsApp, Instagram DM, Telegram ve web chat gibi kanalları tek panelde yönetmek istiyorsanız omnichannel bir platform katmanı kullanmak, hem teknik yükü hem de sürekli bakım maliyetini düşürür.

Nasıl Çalışır? Platform, Meta ile BSP (Business Solution Provider) ilişkisini yönetir. Siz sadece platformun CRM entegrasyonunu yapılandırırsınız. Platform → CRM bağlantısı genellikle OAuth veya API anahtarıyla 10-15 dakikada kurulur. Conversation routing, temsilci havuzu, SLA zamanlayıcı ve şablon yönetimi platform tarafından sağlanır.

CRM Entegrasyonu Akışı: - Platform gelen mesajı alır ve kendi veri tabanında conversation_id'yi saklar. - Yapılandırdığınız kural (örn. telefon numarası eşleşmesi) tetiklendiğinde CRM'e webhook veya API çağrısı gönderir. - CRM tarafında lead/contact güncellemesi ve aktivite logu otomatik oluşur.

Avantajları: - Düşük teknik yük: Yazılım geliştirme gerekmeyebilir. - Yerleşik şablon yönetimi ve 24 saatlik pencere izleme. - İnsan temsilci devri kuralları platform düzeyinde zorunlu tutulur.

Dezavantajları: - Platform vendor'ına bağımlılık artar. - Aylık platform ücreti ek maliyet oluşturur. - Çok spesifik CRM özelleştirmeleri için yine custom geliştirme gerekebilir.

Kontroljet ekosistemi içinde omnichannel müşteri hizmetleri kurulumunu daha geniş bir perspektifle inceleyebilirsiniz.

| Kriter | Native Connector | Webhook + Middleware | Omnichannel Platform | |---|---|---|---| | Kurulum süresi | 30 dk – 2 saat | 1 – 3 gün | 1 – 4 saat | | Teknik yetenek gerekliliği | Düşük | Orta – Yüksek | Düşük | | Özelleştirme | Kısıtlı | Yüksek | Orta | | Bakım yükü | Düşük | Orta | Düşük | | Maliyet yapısı | CRM lisans dahili | Sunucu + geliştirici | Platform ücreti | | 24 saat pencere yönetimi | Otomatik | Manuel kodlama | Otomatik | | Çoklu kanal desteği | Genellikle hayır | Evet (tasarım ister) | Evet |

Hangi yöntemi seçmeli? 100'den az günlük konuşma, tek bir CRM ve minimal özelleştirme ihtiyacı olan ekipler için native connector yeterlidir. Karmaşık iş akışları, birden fazla CRM veya özel veri dönüşümü gerektiren senaryolarda webhook + middleware daha sürdürülebilirdir. Kanal sayısını büyütme planı olan ve teknik ekip yatırımı yapmak istemeyen işletmelere omnichannel platform daha mantıklı bir başlangıç noktasıdır.

WhatsApp şablon mesaj fiyatlandırması ve kategori hesabı konusunda ayrıntılı bilgi için WhatsApp Business API fiyatları ve kategori hesabı yazısına bakabilirsiniz.

WhatsApp üzerinden iletilen her mesaj, Kişisel Verilerin Korunması Kanunu (KVKK, 6698 sayılı Kanun) kapsamında kişisel veridir. Telefon numarası, mesaj içeriği ve zaman damgası bu kapsamdadır. CRM entegrasyonu kurduğunuzda bu verilerin işlenme ve aktarım zincirini belgelemeniz gerekir.

Açık Rıza: WhatsApp üzerinden kişisel veri içeren mesajların CRM'e aktarılması için Kanun'un 5. maddesi kapsamında açık rıza veya meşru menfaat gibi hukuki dayanak bulunmalıdır. Müşteriyle iletişime geçmeden önce aydınlatma metni sunmak ve rızayı kayıt altına almak zorunludur.

Veri Minimizasyonu: CRM'e aktarılan veri, amacın gerektirdiğinden fazla olmamalıdır. Örneğin pazarlama amacı yoksa tüm konuşma geçmişini süresiz saklamak orantılılık ilkesini ihlal edebilir.

Yurt Dışı Aktarım: Meta'nın altyapısı AB veri merkezleri kullanmakla birlikte, Meta Ireland ile Türkiye Kişisel Verileri Koruma Kurumu (KVKK Kurulu) arasında standart sözleşme maddeleri veya bağlayıcı kurumsal kural mekanizması çerçevesinde uygun güvence bulunması gerekir. Kullandığınız BSP'nin veri işleyici sözleşmesini inceleyip imzalamanız önerilir.

Veri Saklama Süresi: Saklama politikasını CRM ayarlarında tanımlayın. Müşteri ilişkisi sonlandığında mesaj geçmişinin silinmesi veya anonim hale getirilmesi için otomatik bir süreç kurun.

Denetim İzi: Entegrasyon katmanında her veri işleme eylemini (mesaj alındı, CRM'e yazıldı, temsilciye atandı) zaman damgasıyla loglayın. KVKK Kurulu denetiminde bu log'lar temel kanıt niteliğindedir.

Entegrasyonunuzu canlıya almadan önce aşağıdaki kontrol adımlarını uygulayın:

1. Webhook Doğrulama Testi Meta'nın Graph API test aracından veya `curl` ile webhook endpoint'inize GET isteği atın. `hub.challenge` değerini doğru döndürdüğünüzü onaylayın.

2. Mesaj Teslim Testi Test WhatsApp numarasından (Meta Developer Console'da tanımlayabileceğiniz) bir mesaj gönderin. Middleware'inizin mesajı aldığını, HMAC imzasını doğruladığını ve CRM'e yazdığını log'lardan izleyin.

3. 24 Saat Pencere Simülasyonu Oturumun sona ermesini beklemeden şablon mesaj gönderimini test edin. Açık oturumda serbest metin, kapalı oturumda yalnızca onaylı şablon kullanıldığını doğrulayın.

4. İnsan Devri Akışı Testi Botun "canlı temsilci isteği" mesajını algılayıp algılamadığını ve temsilciyi doğru atayıp atamadığını test edin. CRM'de `handoff_requested_at` alanının güncellendiğini kontrol edin.

5. Yük Testi Günlük beklenen mesaj hacminin 3 katı yükle kısa bir test yapın. Webhook kuyruğu gecikmesi ve CRM API rate limit tepkisini gözlemleyin.

6. KVKK Denetim İzi Kontrolü Her test mesajı için log'un `wa_message_id`, `contact_phone_hash`, `crm_record_id`, `processed_at` alanlarını içerdiğini doğrulayın.

Ekibinizin müşteri mesajlarını tek panelden yönetme deneyimi ve bot-temsilci devri akışı hakkında sektörler sayfamızdan kendi kullanım senaryonuza uygun kaynağa ulaşabilirsiniz.