HubSpot CRM

HubSpot CRM Entegrasyonu, müşteri iletişiminin ve çok kanallı desteğin yönetildiği Supsis ile kurumsal pazarlama, satış ve destek süreçlerinin yürütüldüğü HubSpot CRM arasında iki yönlü, güvenli ve gerçek zamanlı bir veri köprüsü kurar. Bu entegrasyon sayesinde WhatsApp, Instagram, Canlı Sohbet (WebChat) veya diğer iletişim kanallarından gelen yeni müşteriler, belirlenen kurallara ve aktarım modlarına göre HubSpot'ta otomatik olarak kişi (contact) ve satış fırsatı (deal) olarak oluşturulabilir.

Entegrasyon, karmaşık OAuth izin pencerelerine ihtiyaç duymadan doğrudan Access Token ile kurulur. Kullanım senaryosuna bağlı olarak hızlı başlangıç için Service Key veya otomasyon olaylarını (webhook) destekleyen tam özellikli Private App yöntemlerinden biri tercih edilebilir. Canlı destek temsilcileri sohbet ekranından ayrılmadan müşterinin HubSpot kişi, anlaşma, şirket ve aktivite verilerini tek bakışta inceleyebilir; yeni notlar ve görevler ekleyebilir. Ayrıca HubSpot tarafında gerçekleşen kişi veya anlaşma güncellemeleri Supsis otomasyonlarını anlık olarak tetikleyebilir.

1- HubSpot CRM Entegrasyonuna Genel Bakış

1.a – HubSpot CRM Nedir ve Entegrasyonun Amacı

HubSpot; satış, pazarlama, müşteri hizmetleri ve operasyon ekiplerinin kişi (contact), anlaşma (deal), şirket (company), destek talebi (ticket) ve aktiviteleri tek bir merkezi veritabanında toplamasını sağlayan bulut tabanlı bir CRM platformudur.

İşletmeler genellikle çok kanallı müşteri desteğini Supsis üzerinden yürütürken, satış süreçlerini ve müşteri yaşam döngüsünü HubSpot üzerinde takip eder. Entegrasyon sağlanmadığında temsilciler mesajlaşma ekranı ile CRM sekmesi arasında sürekli geçiş yapmak, müşteri bilgilerini kopyalayıp yapıştırmak ve her yeni görüşmeyi elle CRM'e girmek zorunda kalır. Bu durum zaman kaybına, veri tutarsızlıklarına ve takipsiz kalan potansiyel satış fırsatlarına yol açar.

Supsis HubSpot CRM Entegrasyonu bu iki dünya arasında iki yönlü kesintisiz bir akış sağlar:

1. Supsis → HubSpot (Veri Aktarımı): WhatsApp, Instagram veya WebChat üzerinden yeni bir müşteri mesaj attığında, telefon ve e-posta mükerrer araması yapılır; mevcut bir kayıt yoksa HubSpot'ta otomatik kişi (contact) veya kişi + anlaşma (deal) oluşturulur.
2. HubSpot → Supsis (Sohbet Ekranı Görünümü): Canlı destek ekranında sağ taraftaki müşteri panelinde HubSpot sekmesi açılır. Müşteriye ait iletişim bilgileri, açık/kapalı anlaşmalar, bağlı şirket ve görevler anında listelenir. Temsilci sohbetten çıkmadan HubSpot kaydını görüntüleyebilir ve deal'e not ekleyebilir.
3. HubSpot Olayları → Supsis Otomasyonları (Webhook): Private App altyapısı sayesinde HubSpot'ta bir anlaşmanın aşaması değiştiğinde (örneğin "Closed Won" olduğunda), kişi silindiğinde veya şirket güncellendiğinde Supsis otomasyonları tetiklenir ve müşteriye WhatsApp/SMS üzerinden anlık bildirimler gönderilebilir.

1.b – İki Katmanlı Yapılandırma Mimarisi

HubSpot CRM entegrasyonu iki temel katmandan meydana gelir:

1.c – Terimler Sözlüğü

HubSpot entegrasyon arayüzlerinde ve teknik süreçlerde kullanılan temel kavramlar aşağıdaki tabloda açıklanmıştır:

2- Bağlantı Yöntemleri: Service Key vs. Private App

Supsis HubSpot CRM entegrasyonunda standart OAuth onay penceresi bulunmaz. Kullanıcı, HubSpot panelinden aldığı Access Token'ı Supsis arayüzüne yapıştırarak bağlantıyı sağlar. İhtiyacınıza göre iki farklı bağlantı modelinden birini seçebilirsiniz:

3- Gerekli İzinler (Scopes)

Her iki bağlantı yönteminde de Access Token oluşturulurken aşağıdaki scope'ların (izinlerin) eksiksiz işaretlenmesi zorunludur. Eksik bir izinle bağlanmaya çalışıldığında Supsis bağlantıyı reddeder ve hangi iznin eksik olduğunu hata mesajında bildirir:

