Heytelmi API (0.27.0)

Heytelmi API'si CRM'inizin, otomasyon aracınızın ya da kendi yazılımınızın santralinize bağlanmasını sağlar: çağrı kayıtlarını okur, süren çağrıları izler, tek istekle arama başlatır (click-to-call) ve olayları webhook ile alırsınız.

Taban adres:

https://api.heytelmi.com/v1

1. Panelde Ayarlar > API anahtarları sayfasını açın (sahip ya da yönetici).
2. Anahtar oluştur deyin, bir ad verin ve yalnızca gereken izinleri seçin.
3. İsterseniz anahtarı belirli IP adreslerine ya da aralıklara bağlayın (203.0.113.10, 198.51.100.0/24).
4. Anahtar yalnızca bir kez gösterilir; güvenli bir yere kaydedin. Heytelmi anahtarın kendisini saklamaz.

Anahtarı her istekte Authorization başlığında gönderin:

curl https://api.heytelmi.com/v1/extensions \
  -H "Authorization: Bearer hk_live_..."

Yönetme izni okumayı da kapsar. Her ucun gerektirdiği izin, ucun açıklamasında yazar. Bu dokümanda yer almayan uçlar (ekip üyeleri, SIP parolası, anahtar yönetimi) yalnızca panelden kullanılır.

• Yenile: yeni anahtar üretilir, eskisi 24 saat daha çalışır. Bu sürede sisteminizi yeni anahtara geçirin.
• İptal et: anahtar hemen geçersiz olur. Sızdığından şüphelendiğiniz anahtarı iptal edin.

• İstek ve yanıt gövdeleri JSON'dur (Content-Type: application/json).
• Zamanlar saat dilimi ofsetiyle ISO 8601 biçimindedir (2026-10-22T14:30:00+03:00).
• Telefon numaraları E.164 olarak döner (+905321234567). İstekte 0532 123 45 67 gibi yerel yazım da kabul edilir.
• Kayıt üzerinde çalışan eylemler yolun sonunda iki noktayla yazılır: POST /event-subscriptions/{id}:ping.

Hata yanıtları her zaman aynı biçimdedir:

{
  "problem": {
    "kind": "live_call.invalid",
    "detail": "Arama isteği geçersiz",
    "context": { "fields": { "destination": "geçerli bir telefon numarası" } }
  }
}

kind değeri sabittir; kodunuzu ona göre yazın. detail insan için açıklamadır ve değişebilir. Alan hatalarında context.fields hangi alanın neden reddedildiğini söyler.

Liste uçları page_size ve page_token parametrelerini alır. Yanıttaki next_page_token bir sonraki sayfanın anahtarıdır; boşsa son sayfadasınız. Toplam kayıt sayısı X-Result-Count başlığındadır.

Arama başlatan isteklerde Idempotency-Key başlığı gönderin (ör. bir UUID ya da CRM'deki düğme tıklamasının kimliği). Bağlantı koptuğu için isteği tekrarlarsanız ikinci bir arama başlamaz, ilk çağrı döner. Aynı anahtar başka bir istek gövdesiyle gelirse 422 request.idempotency_key_reused döner.

CRM'inizdeki bir düğmeyle arama başlatın: önce temsilcinin dahilisi çalar, temsilci açınca müşteri firmanızın numarasıyla aranır ve ikisi bağlanır. Anahtarda calls.control izni gerekir.

curl -X POST https://api.heytelmi.com/v1/live-calls \
  -H "Authorization: Bearer $HEYTELMI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: crm-4711-btn-1" \
  -d '{
    "mode": "bridge",
    "agent": { "extension": "101" },
    "destination": "0532 123 45 67",
    "metadata": { "crm_contact_id": "4711" }
  }'

Yanıt 202 ve süren çağrıdır; id çağrının kimliğidir ve çağrı bitince GET /call-logs/{id} altında aynı kalır.

1. Temsilcinin dahilisi 20 saniye çalar. Açmazsa çağrı müşteri aranmadan biter (missed).
2. Temsilci açınca çalma sesi duyar; müşteri 30 saniye aranır.
3. Müşteri açınca görüşme başlar. Açmazsa temsilci kısa bir meşgul sesi duyar ve çağrı biter.

Dış arama kuralları temsilci çaldırılmadan önce uygulanır: yurt dışı izni, günlük dış arama dakikası ve eşzamanlı çağrı sınırı. Kurallar izin vermezse çağrı rejected olarak kapanır, nedeni hangup_reason alanındadır.

• Webhook: call.initiated, call.connected, call.completed ve call.unanswered olaylarına abone olun. Her olay istekte gönderdiğiniz metadata'yı geri taşır; CRM kaydını onunla eşleştirin.
• Sorgu: GET /live-calls/{id} süren çağrının durumunu, çağrı bitince GET /call-logs/{id} sonucu ve süreyi verir.

