Bilgilendirme Kartında Arayan Adı, Şirket ve Bakiye Göster -New

Genel Bakış

Bir temsilci çağrıyı yanıtladığında her saniye önemlidir. Kimin aradığını öğrenmek için CRM'de arama yapmak yerine, temsilci merhaba demeden önce arayanın adını, şirketini ve hesap bakiyesini otomatik olarak görmelidir.

Bu rehber, bir çağrı bağlandığı anda temsilci ekranında gerçek zamanlı arayan verilerini görüntülemek için Webkancaları ve Bilgilendirme Kartı API'sini nasıl birleştireceğinizi gösterir.

Nasıl Çalışır

Entegrasyon iki Hipcall geliştirici aracını kullanır:

Webkancaları — Bir çağrı başladığında Hipcall, sunucunuza bir call_init olayı gönderir.
Bilgilendirme Kartı API — Sunucunuz arayanı sorgular ve Hipcall'a bir kart göndererek bunu temsilcinin ekranında gösterir.

Mimari

flowchart TD
    A[Gelen çağrı] --> B[Hipcall call_init webkancasını gönderir]
    B --> C[Sunucunuz olayı alır]
    C --> D{CRM/ERP'de\neşleşme bulundu mu?}
    D -- Evet --> E[Bilgilendirme Kartı API'sine POST gönder]
    D -- Hayır --> F[Atla]
    E --> G[Temsilci ekranda arayan bilgisini görür]

Adım 1: Webkancayı Alın

Hesap > Entegrasyonlar > Webkancaları bölümünden call_init olayına abone olun. Hipcall, her çağrı başladığında — hem gelen hem giden — uç noktanıza bir JSON yükü POST edecektir.

Örnek webkanca yükü:

{
  "event": "call_init",
  "data": {
    "credited": null,
    "team_touch_at": null,
    "first_touch_duration": null,
    "contact_id": null,
    "callee_id": null,
    "answered_at": null,
    "voicemail_url": null,
    "caller_number": "+90850XXXXXXX",
    "missing_call_reason": null,
    "call_duration": null,
    "callback_time": null,
    "call_flow": [
      {
        "action": "init",
        "detail": {
          "id": null,
          "type": "contact"
        },
        "timestamp": 1790691203
      }
    ],
    "direction": "outbound",
    "callee_number": "+90530XXXXXXX",
    "voicemail_id": null,
    "callback_user_id": null,
    "callee_type": "contact",
    "ended_at": null,
    "missing_call": null,
    "channel_type": "number",
    "callback_cdr_uuid": null,
    "voicemail_type": null,
    "caller_id": null,
    "started_at": "2026-09-29T14:13:23Z",
    "bridged_at": null,
    "channel_id": 942,
    "caller_type": null,
    "user_id": 4200,
    "hangup_by": null,
    "uuid": "410c92c5-2b61-4dd2-aa75-xxxxxxxxxxxx",
    "record_url": null,
    "number_id": 942,
    "company_id": 80719
  }
}

Örnek, giden bir çağrıya aittir (direction: outbound).

data.uuid (çağrı kimliği) ve müşterinin telefon numarasını çıkarın:

Gelen çağrı (inbound) → müşteri data.caller_number'dır
Giden çağrı (outbound) → müşteri data.callee_number'dır (yukarıdaki örnekte +90530XXXXXXX)

Adım 2: CRM veya ERP'nizde Arayan Verisini Sorgulayın

Müşterinin telefon numarasını kullanarak veri kaynağınızı — bir veritabanı, CRM API'si veya ERP sistemi — sorgulayın.

CRM'inizden örnek yanıt:

{
  "full_name": "Ahmet Y.",
  "company": "Örnek Teknoloji A.Ş.",
  "segment": "Kurumsal",
  "balance": "14250.00",
  "account_manager_user_id": 4200
}

Eşleşme bulunamazsa Bilgilendirme Kartı API'sine istek atmayın ve webkanca isteğine sadece 200 OK dönün. Hipcall boş bir kartı ({"card": []}) teknik olarak kabul eder, ancak temsilcinin ekranında içi boş, anlamsız bir gri panel görünür.

Adım 3: Kartı Bilgilendirme Kartı API'sine Gönderin

Kartı doğru çağrıyla ilişkilendirmek için webkanca yükündeki data.uuid değerini {call_id} yerine kullanarak Bilgilendirme Kartı API'sini çağırın.

Uç nokta:

POST https://use.hipcall.com.tr/api/v3/calls/{call_id}/cards
Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

İstek gövdesi:

{
  "card": [
    {
      "type": "title",
      "text": "Ahmet Y.",
      "link": "https://crm.example.com/customers/102"
    },
    {
      "type": "shortText",
      "label": "Şirket",
      "text": "Örnek Teknoloji A.Ş.",
      "link": "https://crm.example.com/customers/102"
    },
    {
      "type": "shortText",
      "label": "Segment",
      "text": "Kurumsal"
    },
    {
      "type": "shortText",
      "label": "Bakiye",
      "text": "14.250 TL (Açık Fatura)"
    },
    {
      "type": "user",
      "label": "Hesap Yöneticisi",
      "user_id": 4200
    }
  ]
}

Bu örnekte başlıkta müşteri adı, altında şirket, segment ve bakiye görünür. user satırı ise Hipcall kullanıcı ID'sinden hesap yöneticisinin adını karta basar.

İşlem başarılı olduğunda API 201 Created döner ve kart temsilcinin Webphone'unda görünür. Telefon ortalama 5-15 saniye çaldığı için kendi veritabanınızda 2 saniyelik bir sorgu güvenlidir; CRM sorgunuz 3-4 saniyeyi aşarsa kart ancak temsilci telefonu açtıktan sonra ekrana düşer.

Karta ekleyebileceğiniz satır tipleri:

Satır Tipi	Alanlar	Açıklama
`title`	`type`, `text`, `link`	Ana kart başlığı. `link` verilirse tıklanabilir.
`shortText`	`type`, `text`, `label`, `link`, `ios`, `android`	İki sütunlu veri satırı: solda `label`, sağda `text` görünür.
`user`	`type`, `label`, `user_id`	Hipcall kullanıcı ID'sinden temsilcinin adını karta basar.

Dikkat Edilecekler

Her satır tipi yalnızca kendi alanlarını kabul eder. Örneğin shortText satırına user_id göndermek (değeri null olsa bile) 422 Unprocessable Entity ile reddedilir. Boş alanları JSON gövdesine yazmayın.
Çağrı bittikten sonra kart göndermeyin. Çağrı kapanmışsa API yine 201 Created döner, ancak temsilci kartı göremez.
Webkancaya hemen 200 OK dönün. CRM sorgusunu ve kart gönderimini arka planda yapın.

Kullanılan Araçlar

Araç	Amaç
Webkancaları	Bir çağrı başladığında `call_init` olayını alır
Bilgilendirme Kartı API	Arayan veri kartını temsilcinin ekranına gönderir

Sonraki Adımlar

Webkancaları dokümantasyonu — Olaylara abone olun, yeniden deneme mantığını yapılandırın, imzaları doğrulayın
REST API kimlik doğrulaması — Sunucunuz için API anahtarları veya OAuth 2.0 ayarlayın