Jak połączyć CRM z Heilo przez API

Najprostsza integracja polega na tym, że Heilo samo wysyła dane po każdej rozmowie do Twojego CRM-a.

1. Przygotuj adres URL w CRM-ie, Zapierze, Make albo własnym systemie, na który Heilo ma wysyłać dane.
2. W Heilo dodaj subskrypcję na zdarzenie call.completed. Opcjonalnie dodaj też call.outbound.attempted, jeśli chcesz śledzić próby połączeń wychodzących.
3. Odbieraj call.completed i sprawdzaj podpis Heilo-Signature, żeby upewnić się, że wiadomość przyszła z Heilo.
4. Nie twórz duplikatów: zapisuj event_id z nagłówka heilo-event-id. data.call_id oznacza konkretną rozmowę.
5. W CRM-ie znajdź albo utwórz kontakt po numerze telefonu, potem dodaj lead, deal, aktywność albo notatkę z podsumowaniem i linkiem do nagrania.

Nie kodujesz? Przewodnik połączenia bez kodu (Zapier/Make) prowadzi krok po kroku.

Do publicznego API używasz klucza API. Wygeneruj go w karcie „Klucze API”, a programista wklei go w nagłówek Authorization:

Authorization: Bearer hk_live_AbC1MnPq...

W Heilo są trzy sposoby potwierdzania dostępu:

• Klucz API, np. hk_live_… — używany przez CRM, Zapier, Make albo własny skrypt.
• Sesja użytkownika w przeglądarce — używana tylko w panelu Heilo, nie w integracji API.
• Podpis HMAC — dodatkowe zabezpieczenie webhooków, czyli wiadomości wysyłanych z Heilo do Twojego adresu URL.

Pole environment w odpowiedzi /me ma dziś zawsze wartość live. Klucze testowe są w planach.

Wszystkie publiczne adresy API zaczynają się od:

https://www.heilo.io/api/v1

Te adresy służą głównie do sprawdzenia klucza i odczytu wybranych danych rozmów. Główna integracja CRM powinna opierać się na webhookach, czyli automatycznych powiadomieniach wysyłanych przez Heilo po rozmowie.

curl https://www.heilo.io/api/v1/me \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."