• crm.objects.contacts.read – Kişileri okuma yetkisi
• crm.objects.contacts.write – Yeni kişi oluşturma ve güncelleme yetkisi
• crm.objects.deals.read – Satış fırsatlarını okuma yetkisi
• crm.objects.deals.write – Satış fırsatı oluşturma ve güncelleme yetkisi
• crm.objects.owners.read – HubSpot kullanıcılarını ve temsilcilerini okuma yetkisi
• crm.objects.companies.read – Bağlı şirket bilgilerini okuma yetkisi
• crm.schemas.contacts.read – Kişi alan şemalarını listeleme yetkisi
• crm.schemas.deals.read – Anlaşma alan şemalarını listeleme yetkisi
• crm.schemas.companies.read – Şirket alan şemalarını listeleme yetkisi

4- Kurulum Adımları

4.a – Entegrasyon Kartına Erişim

1. Supsis yönetim paneline giriş yapın ve sol ana menüden Entegrasyonlar sayfasına tıklayın.
2. Sayfadaki CRM kategorisi altında yeşil ● ÜCRETSİZ rozetine sahip HubSpot CRM kartını bulun.
3. Karta tıklayarak HubSpot CRM Kanalları listesine geçiş yapın.

4.b – Yöntem 1: Private App ile Tam Kurulum (Önerilen)

Otomasyon tetikleyicileri, webhook bildirimleri ve tam kapsamlı CRM yönetimi için Private App kurulum adımları şöyledir:

1. HubSpot'ta Private Apps Alanına Gidin: HubSpot hesabınızda sağ üstteki dişli çark simgesine (Settings) tıklayın. Sol menüden Integrations → Private Apps yolunu izleyin.

2. Uygulamayı Başlatın: Create legacy app (veya Create a private app) butonuna tıklayın ve açılan modalda Private seçeneğini işaretleyin.

3. Temel Bilgileri Tanımlayın (Basic Info): Uygulama adı olarak Supsis AI Entegrasyonu yazın. İsteğe bağlı olarak açıklama ve Supsis logosu ekleyin.

4. Scope (İzinleri) Ekleyin: Scopes sekmesine geçin. Bölüm 3'te listelenen tüm Contact, Deal, Owner, Company ve Schema izinlerini aratarak tek tek işaretleyin. Sayfa özetinde (Summary) seçilen tüm izinleri doğrulayın.

5. Uygulamayı Oluşturun ve Token'ı Alın: Sağ üstteki Create app butonuna basıp gelen onay ekranında Continue creating seçeneğini onaylayın.

6. Açılan pencerede Access Token değerini kopyalayın (pat-na1-...).

7. Auth sekmesinden webhook güvenliği için Client Secret değerini kopyalayın.

8. Supsis'e Bağlayın: Supsis panelindeki Kanal Ekle modalına dönün. Kanal adını girin, Access Token ve Client Secret alanlarını yapıştırıp Bağlan butonuna tıklayın.

4.c – Yöntem 2: Service Key ile Hızlı Kurulum

Yalnızca sohbet içi müşteri görüntüleme ve yeni kişileri HubSpot'a aktarma ihtiyacınız varsa, uygulama oluşturmadan saniyeler içinde Service Key ile bağlanabilirsiniz:

1. Service Keys Alanına Gidin: HubSpot hesabınızda Settings → Integrations → Service Keys (veya bazı hesaplarda Development → Keys → Service Keys) menüsünü açın (Bkz: Yukarıdaki Entegrasyonlar Ayarlar Ekranı).
2. Yeni Anahtar Oluşturun: Create Service Key butonuna basın. Açılan panelde anahtara bir isim verin.
3. Gerekli Scope'ları Tanımlayın: Bölüm 3'te belirtilen okuma/yazma scope'larını seçin ve özet listesini onaylayın.
4. Token'ı Kopyalayın: Üretilen Access Token'ı kopyalayın.
5. Supsis'te Kanalı Oluşturun: Supsis panelinde Kanal Ekle modalını açın, kopyaladığınız token'ı yapıştırın ve Bağlan butonuna basın.

5- İletişim Kanallarından Veri Aktarımı (CRM Forward)

5.a – Aktarımın Yapılandırılması

HubSpot kanalı kurulduktan sonra, müşteri görüşmelerinin yapıldığı kaynak iletişim kanallarında (örneğin WhatsApp veya WebChat) aktarım mekanizması açılmalıdır:

1. Supsis panelinde Ayarlar > Kanallar veya sol menüden ilgili kanalın detayına gidin (Örn: WhatsApp Kanalları → Kanal Detayı).
2. Kanal ayarlarında CRM / HubSpot sekmesini açın.
3. Yeni kişileri HubSpot'a aktar anahtarını aktif hale getirin.