• metadata en çok 20 metin alanı alır (anahtar 1–40, değer en çok 200 karakter).
• Aynı Idempotency-Key ile gelen istek yeni arama başlatmaz. Çağrı bitmişse 409 live_call.ended ve context.call_id döner.
• Görüşme kaydı henüz desteklenmez; record: true gönderirseniz istek reddedilir.

Olaylar gerçekleştiği anda adresinize POST edilir. Aboneliği panelde Ayarlar > Webhook'lar sayfasından ya da webhooks.manage izinli bir anahtarla POST /event-subscriptions ile oluşturun. İmza anahtarı (whsec_…) yalnızca oluşturma ve yenilemede bir kez gösterilir.

{
  "event_id": "5c0f6a9e2b1d4e7f8a9b0c1d",
  "event": "call.completed",
  "occurred_at": "2026-10-22T11:42:07Z",
  "data": {
    "call": {
      "id": 170,
      "direction": "outbound",
      "kind": "click_to_call",
      "status": "answered",
      "from_number": "101",
      "to_number": "+905321234567",
      "duration_seconds": 74
    }
  },
  "metadata": { "crm_contact_id": "4711" }
}

data olaya göre call, voicemail ya da extension taşır; alanlar ilgili API uçlarının yanıtlarıyla aynıdır.

Her istek iki başlık taşır:

• X-Imza: t=1792664527,v1=5d41402a… — v1, HMAC-SHA256(imza_anahtarı, "<t>.<gövde>") değerinin onaltılık yazımıdır.
• X-Teslim-Id: 812 — teslimin kimliği; tekrar denemelerinde aynı kalır.

Gövdeyi ayrıştırmadan önce, geldiği haliyle doğrulayın. Anahtarı yenilediyseniz 24 saat boyunca başlıkta iki v1 bulunur; biri eşleşmesi yeterlidir. Eski istekleri reddetmek için t ile şimdiki zaman arasındaki farkı da denetleyin (ör. 5 dakika).

Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

function verify(header, rawBody, secret, toleranceSec = 300) {
  const parts = header.split(",");
  const t = parts.find((p) => p.startsWith("t="))?.slice(2);
  if (!t || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const want = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return parts
    .filter((p) => p.startsWith("v1="))
    .some((p) => {
      const got = Buffer.from(p.slice(3), "hex");
      return got.length === want.length && timingSafeEqual(got, want);
    });
}

Go:

func verify(header string, body []byte, secret string, tolerance time.Duration) bool {
    var ts string
    var sigs []string
    for _, p := range strings.Split(header, ",") {
        if v, ok := strings.CutPrefix(p, "t="); ok {
            ts = v
        } else if v, ok := strings.CutPrefix(p, "v1="); ok {
            sigs = append(sigs, v)
        }
    }
    sec, err := strconv.ParseInt(ts, 10, 64)
    if err != nil || time.Since(time.Unix(sec, 0)).Abs() > tolerance {
        return false
    }
    m := hmac.New(sha256.New, []byte(secret))
    m.Write([]byte(ts + "."))
    m.Write(body)
    want := m.Sum(nil)
    for _, s := range sigs {
        if got, err := hex.DecodeString(s); err == nil && hmac.Equal(got, want) {
            return true
        }
    }
    return false
}

PHP:

function heytelmi_verify(string $header, string $body, string $secret, int $tolerance = 300): bool {
    $t = null; $sigs = [];
    foreach (explode(',', $header) as $part) {
        if (str_starts_with($part, 't=')) $t = substr($part, 2);
        elseif (str_starts_with($part, 'v1=')) $sigs[] = substr($part, 3);
    }
    if ($t === null || abs(time() - (int) $t) > $tolerance) return false;
    $want = hash_hmac('sha256', $t . '.' . $body, $secret);
    foreach ($sigs as $sig) {
        if (hash_equals($want, $sig)) return true;
    }
    return false;
}

• Adres https olmalı; iç ağ adreslerine teslim yapılmaz, yönlendirme izlenmez.
• Alıcı 10 saniye içinde 2xx dönmelidir. Uzun işleri kuyruğa alıp hemen yanıt verin.
• 2xx dışındaki yanıtlarda 1 dk, 5 dk, 30 dk, 2 sa ve 12 sa sonra tekrar denenir; altıncı denemeden sonra teslim başarısız sayılır.
• Aynı olay birden fazla gelebilir; event_id ile daha önce işlediğiniz olayı atlayın.
• Teslim geçmişini GET /event-subscriptions/{id}/attempts ile görün, başarısız teslimi :redeliver ile yeniden gönderin. Adresinizi :ping ile sınayın.

Santral: dahililer. Dahilinin Asterisk kimliği kiracı önekli (t42_101); SIP parolası hiçbir yanıtta görünmez, yalnızca :issueSecret yeniler ve bir kez döndürür.