{
  "success": true,
  "data": {
    "api_key_id": "a1b2c3d4-5e6f-7081-92a3-b4c5d6e7f809",
    "user_id": "5f4e3d2c-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
    "organization_id": "7a8b9c0d-1e2f-4a3b-9c8d-7e6f5a4b3c2d",
    "scopes": ["read.calls", "manage.webhooks"],
    "rate_limit_per_hour": 1000,
    "environment": "live"
  },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

Te adresy pozwalają odczytać rozmowy. Klucz API musi mieć uprawnienie read.calls.

curl "https://www.heilo.io/api/v1/calls?limit=20&direction=inbound" \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."

{
  "success": true,
  "data": {
    "items": [
      {
        "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "direction": "inbound",
        "caller_phone": "+48600100200",
        "customer_phone_e164": "+48600100200",
        "caller_name": "Jan Kowalski",
        "duration": 87,
        "crm_status": "new",
        "review_status": null,
        "outbound_lifecycle": null,
        "transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "..." },
        "created_at": "2026-06-03T12:34:56Z"
      }
    ],
    "has_more": false,
    "page": 1,
    "limit": 20
  },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

curl https://www.heilo.io/api/v1/calls/<id> \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."

Lista rozmów nie zwraca plików nagrań. Link do nagrania dostajesz w webhooku, a nagrania mogą zostać usunięte zgodnie z retencją i RODO.

Heilo ogranicza liczbę zapytań w ciągu godziny, osobno dla jednego klucza i całego konta. Limit resetuje się o pełnej godzinie UTC.

Po przekroczeniu limitu API zwraca 429 i informację, kiedy spróbować ponownie:

HTTP/1.1 429 Too Many Requests
Retry-After: 1842
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-06-03T13:00:00Z

Błędy mają stały format JSON. W automatyzacji zapisuj error.code, bo error.message jest opisem dla człowieka i może się zmienić.

{
  "success": false,
  "error": { "code": "RATE_LIMITED", "message": "Per-key rate limit 1000/h exceeded" },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

Kod SUBSCRIPTION_INACTIVE występuje w dwóch sytuacjach: HTTP 402 — subskrypcja Heilo wygasła (płatność), oraz HTTP 409 — subskrypcja webhooka jest wstrzymana (np. przy akcji Test); wtedy najpierw kliknij „Ponów weryfikację”.

Webhook to adres URL w Twoim CRM-ie, Zapierze, Make albo własnym systemie. Po rozmowie Heilo wyśle tam JSON z danymi. Przy aktywacji sprawdzamy, czy adres odpowiada. Każda wiadomość ma podpis HMAC, żeby odbiorca mógł sprawdzić, że pochodzi z Heilo:

POST <your URL>
content-type: application/json
heilo-signature: t=1717423396,v1=4f3a...
heilo-event-id: 1bf3a5e2-...
heilo-event-type: call.completed

{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-...",
  "event_type": "call.completed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-06-03T12:34:56Z",
  "data": { /* see the setup guide for the full schema */ }
}

Co się stanie, jeśli Twój adres nie odpowie:

• Błędy przejściowe (HTTP 408/429/5xx, sieć) ponawiamy z rosnącą przerwą (2 min, 5 min, 30 min, 2 h) — po 5 próbach wiadomość trafia do martwej kolejki.
• Błędy trwałe (HTTP 401/403/422) od razu wstrzymują subskrypcję — bez ponawiania.
• 50 błędów przejściowych z rzędu albo 2 razy z rzędu HTTP 410 Gone (np. usunięty scenariusz w Make) także wstrzymują subskrypcję.
• Po poprawieniu adresu kliknij „Ponów weryfikację”, aby wznowić wysyłkę.

Gdy subskrypcja zostanie automatycznie wstrzymana, wysyłamy e-mail na adres właściciela konta. Zdarzenia z martwej kolejki możesz wysłać ponownie przyciskiem „Wyślij ponownie” w Historii wysyłek — po ponownej weryfikacji subskrypcji.

Gdy dodajesz adres webhooka, Heilo sprawdza, czy da się na niego wysłać wiadomość. Dla Zapier i Make zostaw tryb domyślny. Tryb zaawansowany jest tylko dla własnych serwerów.

{"challenge":"<echo of the challenge field from Heilo's POST>"}

Tryb wybierasz przy tworzeniu subskrypcji. Po utworzeniu nie zmienisz go w miejscu — usuń subskrypcję i dodaj ją ponownie.

Możesz mieć maksymalnie 20 aktywnych subskrypcji na konto. Subskrypcję wstrzymujemy automatycznie po 50 błędach przejściowych z rzędu lub 2 razy z rzędu HTTP 410, a od razu przy HTTP 401/403/422.

Heilo podpisuje każdą wiadomość webhooka. Programista powinien sprawdzić podpis na niezmienionej treści żądania, zanim zapisze dane w CRM-ie.

signed_string = "<unix_timestamp>.<raw_request_body>"
signature     = HMAC-SHA256(signing_secret, signed_string).hex()
header        = "t=<unix_timestamp>,v1=<signature>"

import { createHmac, timingSafeEqual } from 'crypto';

// rawBody MUST be the exact received bytes — do NOT re-serialize the JSON.
function verifyHeiloSignature(rawBody, header, signingSecret, toleranceSec = 300) {
  if (!header) return false;
  const parts = Object.fromEntries(
    header.split(',').map((p) => p.split('=').map((s) => s.trim()))
  );
  const t = Number(parts.t);
  const sig = parts.v1;
  if (!Number.isFinite(t) || !sig) return false;

  // Asymmetric tolerance: reject old replays; allow only small clock skew ahead.
  const now = Math.floor(Date.now() / 1000);
  if (now - t > toleranceSec || t - now > 60) return false;

  const expected = createHmac('sha256', signingSecret)
    .update(`${t}.${rawBody}`)
    .digest('hex');
  const a = Buffer.from(expected, 'utf8');
  const b = Buffer.from(sig, 'utf8');
  // timingSafeEqual THROWS on length mismatch — length-check first.
  return a.length === b.length && timingSafeEqual(a, b);
}

Domyślnie akceptuj wiadomości wysłane maksymalnie 5 minut temu. Dzięki temu stary, przechwycony request nie powinien zostać użyty ponownie.

Sekret podpisu pokazujemy tylko raz — przy utworzeniu subskrypcji. Jeśli go zgubisz albo podejrzewasz wyciek: usuń subskrypcję i utwórz ją ponownie z tym samym adresem URL (adres w Zapier/Make się nie zmienia). Rotacja sekretu bez usuwania jest w planach.

Przy tworzeniu subskrypcji wybierasz, które zdarzenia chcesz odbierać. Każde zdarzenie ma unikalny identyfikator, dzięki czemu CRM może uniknąć duplikatów.

Pierwsze zdarzenie, które dostaniesz, to webhook.test — wiadomość testowa z data._test = true. Użyj jej do zmapowania pól albo odfiltruj.

Poniżej obiekt data każdego zdarzenia. Nazwy pól, typy i wartości słownikowe są częścią kontraktu API i nie zmieniają znaczenia w ramach v1; z czasem mogą dochodzić nowe, opcjonalne pola.

{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-...",        // same value as heilo-event-id header
  "event_type": "call.completed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-06-03T12:34:56Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "caller_phone": "+48600100200",
    "customer_phone_e164": "+48600100200",
    "duration": 87,
    "recording_url": "https://www.heilo.io/api/v1/calls/.../recording.mp3?token=...&exp=...",
    "transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "..." },
    "transcript_original": "..."
  }
}