5.b – Aktarım Modları ve Parametreler

Aktarım sekmesinde aşağıdaki kritik ayarlar yapılandırılır:

1. Aktarım Modu (Forward Mode):
2. Contact (Yalnızca Kişi): Gelen müşteri için HubSpot'ta yalnızca kişi kaydı oluşturulur.
3. Contact + Deal (Kişi + Anlaşma): Müşteri için hem kişi hem de yeni bir satış anlaşması açılır; anlaşma otomatik olarak ilgili kişiye bağlanır (Association). Bu mod seçildiğinde Pipeline (Satış Hunisi) ve Deal Stage (Aşama) alanlarının seçilmesi zorunludur.
4. Yaşam Döngüsü Aşaması (Lifecycle Stage): HubSpot varsayılan yapısında bağımsız bir "Lead" nesnesi barındırmaz. Supsis'te müşteri adayı tanımlamak için kişi üzerindeki Lifecycle Stage kullanılır. Seçilebilecek değerler:
5. lead (Varsayılan)
6. subscriber
7. marketingqualifiedlead (MQL)
8. salesqualifiedlead (SQL)
9. opportunity
10. customer
11. evangelist
12. other
13. Telefon Formatı:
14. E.164 (+ ile): +905xxxxxxxxx
15. Artısız: 905xxxxxxxxx (HubSpot aramasında phone, mobilephone ve normalize edilmiş telefon alanları eşzamanlı taranır).
16. Varsayılan Kayıt Sahibi (Owner): Yeni açılan kayıtların HubSpot tarafındaki varsayılan temsilcisini belirler. Boş bırakılırsa HubSpot varsayılan kullanıcısı atanır.
17. Özel Alan Eşlemesi (Field Mapping): Supsis kişi ve oturum parametrelerini HubSpot özel alanlarına dinamik şablonlarla aktarabilirsiniz. Örnek: {{contact.phone}}, {{contact.name}}.

5.c – Mükerrer Kayıt Önleme (Dedup) Mantığı

Müşterinin her mesajında yeni bir kişi kaydı açılarak CRM veritabanının kirlenmesi engellenir:

6- Canlı Destek Sohbet Ekranında HubSpot Widget'ı

HubSpot entegrasyonu aktif olduğunda canlı destek temsilcileri için sohbet ekranında güçlü bir CRM paneli açılır:

1. Erişim: Canlı sohbet ekranında sağ tarafta yer alan müşteri bilgi alanında HubSpot sekmesine tıklanır.
2. Kişiler (Contacts) Sekmesi: Müşterinin adı, unvanı, e-postası, telefonu, yaşam döngüsü ve kayıt sahibi listelenir. "HubSpot'ta Görüntüle" butonu ile doğrudan HubSpot'taki ilgili kayda tek tıkla gidilebilir.
3. Anlaşmalar (Deals) Sekmesi: Müşteriye bağlı tüm aktif ve kapalı anlaşmalar, aşama bilgisi, tutar ve tahmini kapanış tarihiyle görüntülenir. Temsilciler bu ekran üzerinden anlaşmaya anında yeni notlar ekleyebilir.
4. Şirketler (Companies) Sekmesi: Kişinin bağlı olduğu firma bilgileri salt okunur olarak incelenir.
5. Aktiviteler (Activities) Sekmesi: Kişiyle ilişkili görevler (task) ve geçmiş iletişim adımları takip edilir.

7- Kullanıcı Eşlemesi ve Görünürlük

7.a – Kullanıcı Eşlemesi (User Mapping)

Kanal detayında yer alan Kullanıcı eşlemesi sekmesi, Supsis panelindeki canlı destek temsilcileri ile HubSpot kayıt sahiplerini (Owners) e-posta adresleri üzerinden eşleştirir:

• Temsilci sohbet ekranında kaydın sahibini değiştirdiğinde bu eşleme tablosu referans alınır.
• HubSpot'ta ilgili personele atanmış bir contact veya deal oluştuğunda Supsis tarafında doğru temsilciye bildirim iletilebilir.

7.b – Görünürlük (Visibility)

HubSpot CRM kanalını ve sohbet içi widget verilerini hangi departman ve personellerin görebileceği Görünürlük sekmesinden belirlenir. Yalnızca yetkilendirilen ekipler CRM verilerine erişebilir.

8- Webhook Kurulumu ve Otomasyon Tetikleyicileri

Private App yöntemiyle bağlanan hesaplarda HubSpot tarafında gerçekleşen olaylar Supsis otomasyonlarını tetikleyebilir.

8.a – Webhook Kurulum Adımları

1. Supsis panelinde Entegrasyonlar > HubSpot CRM > Kanal Detayı > Webhooks sekmesine gidin.
2. Ekranda size özel üretilen Target URL adresini kopyalayın. (Biçim: https://socket.supsis.live/webhook/hubspot/{siteId}/{channelId})
3. HubSpot Private App panelinizde Webhooks sekmesini açın ve kopyaladığınız Target URL'i yapıştırın.
4. Event subscriptions (Olay Abonelikleri) alanından aşağıdaki önerilen abonelikleri ekleyin:
5. contact.creation, contact.propertyChange, contact.deletion
6. deal.creation, deal.propertyChange, deal.deletion
7. company.creation, company.propertyChange
8. ticket.creation
9. HubSpot'ta ayarları kaydedin.
10. Private App'in Auth sekmesinden Client Secret anahtarını kopyalayın ve Supsis kanalınızın Detay sekmesine yapıştırıp kaydedin.

8.b – Otomasyon Tetikleyici Olayları (Triggers)

Supsis Otomasyon Sihirbazı tetikleyici menüsünde HubSpot modülü altında 10 farklı olay bulunur:

9- Supsis Otomasyon Tasarımcısı ve Aksiyon Blokları

Otomasyon akış tasarımcısının sol paletinde yer alan turuncu renkli HubSpot Actions kategorisinde 4 adet hazır aksiyon bloğu sunulmaktadır:

1. HubSpot Telefon ile Kişi Bul: Müşterinin telefon numarasını aratarak HubSpot Contact ID'sini çeker. Sonraki bloklarda kişi kimliği üzerinden işlem yapılmasını sağlar.
2. HubSpot Kayıt Oluştur: Belirlenen parametrelerle Contact, Deal, Note, Task veya Ticket nesnesi oluşturur. Alanlar HubSpot şemasından dinamik olarak seçilir.
3. HubSpot Kayıt Güncelle: Mevcut bir kaydın özelliklerini (sahip değişimi, aşama güncellemesi vb.) düzenler.
4. HubSpot Not Ekle: İlgili kişi veya anlaşmanın zaman çizelgesine anında zengin metin formatında not iliştirir.

9.a – JavaScript SDK ve Kod Blokları

Chatbot ve Otomasyon kod bloklarında supsis.hubspot nesnesi üzerinden özel operasyonlar yürütülebilir:

// Örnek: Telefon numarası ile HubSpot üzerinde kişi arama
const contact = await supsis.hubspot.findContactByPhone("+905551234567");

if (contact) {
  // Kişiye bağlı yeni bir Deal (Satış Fırsatı) oluşturma
  await supsis.hubspot.createRecord("deals", {
    dealname: "WhatsApp Kaynaklı Talep",
    amount: "15000",
    dealstage: "appointmentscheduled",
    pipeline: "default"
  }, { associateContactId: contact.id });

  // İlgili anlaşmaya not ekleme
  await supsis.hubspot.addNote(contact.id, "Müşteri WhatsApp üzerinden demo talep etti.");
}

10- Sık Karşılaşılan Sorunlar ve Çözümleri

10.a – "Kanal kartında 'Yeniden bağlantı gerekli' uyarısı çıkıyor"

• HubSpot tarafında Access Token silinmiş, yetkileri değiştirilmiş veya personelin geliştirici erişim yetkisi kaldırılmış olabilir.
• Çözüm: HubSpot panelinden yeni bir Access Token üretin, Supsis panelinde HubSpot CRM > Kanal Detayı > Detay sekmesini açarak yeni token'ı yapıştırın ve kaydedin.

10.b – "HubSpot'ta çift (mükerrer) kişi kayıtları açılıyor"

• İletişim kanalındaki telefon formatı seçeneği ile HubSpot'ta saklanan numaraların formatı uyuşmuyor olabilir (Örn: başında + olan ve olmayan numaralar).
• Çözüm: WhatsApp kanal ayarlarından telefon formatını HubSpot standardınıza (E.164 + ile veya Artısız) göre eşitleyin.

10.c – "Anlaşma (Deal) aşaması değiştiğinde otomasyon çalışmıyor"

• HubSpot Private App webhook aboneliklerinde deal.propertyChange seçeneği eklenmemiş olabilir.
• Çözüm: HubSpot Private App → Webhooks sekmesinde deal.propertyChange aboneliğinin aktif olduğunu ve Supsis kanal detayında Client Secret'ın girilmiş olduğunu doğrulayın.

10.d – "Rate Limit (429 Too Many Requests) hatası alıyorum"

• HubSpot Search API saniyede yaklaşık 4–5 istek sınırı uygulamaktadır. Toplu mesajlaşma veya ani otomasyon tetiklenmelerinde burst aramalar bu sınıra takılabilir.
• Çözüm: Otomasyon tasarımcısında seri aramalar arasına gecikme (delay) blokları yerleştirin veya dedup kontrolünde Contact ID önbelleğini kullanın.