Przejdź do treści

Jak połączyć CRM z Heilo przez API

Prosta ścieżka integracji: Heilo wysyła dane rozmów do Twojego CRM-a, a niżej znajdziesz szczegóły dla programisty.

v1 · 2026-06-15Beta

Szybki start: połącz CRM z Heilo

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

Najważniejsze zdarzenie to call.completed. Oznacza: rozmowa jest gotowa, a CRM może zapisać kontakt, lead lub notatkę. Adresy REST /calls traktuj jako dodatek do sprawdzania lub odczytu danych.

  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 odbiorcę 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.

Dostęp przez klucz API

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 wysyłki — dodatkowe zabezpieczenie webhooków, czyli wiadomości wysyłanych z Heilo do Twojego adresu URL.
Uprawnienie (scope)Znaczenie
read.callsOdczyt rozmów: GET /api/v1/calls, GET /api/v1/calls/:id
read.recordingsWydanie linku do pliku audio rozmowy przez `GET /calls/:id/recording-url`. Osobno od `read.calls`, bo audio to inna zgoda niż metadane — stary klucz go nie dostaje, trzeba utworzyć nowy z jawnym dostępem do nagrań.
read.transcriptsDodaje tekst transkrypcji do `GET /calls/:id`: `transcript_original`, `transcript_edited` i `transcript_edited_at`. Osobny od `read.calls`, bo słowa rozmowy to inna zgoda niż metadane — istniejący klucz go nie dostaje, trzeba utworzyć nowy klucz z wyraźnym dostępem do transkrypcji. Bez niego tych pól nie ma w odpowiedzi, a rozmowa nadal zwraca 200. Wymaga też `read.calls`: klucz z samym `read.transcripts` dostaje 403, a tworzenie takiego klucza kończy się błędem 400.
write.calls, read.contacts, write.contacts, manage.webhooks, manage.api_keysZarezerwowane dla planowanych punktów API. Nowego klucza z nimi nie da się utworzyć (400 BAD_REQUEST). Starszy klucz może jeszcze któryś mieć i nic mu on nie daje.

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

Adres bazowy i wersja

Wszystkie publiczne adresy API zaczynają się od:

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

Aktualna wersja

v1 · 2026-06-15

To nazwa wersji API, nie informacja o dzisiejszej dacie.

Status

Beta

Wersja API jest oznaczona datą. Drobne zmiany, takie jak nowe pola w odpowiedzi lub w ładunku webhooka, nie powinny psuć istniejącej integracji.

Jeśli kiedyś zmienimy API w sposób wymagający zmian po Twojej stronie, wydamy nową główną wersję, np. v2, i utrzymamy starą wersję przez co najmniej 12 miesięcy.

Limity zapytań

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

Na jeden klucz

1000 req/h

Na całe konto

5000 req/h

Każda udana odpowiedź niesie X-RateLimit-Limit (godzinny limit klucza), X-RateLimit-Remaining (ile żądań zostało kluczowi w tej godzinie) i X-RateLimit-Reset (kiedy licznik się zeruje, ISO 8601). Po przekroczeniu zwracamy 429 z nagłówkiem Retry-After (sekundy do resetu):

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

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" }
}
{
  "success": false,
  "error": { "code": "BAD_REQUEST", "message": "Validation failed", "details": { "errors": [{ "path": "scopes", "message": "Required" }] } },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}
HTTPcodeZnaczenie
400BAD_REQUESTNiepoprawne parametry zapytania lub treści (ogólna walidacja)
401UNAUTHORIZEDBrak lub niepoprawny klucz API
402SUBSCRIPTION_INACTIVESubskrypcja nieaktywna — odnów płatność, aby znów włączyć klucz
403FORBIDDENKlucz API nie ma potrzebnego uprawnienia
404NOT_FOUNDZasób nie istnieje lub znajduje się poza organizacją przypisaną do klucza API.
400VALIDATION_ERRORParametr nie przeszedł sprawdzenia (np. phone nie jest numerem telefonu)
429RATE_LIMITEDPrzekroczono limit zapytań
500DATABASE_ERRORBłąd serwera lub bazy — można spróbować ponownie później
503MAINTENANCEPubliczne API jest tymczasowo wyłączone
503SERVICE_UNAVAILABLECzęść usługi potrzebna do tego wywołania jest niedostępna (na przykład nie da się teraz wystawić linków do nagrań) — ponów z odstępem
503WEBHOOK_ACTIVATION_LOCKEDWłączanie subskrypcji webhooków jest wstrzymane na czas migracji; istniejące subskrypcje działają dalej — spróbuj później
422SUBSCRIPTION_LIMITOrganizacja osiągnęła limit subskrypcji webhooków (HTTP 422) — najpierw usuń nieużywaną

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

Błąd może też nieść error.details ze szczegółami, na przykład z polami, które nie przeszły walidacji; pola może nie być. Stały jest kod.

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

Sprawdza, czy klucz API działa. Zwraca identyfikator klucza, użytkownika, uprawnienia i limit zapytań.

Przydatne jako test połączenia: jeśli dostajesz odpowiedź 200, klucz i sieć działają.

Przykładowe zapytanie
curl https://www.heilo.io/api/v1/me \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Przykładowa odpowiedź
{
  "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", "read.recordings"],
    "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.

Lista rozmów organizacji. Stronicowanie (page/limit≤100), filtry: direction, status, zakres dat (dateFrom/dateTo). Zwraca has_more.

Lista jest od najnowszej (created_at malejąco) i dzielona na strony po numerze, więc rozmowa, która wpadnie w trakcie przeglądania, przesuwa wiersze. Deduplikuj po call_id i przeczytaj pierwszą stronę jeszcze raz, żeby nadrobić. To nie jest eksport pełnej historii.

Parametry zapytania

ParametrTypWartości
pageintod 1 (domyślnie 1)
limitint1–100 (domyślnie 20)
directionenuminbound | outbound
statusenumnew | to_call | contacted | qualified
dateFrom / dateTostringdata YYYY-MM-DD albo data z godziną w UTC, np. 2026-06-03T12:34:56Z (przesunięcie strefy, np. +02:00, daje błąd 400). Sama data w dateTo obejmuje cały ten dzień w UTC, więc dateTo=2026-06-03 zwraca też rozmowy z 3 czerwca; data z godziną to dokładna chwila, włącznie
phonestringnumer klienta z rozmowy, z numerem kierunkowym kraju; spacje, myślniki i wiodący + są opcjonalne, np. +48 600 100 200
Przykładowe zapytanie
curl "https://www.heilo.io/api/v1/calls?limit=20&direction=inbound" \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Przykładowa odpowiedź
{
  "success": true,
  "data": {
    "items": [
      {
        "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "direction": "inbound",
        "caller_phone": "+48600100200",
        "customer_phone_e164": "+48600100200",
        "customer_phone_national": "600 100 200",
        "company_phone_e164": "+48222630000",
        "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "caller_name": "Jan Kowalski",
        "duration": 87,
        "crm_status": "new",
        "review_status": null,
        "outcome": "quote_to_send",
        "outcome_source": "ai",
        "outbound_lifecycle": null,
        "transcript_processed": { "caller_name": "Jan Kowalski", "summary": "...", "service_needed": "...", "followup_email": null },
        "created_at": "2026-06-03T12:34:56Z"
      }
    ],
    "has_more": false,
    "page": 1,
    "limit": 20
  },
  "meta": { "timestamp": "2026-06-03T12:34:56Z" }
}

Jedna rozmowa po identyfikatorze. API zwróci 404, jeśli rozmowa nie należy do organizacji albo została usunięta.

W tym punkcie obiekt analizy transcript_processed niesie summary, service_needed, caller_name i followup_email, a także subject, lead_score (1–10, szacunek modelu), detected_language i client_city: te same wartości, które wysyła webhook call.completed. Pole, którego analiza nie wytworzyła, ma wartość null. has_recording mówi, czy dźwięk jest zapisany; sam dźwięk pobierzesz z GET /calls/:id/recording-url z zakresem read.recordings.

Z zakresem read.transcripts odpowiedź niesie też transcript_original (null, gdy rozmowa nie ma użytecznej transkrypcji: jest jeszcze przetwarzana, się nie udała albo nie było mowy), transcript_edited i transcript_edited_at (null, gdy nikt jej nie poprawiał). Bez tego zakresu tych trzech pól nie ma w odpowiedzi (nie null), a odpowiedź nadal ma status 200.

Odpowiedź niesie też user_notes: wpisy, które ludzie zapisali przy rozmowie w Heilo („Notatki do rozmowy”), od najstarszego, najwyżej 200, a gdy ich nie ma, pustą tablicę. Lista GET /calls ich nie zawiera. Przykład jest skrócony; pozostałe pola są takie same jak na liście. Żeby dowiadywać się o zmianach wpisów, zapisz się na call.user_notes.changed.

Przykładowe zapytanie
curl https://www.heilo.io/api/v1/calls/<id> \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Przykładowa odpowiedź
{
  "success": true,
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "duration": 87,
    "outcome": "quote_to_send",
    "outcome_source": "ai",
    "created_at": "2026-06-03T12:34:56Z",
    "transcript_processed": {
      "caller_name": "Anna Nowak",
      "summary": "Asks for a quote for a bathroom renovation.",
      "service_needed": "bathroom renovation",
      "followup_email": null,
      "subject": "Bathroom renovation quote",
      "lead_score": 7,
      "detected_language": "en",
      "client_city": "Gdańsk"
    },
    "has_recording": true,
    "user_notes": [
      {
        "id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "body": "Klient prosi o telefon po 10:00.",
        "source": "live",
        "author": {
          "id": "2ce127a0-c621-483d-b576-e68f69d95e84",
          "name": "Anna Nowak"
        },
        "noted_at": "2026-09-08T10:01:12Z",
        "recording_offset_seconds": 72,
        "created_at": "2026-09-08T10:01:12Z",
        "updated_at": "2026-09-08T10:01:12Z"
      }
    ]
  },
  "meta": {
    "timestamp": "2026-06-03T12:34:56Z"
  }
}

Świeży link do pliku audio rozmowy, ważny 15 minut. To pozwolenie na pobranie z terminem, a nie trwały odnośnik: zapisz `call_id` i poproś o link ponownie, bo adres wklejony w pole CRM-a przestanie działać w ciągu godziny. Link z webhooka `call.recording.ready` jest podpisany na siedem dni — ta trasa służy do sięgnięcia po audio później.

  • 200 — link i moment, w którym przestaje działać.
  • 409 `RECORDING_NOT_READY` — rozmowa jest Twoja, ale audio jeszcze nie dotarło. Zapytaj ponownie za chwilę.
  • 409 `RECORDING_WITHHELD` — rozmowa jest w koszu albo zaplanowana do usunięcia. Rozmowę z kosza klient może przywrócić przez 30 dni, więc pytaj dalej, zamiast wykreślać nagranie u siebie; rozmowa z nagraniem jest kasowana 30 dni po przeniesieniu do kosza. Zaplanowanego usunięcia nie da się cofnąć: przestań używać nagrania. W obu przypadkach po skasowaniu dostaniesz 410.
  • 410 `RECORDING_DELETED` — nagranie skasowano (retencja, kosz po 30 dniach albo żądanie usunięcia) i nie da się go odzyskać. Przestań pytać i przestań kolejkować.
  • 410 `RECORDING_NOT_CAPTURED` — to połączenie wychodzące nigdy nie zostało nagrane i nagranie nigdy nie powstanie: bramka przechwytywania odmówiła nagrania przy jego rozpoczęciu, szło w trybie no_recording albo skończyło się bez rozmowy. Przestań pytać — nie ma powodu, by ponawiać. Połączenie przychodzące, którego nagrania odmówiono, dalej odpowiada 409, bo nagranie może jeszcze nadejść.

Odpowiedź jest podawana z nagłówkiem `Cache-Control: no-store`, bo ciało niesie poświadczenie. Uprawnienie jest sprawdzane ponownie przy pobraniu pliku, a nie tylko przy wydaniu linku, więc rozmowa usunięta w międzyczasie przestaje być dostępna natychmiast.

Przykładowe zapytanie
curl https://www.heilo.io/api/v1/calls/<id>/recording-url \
  -H "Authorization: Bearer hk_live_AbC1MnPq..."
Przykładowa odpowiedź
{
  "success": true,
  "data": {
    "url": "https://www.heilo.io/api/v1/calls/<id>/recording.mp3?token=...&exp=...",
    "expires_at": "2026-09-15T12:15:00.000Z"
  }
}

Ani lista rozmów, ani szczegóły nie zwracają pliku ani linku do nagrania; szczegóły mówią tylko, czy nagranie istnieje (has_recording). Link do nagrania dostajesz w webhooku, a po jego wygaśnięciu z `GET /calls/:id/recording-url`. Nagrania mogą zostać usunięte zgodnie z zasadami retencji i RODO.

Co jest w REST, a co tylko w webhooku

Te dwa kanały nie niosą tego samego, a różnica decyduje o wyborze. REST jest trwały: rozmowę odczytasz z niego kiedykolwiek. Webhook jest bogatszy, ale przychodzi raz i część jego treści z czasem znika.

DaneRESTWebhook
Metadane rozmowy: kierunek, numery, czas trwania, datajestjest
Status w CRM-ie i status przeglądujestbrak
Wynik rozmowy i kto go ustawiłjestjest
Notatki do rozmowy (w REST tylko w GET /calls/:id)jestjest
Podsumowanie, imię dzwoniącego, potrzeba klientajestjest
Pozostałe pola analizy: miasto, adres, ocena leada, preferowany termin, językczęściowo: GET /calls/:id ma miasto, ocenę leada i język; adres i preferowany termin tylko w webhookujest
Zapis rozmowy słowo w słowotak, GET /calls/:id z read.transcriptsjest
Link do nagraniajest, przez /calls/:id/recording-urljest, ważny 7 dni

Stąd praktyczna zasada: webhook niesie wszystko w chwili przetworzenia rozmowy, a REST daje potem szczegóły jednej rozmowy, z szerszą analizą i, z read.transcripts, z transkrypcją. Nagranie odzyskujesz osobno — poproś /calls/:id/recording-url o świeży link na 15 minut zamiast zapisywać siedmiodniowy z payloadu.

Specyfikacja i zapytanie na żywo

Te same cztery operacje, zapisane dla maszyn: OpenAPI 3.1. Zaimportuj je do Postmana albo Insomnii, albo wygeneruj klienta w swoim języku.

Pobierz OpenAPI 3.1

Specyfikacja i zapytanie na żywo

Wyślij stąd jedno zapytanie i sprawdź, czy klucz działa, zanim napiszesz choć linijkę kodu.

To wywołuje prawdziwe API Twoim prawdziwym kluczem i zwraca Twoje własne dane. Klucz zostaje w tej karcie przeglądarki — nigdzie go nie zapisujemy.

Webhooki: dane wysyłane do CRM-a

Heilo wysyła podpisane zdarzenia JSON na Twój endpoint. Odbiorcę dodasz w karcie „Webhooki do CRM-a” przyciskiem „Dodaj adres”. Aktywacja używa osobnego, niepodpisanego handshake webhook.subscription.verify, który nie może tworzyć rekordów biznesowych.

Adres punktu końcowego musi być https, publicznie osiągalny i nie może wskazywać adresu prywatnego ani wewnętrznego (localhost, 10.x, 192.168.x i podobne). Żeby przetestować z własnego komputera, wystaw go przez publiczny tunel. Punkty końcowe tworzy się tylko w Ustawieniach → Integracje; żadne wywołanie API ich nie tworzy.

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 uruchamiają maksymalnie 5 prób łącznie: po 2 min, 5 min, 30 min i 2 h, z niewielkim losowym przesunięciem późniejszych prób (jitter). Piąta nieudana próba kończy dostawę statusem dead-letter.
  • Błędy trwałe (HTTP 401/403/422) od razu wstrzymują wysyłkę — 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ą wysyłkę.
  • Po poprawieniu adresu kliknij „Ponów weryfikację”, aby wznowić wysyłkę. Weryfikacja nie wyśle zdarzeń, które czekały w kolejce w chwili wstrzymania: trafiły do martwej kolejki i trzeba je wysłać ręcznie przyciskiem „Wyślij ponownie” w Historii wysyłek.

Gdy Heilo automatycznie wstrzyma wysyłkę po błędach Twojego adresu, wysyłamy e-mail do osoby, która opiekuje się odbiorcą — zwykle tej, która go utworzyła. Jeśli jej konta już nie ma, e-mail dostają właściciele organizacji. Zdarzenia z martwej kolejki możesz wysłać ponownie przyciskiem „Wyślij ponownie” w Historii wysyłek — po ponownej weryfikacji odbiorcy.

Odpowiedź 2xx potwierdza odbiór HTTP, nie zakończenie automatyzacji ani zapis w CRM-ie. Dostawy mogą się powtarzać i przychodzić poza kolejnością. Heilo uzupełnia niedawne braki w ograniczonym oknie czasu; nie jest to odzyskiwanie całej historii. Sprawdzaj osobno historię dostaw i wynik w CRM-ie.

Weryfikacja adresu webhooka

Niepodpisany handshake zawiera tylko event_type = webhook.subscription.verify oraz challenge. Odpowiedz wyłącznie w celu potwierdzenia endpointu; nie uruchamiaj zapisu biznesowego. Oba tryby używają tego samego żądania:

{
  "event_type": "webhook.subscription.verify",
  "challenge": "example-verification-token"
}

Tryb prosty permissive (domyślnie)

Dowolna odpowiedź 2xx aktywuje odbiorcę, a treść odpowiedzi jest pomijana. To domyślny tryb dla odbiornika no-code.

Tryb zaawansowany strict (opcjonalnie)

Zwróć 2xx oraz JSON z dokładnie tą wartością challenge, którą otrzymałeś od Heilo:

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

Wybierz tryb w formularzu tworzenia. Jego zmiana wymaga usunięcia i ponownego utworzenia odbiorcy. Trasy zarządzania odbiorcami wymagają zalogowanej sesji i ochrony CSRF; nie są endpointami dostępnymi z kluczem API.

Organizacja może mieć najwyżej 20 aktywnych odbiorców. Wysyłkę 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.

Podpis bezpieczeństwa wysyłki

Podpisane zdarzenia, w tym ręczny webhook.test, używają Heilo-Signature z podpisem HMAC-SHA256 liczonym z timestamp + kropka + oryginalne bajty żądania. Sprawdź podpis przed parsowaniem biznesowego JSON. Niepodpisany jest wyłącznie handshake potwierdzający endpoint.

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 'node:crypto';

// Pass the exact received Buffer (e.g. Express raw parser), never JSON.stringify(req.body).
// signingSecrets: every secret you currently trust, tried in constant time each.
// During a secret rotation pass [newSecret, oldSecret]; remove the old one once
// Heilo's grace window ends. Heilo itself always sends exactly ONE v1 signature —
// this list is what lets your receiver accept it under either secret while both
// are live, never a second signature to parse.
function verifyHeiloSignature(rawBody, header, signingSecrets) {
  const match = /^t=(\d+),v1=([a-f0-9]{64})$/.exec(header || '');
  if (!match) return false;
  const timestamp = Number(match[1]);
  const now = Math.floor(Date.now() / 1000);
  // Receiver policy: at most 10 minutes old or 5 minutes ahead (clock skew).
  if (!Number.isSafeInteger(timestamp) || now - timestamp > 600 || timestamp - now > 300) return false;
  // One string is accepted too. Empty entries are dropped: an HMAC key of ''
  // is valid, so a blanked env var (OLD_SECRET=) would let anyone sign events.
  const secrets = [].concat(signingSecrets).filter((s) => typeof s === 'string' && s.length > 0);
  if (secrets.length === 0) return false;
  const actual = Buffer.from(match[2], 'hex');
  return secrets.some((signingSecret) => {
    const expected = createHmac('sha256', signingSecret)
      .update(match[1] + '.')
      .update(rawBody)
      .digest();
    return actual.length === expected.length && timingSafeEqual(actual, expected);
  });
}

function receiveHeiloWebhook(rawBody, signatureHeader, signingSecrets) {
  if (!signatureHeader) {
    // The ONLY unsigned exception confirms the endpoint; never enqueue it for CRM writes.
    const probe = JSON.parse(rawBody.toString('utf8'));
    if (probe && typeof probe === 'object' && !Array.isArray(probe)
      && Object.keys(probe).length === 2
      && probe.event_type === 'webhook.subscription.verify'
      && typeof probe.challenge === 'string') {
      return { kind: 'verification', response: { challenge: probe.challenge } };
    }
    throw new Error('Missing Heilo-Signature');
  }
  if (!verifyHeiloSignature(rawBody, signatureHeader, signingSecrets)) throw new Error('Invalid Heilo-Signature');
  return { kind: 'event', event: JSON.parse(rawBody.toString('utf8')) };
}

// HTTP adapter: limit body size; map verification to 200 JSON response.
// Signature errors -> 401 (pauses delivery; fix the secret, then Reverify). JSON errors -> 400.
// For kind=event: validate the envelope and chosen event_type, ignore webhook.test
// in business flows, then durably deduplicate/enqueue by event_id BEFORE returning 2xx.
// Enqueue failure: return 503. An HTTP acknowledgement is not proof of a CRM write.

Przykłady akceptują podpisy starsze o maksymalnie 600 sekund (10 minut) i wyprzedzające zegar o 300 sekund (5 minut), zgodnie z obecnym weryfikatorem Heilo. Synchronizuj zegary serwerów. Kontrola czasu ogranicza okno ponownego użycia podpisu; nadal trzeba deduplikować po event_id.

Sekret podpisu pokazujemy tylko raz — przy dodaniu odbiorcy. Zgubiłeś go albo podejrzewasz wyciek? Otwórz odbiorcę w Ustawienia → Integracje → Webhooki i wymień go tam — zobacz „Rotacja sekretu” poniżej. Nie trzeba usuwać odbiorcy i zakładać go od nowa.

Rotacja sekretu

Heilo zawsze wysyła dokładnie jeden podpis v1, nigdy dwa naraz. Dlatego wymiana polega na kolejności: najpierw Twój odbiornik uczy się nowego sekretu, dopiero potem Heilo zaczyna nim podpisywać.

  1. Przygotuj nowy sekret w ustawieniach odbiorcy. Pokazujemy go raz, a on czeka na aktywację przez 24 godziny.
  2. Zainstaluj nowy sekret OBOK obecnego — Twój odbiornik musi akceptować podpis zrobiony którymkolwiek z nich.
  3. Opcjonalnie wyślij test podpisany nowym sekretem. Niesie nagłówek Heilo-Secret-Rotation-Id i zwykłe body webhook.test; odpowiedź 2xx nie dowodzi, że odbiornik sprawdził podpis — potwierdź to we własnym logu.
  4. Aktywuj rotację.
  5. Trzymaj stary sekret zainstalowany jeszcze przez 1 godzinę po aktywacji, potem go usuń.

Heilo nie zmienia niczego po stronie Twojego odbiornika. To Twój odbiornik musi w tym czasie przyjmować podpis zrobiony którymkolwiek z dwóch sekretów.

Tryb awaryjny: sekret wyciekł

Rotacja awaryjna od razu wstrzymuje wysyłkę. Zainstaluj WYŁĄCZNIE nowy sekret — stary uznaj za skompromitowany — potem aktywuj; nie ma okresu karencji. Wznów wysyłkę potem przyciskiem „Ponów weryfikację”. Dostawy, które czekały w kolejce w chwili wstrzymania, są pomijane; wyślij je ponownie z dziennika dostaw.

Sekret zaginął, ale nie wyciekł? Wystarczy zwykła wymiana — nie trzeba usuwać odbiorcy.

Zdarzenia, które może wysłać Heilo

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

webhook.test jest wysyłany ręcznym przyciskiem Test i ma data._test = true. Idzie tą samą kolejką dostaw co prawdziwe zdarzenia, więc może dotrzeć chwilę po kliknięciu, a jego wynik widać jako status w historii dostaw. Użyj go do mapowania pól, a następnie wyklucz z obsługi biznesowej. Osobny handshake aktywacji to webhook.subscription.verify.

nazwa technicznaOpis
call.completedZakończona rozmowa, transkrypcja gotowa
call.missedPołączenie przychodzące zakończone bez transkrypcji (nieodebrane, bez wiadomości albo niezarejestrowane)
call.outbound.attemptedPróba połączenia wychodzącego osiągnęła stan końcowy (rozmowa lub niepowodzenie)
call.recording.readyNagranie gotowe do pobrania
call.transcribedTranskrypcja gotowa
call.failedRozmowa nieudana (zajęte / brak odpowiedzi / błąd)
call.outbound.lifecycle_repairedKorekta statusu rozmowy wychodzącej
call.deletion_scheduledRozmowa zaplanowana do usunięcia (RODO)
call.recording.deletedNagranie usunięte (RODO)
call.followup_email.draftedDraft maila follow-up gotowy
call.outcome.changedUstawiono lub zmieniono wynik rozmowy
call.user_notes.changedDodano, zmieniono lub usunięto notatki do rozmowy
call.tracker.matchedWzmianka o śledzonej frazie
contact.createdNowy kontakt utworzony
contact.updatedKontakt zaktualizowany

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.

call.completed

Wysyłane po zakończeniu przetwarzania rozmowy. To główna wiadomość dla CRM-a: zawiera link do nagrania, podsumowanie i rozpoznane dane rozmówcy.

{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.completed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "caller_phone": "+447700900123",
    "customer_phone_e164": "+447700900123",
    "customer_phone_national": "07700 900123",
    "company_phone_e164": "+48222630000",
    "call_created_at": "2026-09-08T10:00:00Z",
    "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "duration": 87,
    "recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
    "transcript_processed": {
      "caller_name": "Alicja Testowa",
      "counterparty_name": null,
      "counterparty_email": null,
      "caller_location": "Warszawa, Mokotów",
      "client_address": "ul. Przykładowa 10",
      "client_city": "Warszawa",
      "client_country": "Poland",
      "service_needed": "Tynki gipsowe w mieszkaniu 65m²",
      "services_match": true,
      "preferred_date": "w przyszłym tygodniu",
      "additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
      "lead_score": 7,
      "summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
      "subject": "Wycena tynków — Warszawa, 65 m²",
      "detected_language": "pl"
    },
    "transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
    "outcome": "quote_to_send",
    "outcome_source": "ai"
  }
}
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
direction'inbound' | 'outbound'Kierunek rozmowy.
caller_phonestring | nullZapisany numer dzwoniącego; null, jeśli niedostępny w call.completed.
customer_phone_e164string | nullNumer klienta do dopasowania kontaktu w CRM-ie; null, jeśli niedostępny w call.completed.
customer_phone_nationalstring | nullTen sam numer klienta w formacie krajowym, gotowy do wklejenia w pole telefonu w CRM-ie; null, gdy zapisana wartość nie jest numerem — na przykład przy zastrzeżonym numerze.
company_phone_e164string | nullNumer, na który ta rozmowa przyszła albo z którego wyszła. Zwykle Twój numer w Heilo; przy przekierowaniu to Twój własny numer, który ją przekazał. Służy do kierowania notatek, gdy masz więcej niż jeden numer; null, gdy nie został zapisany.
call_created_atstring (ISO 8601) | nullKiedy rozmowa została zapisana w Heilo (ISO 8601). To nie to samo co created_at koperty, które jest momentem wysyłki zdarzenia i przy naprawie może być późniejsze o dni.
app_urlstring | nullTrwały odnośnik do rozmowy w Heilo. W odróżnieniu od recording_url nie wygasa, więc można go trzymać w rekordzie CRM-a. Otwarcie wymaga zalogowania do Heilo.
durationnumberDługość nagrania w sekundach.
recording_urlstring | nullLink do nagrania, ważny 7 dni; null, gdy nagranie nie było jeszcze zapisane w chwili przetwarzania. Po wygaśnięciu pobierz świeży link z GET /calls/:id/recording-url.
transcript_processedobjectPrzetworzona analiza rozmowy — patrz spis pól transcript_processed w tej sekcji.
transcript_originalstring | nullSurowa, dosłowna transkrypcja; null, gdy niedostępna.
outcomestring | nullKod wyniku w chwili zbudowania zdarzenia (zobacz kody wyniku niżej); null, gdy nikt go nie ustawił. Klucza brakuje w odtworzeniu starszego zdarzenia albo gdy Heilo nie mogło go odczytać. Późniejsze call.outcome.changed ma pierwszeństwo.
outcome_source'ai' | 'user' | nullKto ustawił wynik: ai (wybrała analiza), user (wybrał lub potwierdził człowiek) albo null (nikt). Brakuje zawsze, gdy brakuje outcome.

Heilo może wysłać to samo zdarzenie więcej niż raz, dlatego CRM powinien sprawdzać event_id i nie tworzyć duplikatów. data.call_id łączy wszystkie zdarzenia dotyczące tej samej rozmowy.

Wynik rozmowy

outcome to jeden z kodów poniżej albo null, gdy nikt go nie ustawił. outcome_source mówi, kto go ustawił: ai albo user. REST zwraca oba pola przy każdej rozmowie; call.completed i call.transcribed niosą je na najwyższym poziomie data; call.outcome.changed zgłasza każdą późniejszą zmianę. Mogą dojść nowe kody, więc nieznaną wartość traktuj jako dodatkową informację, nie błąd.

KodZnaczenie
bookingUmówiono rezerwację, wizytę lub termin.
cancellation_or_rescheduleDzwoniący odwołał albo prosi o nowy termin.
information_requestDzwoniący pytał o informacje.
quote_to_sendDzwoniący czeka na ofertę lub wycenę.
awaiting_customer_decisionKlient się zastanawia i sam da znać.
deal_wonKlient zgodził się w rozmowie kupić, zamówić lub przyjął ofertę. Automatyzację „wygrana” w CRM-ie uruchamiaj tylko przy outcome_source równym user.
callback_scheduledUstalono ponowny kontakt.
not_interestedDzwoniący nie jest zainteresowany.
spam_wrong_numberPusta wiadomość, spam lub pomyłka.
new_opportunityNowa szansa sprzedaży.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach
existing_deal_updateAktualizacja istniejącego projektu.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach
follow_upKolejny kontakt po wcześniejszej rozmowie.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach
no_answerNikt nie odebrał.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach
voicemailDzwoniący zostawił wiadomość głosową.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach
supportZgłoszenie do obsługi klienta.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach
complaintReklamacja.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach

Która wartość wygrywa

Zdarzenie call.outcome.changed ma pierwszeństwo przed wynikiem z call.completed i call.transcribed, bez względu na kolejność dotarcia. Zdarzenia zmiany porządkuj według data.changed_at, nigdy według czasu dotarcia ani created_at z koperty. REST zawsze zwraca aktualną wartość, więc nim nadrobisz zgubione zdarzenie.

data.outcome to kod z tabeli powyżej. To nie to samo co transcript_processed.call_outcome, czyli zdanie w wolnym tekście z analizy.

Zapier i Make: przycisk Test wysyła kształt call.completed. Żeby dostać próbkę call.outcome.changed, wybierz wynik przy dowolnej rozmowie w Heilo.

Notatki do rozmowy (user_notes)

user_notes to lista wpisów, które ludzie zapisali przy rozmowie w Heilo („Notatki do rozmowy”). REST zwraca ją tylko w GET /calls/:id; call.user_notes.changed wysyła całą aktualną listę około pięciu minut po ostatniej zmianie. Autor to imię i nazwisko z profilu w Heilo, nigdy adres e-mail.

Która lista wygrywa

Każda lista niesie revision, które rośnie z każdą zmianą. Podmień swoją kopię listą tylko wtedy, gdy jej revision jest wyższe niż to, które masz, a każdą inną odrzuć: ręczne ponowne wysłanie przysyła starszą listę jeszcze raz. REST zawsze zwraca aktualną listę, więc nim nadrobisz zgubione zdarzenie.

source mówi, skąd wpis pochodzi: live (wpisany na ekranie rozmowy w jej trakcie), after (dopisany później) albo legacy (dawna jedna notatka do rozmowy sprzed 28.10.2026). Mogą dojść nowe wartości, więc nieznaną wartość traktuj jako dodatkową informację, nie błąd. recording_offset_seconds jest ustawione tylko dla wpisu live pisanego w obrębie nagrania.

Zapier i Make: przycisk Test wysyła kształt call.completed. Żeby dostać próbkę call.user_notes.changed, dodaj wpis przy dowolnej rozmowie w Heilo i poczekaj pięć minut.

call.missedZwykle wysyłane mniej więcej dwie godziny po połączeniu przychodzącym, które skończyło się bez transkrypcji, a gdy nie zgłoszono końca połączenia — nawet do około 4 godzin 15 minut później. Pole data.reason mówi dlaczego, a data.answered — czy ktoś odebrał. Możliwe przypadki: nikt nie odebrał i nikt nie zostawił wiadomości, dzwoniący rozłączył się przed rozpoczęciem rejestrowania, rejestrowanie było wtedy wyłączone dla tego numeru, Heilo celowo nie rejestrowało rozmowy, nagranie było za krótkie albo transkrypcji nie udało się przygotować. Wysyłamy też połączenie odebrane, które nie ma transkrypcji, z answered równym true — oddzwonienie zakładaj więc tylko wtedy, gdy answered ma wartość false. Domyślnie wyłączone — żeby je dostawać, dodaj call.missed do zdarzeń endpointu. Endpoint, który doda je później, może dostać też takie połączenia z ostatnich 7 dni, więc sprawdzaj call_created_at. Wysyłane najwyżej raz na rozmowę. Kolejność nie jest gwarantowana: jeśli dla tego samego call_id istnieje call.completed (nagranie dotarło z opóźnieniem albo rozmowa trwała ponad dwie godziny), rozmowę opisuje call.completed, niezależnie od tego, które przyszło pierwsze; żeby widzieć takie rozmowy, subskrybuj oba zdarzenia. Usunięcie w Heilo ogłaszamy zdarzeniem call.deletion_scheduled albo call.recording.deleted tylko dla rozmowy, która miała nagranie; połączenie bez nagrania nie dostaje zdarzenia usunięcia, więc w razie potrzeby usuń swoją kopię sam. Rozmowy, do których dodano Heilo, nie są tu uwzględniane. Zapier i Make: przycisk Test wysyła kształt call.completed; żeby zobaczyć próbkę call.missed, zadzwoń na swój numer w Heilo, rozłącz się, zanim ktoś odbierze, i odczekaj około dwóch godzin.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
direction'inbound'Kierunek rozmowy.
customer_phone_e164string | nullNumer klienta do dopasowania kontaktu w CRM-ie; null, jeśli niedostępny w call.completed.
customer_phone_nationalstring | nullTen sam numer klienta w formacie krajowym, gotowy do wklejenia w pole telefonu w CRM-ie; null, gdy zapisana wartość nie jest numerem — na przykład przy zastrzeżonym numerze.
company_phone_e164string | nullNumer, na który ta rozmowa przyszła albo z którego wyszła. Zwykle Twój numer w Heilo; przy przekierowaniu to Twój własny numer, który ją przekazał. Służy do kierowania notatek, gdy masz więcej niż jeden numer; null, gdy nie został zapisany.
call_created_atstring (ISO 8601) | nullKiedy rozmowa została zapisana w Heilo (ISO 8601). To nie to samo co created_at koperty, które jest momentem wysyłki zdarzenia i przy naprawie może być późniejsze o dni.
app_urlstring | nullTrwały odnośnik do rozmowy w Heilo. W odróżnieniu od recording_url nie wygasa, więc można go trzymać w rekordzie CRM-a. Otwarcie wymaga zalogowania do Heilo.
reason'no_recording' | 'capture_refused' | 'no_speech' | 'not_transcribed'Dlaczego nie ma transkrypcji: no_recording — nic nie zostało zarejestrowane (nikt nie odebrał i nikt nie zostawił wiadomości, dzwoniący rozłączył się przed rozpoczęciem rejestrowania albo rejestrowanie było wtedy wyłączone dla tego numeru); capture_refused — Heilo celowo nie rejestrowało rozmowy (Twój plan lub okres próbny nie obejmuje rejestrowania albo numer jest na liście „Bez rejestrowania”); no_speech — nagranie było za krótkie, żeby zmieścić wiadomość (najwyżej trzy sekundy); not_transcribed — nagranie jest, ale nie udało się z niego przygotować użytecznej transkrypcji. Czy ktoś odebrał, mówi pole answered. Mogą dojść nowe wartości.
has_recordingbooleantrue, gdy istnieje nagranie tej rozmowy; klucz API z uprawnieniem read.recordings pobierze link do niego z GET /calls/:id/recording-url.
answeredbooleantrue, gdy połączenie zostało przełączone i odebrane, na przykład rozmowa, której Heilo nie zarejestrowało; false, gdy nikt nie odebrał. Oddzwonienie zakładaj tylko przy false.
call.missed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.missed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "customer_phone_e164": "+447700900123",
    "customer_phone_national": "07700 900123",
    "company_phone_e164": "+48222630000",
    "call_created_at": "2026-09-08T10:00:00Z",
    "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reason": "no_recording",
    "has_recording": false,
    "answered": false
  }
}
call.outbound.attemptedWysyłane, gdy próba połączenia wychodzącego osiągnie stan końcowy — także nieudany. completed oznacza, że rozmowa się odbyła i zakończyła normalnie; nagranie i transkrypcja przyjdą osobnymi zdarzeniami.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
agent_user_idstring (uuid)Identyfikator użytkownika Heilo, który dzwonił.
customer_phonestringWybierany numer klienta.
customer_phone_e164stringNumer klienta do dopasowania kontaktu w CRM-ie; null, jeśli niedostępny w call.completed.
outbound_lifecycle'completed' | 'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate'Stan końcowy, który wywołał zdarzenie; completed oznacza, że rozmowa się odbyła i zakończyła normalnie.
durationnumber | nullCzas rozmowy w sekundach; null, gdy połączenie nie doszło do skutku przy nawiązywaniu albo czas nie jest jeszcze znany.
attempted_atstring (ISO 8601)Moment wysłania zdarzenia (ISO 8601).
has_recordingbooleantrue tylko wtedy, gdy outbound_lifecycle to completed i rozmowa nie była w trybie no_recording — nagranie przyjdzie wtedy jako call.recording.ready.
call.outbound.attempted
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.outbound.attempted",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "agent_user_id": "2ce127a0-c621-483d-b576-e68f69d95e84",
    "customer_phone": "+447700900123",
    "customer_phone_e164": "+447700900123",
    "outbound_lifecycle": "completed",
    "duration": 95,
    "attempted_at": "2026-09-08T10:00:00Z",
    "has_recording": true
  }
}
call.recording.readyWysyłane, gdy plik nagrania jest gotowy. Użyj, jeśli CRM ma pobierać lub archiwizować audio.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
recording_urlstring | nullLink do nagrania, ważny 7 dni; w rzadkich przypadkach null, gdy nie udało się wygenerować linku. Po wygaśnięciu pobierz świeży link z GET /calls/:id/recording-url.
durationnumber | nullCzas trwania w sekundach; null, gdy jeszcze nieznany.
call.recording.ready
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.recording.ready",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
    "duration": 87
  }
}
call.transcribedWysyłane w tym samym przebiegu co call.completed — zawiera wyłącznie transkrypcję, bez danych rozmowy i linku do nagrania.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
transcript_originalstring | nullSurowa, dosłowna transkrypcja; null, gdy niedostępna.
transcript_processedobjectPrzetworzona analiza rozmowy — patrz spis pól transcript_processed w tej sekcji.
outcomestring | nullKod wyniku w chwili zbudowania zdarzenia (zobacz kody wyniku niżej); null, gdy nikt go nie ustawił. Klucza brakuje w odtworzeniu starszego zdarzenia albo gdy Heilo nie mogło go odczytać. Późniejsze call.outcome.changed ma pierwszeństwo.
outcome_source'ai' | 'user' | nullKto ustawił wynik: ai (wybrała analiza), user (wybrał lub potwierdził człowiek) albo null (nikt). Brakuje zawsze, gdy brakuje outcome.
call.transcribed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.transcribed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
    "transcript_processed": {
      "caller_name": "Alicja Testowa",
      "counterparty_name": null,
      "counterparty_email": null,
      "caller_location": "Warszawa, Mokotów",
      "client_address": "ul. Przykładowa 10",
      "client_city": "Warszawa",
      "client_country": "Poland",
      "service_needed": "Tynki gipsowe w mieszkaniu 65m²",
      "services_match": true,
      "preferred_date": "w przyszłym tygodniu",
      "additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
      "lead_score": 7,
      "summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
      "subject": "Wycena tynków — Warszawa, 65 m²",
      "detected_language": "pl"
    },
    "outcome": "quote_to_send",
    "outcome_source": "ai"
  }
}
call.failedWysyłane, gdy połączenie wychodzące nie doszło do skutku (brak odpowiedzi, zajęte, błąd przy nawiązywaniu). Dotyczy tylko połączeń wychodzących. Zwykle nie warto tworzyć wtedy leada — wystarczy odnotować próbę kontaktu.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
outbound_lifecycle'agent_only' | 'agent_no_answer' | 'customer_no_answer' | 'failed_to_initiate'Który etap połączenia wychodzącego się nie powiódł.
failure_reasonstring | nullTechniczny kod przyczyny (np. customer_busy, agent_no_confirmation albo carrier_rejected, gdy operator odrzucił połączenie do telefonu handlowca); może być null.
call.failed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.failed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "outbound_lifecycle": "customer_no_answer",
    "failure_reason": "customer_busy"
  }
}
call.outbound.lifecycle_repairedWysyłane, gdy Heilo koryguje wstecznie stan rozmowy wychodzącej (późny sygnał od operatora potwierdził, że rozmowa jednak się odbyła). Zaktualizuj stan rozmowy po swojej stronie.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
previous_lifecycle'agent_only'Stan przed korektą; obecnie zawsze agent_only.
new_lifecycle'completed'Stan po korekcie; obecnie zawsze completed.
repaired_atstring (ISO 8601)Moment korekty (ISO 8601).
call.outbound.lifecycle_repaired
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.outbound.lifecycle_repaired",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "previous_lifecycle": "agent_only",
    "new_lifecycle": "completed",
    "repaired_at": "2026-09-08T10:00:00Z"
  }
}
call.deletion_scheduledRODO art. 17: rozmowa jest zaplanowana do usunięcia. CRM powinien przestać używać nagrania i przygotować się na usunięcie danych. Dostajesz informację o rozmowie tylko wtedy, gdy Heilo ma zapis, że jej treść mogła trafić na Twój adres. Samo zapisanie się na zdarzenia usunięcia nie czyni Cię odbiorcą — nie ma czego usuwać, jeśli nigdy nic nie dostałeś.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
pending_deletion_atstring (ISO 8601)Kiedy dane zostaną trwale usunięte (ISO 8601).
reason'consent_not_asked' | 'consent_withdrawn' | 'retention_expired' | 'user_erasure'Powód zaplanowania usunięcia.
call.deletion_scheduled
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.deletion_scheduled",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "pending_deletion_at": "2026-09-09T10:00:00Z",
    "reason": "retention_expired"
  }
}
call.recording.deletedRODO: nagranie zostało usunięte — recording_url zwraca 410. Usuń albo wyłącz link do nagrania po swojej stronie. Gdy `reason` jest inny niż `retention_expired`, skasowane są też transkrypcja, podsumowanie, dane wyciągnięte z rozmowy i notatki do rozmowy — usuń je u siebie tak samo. Rozmowy przeniesione do kosza przychodzą jako to zdarzenie z powodem `user_erasure` 30 dni po przeniesieniu. Dostajesz informację o rozmowie tylko wtedy, gdy Heilo ma zapis, że jej treść mogła trafić na Twój adres, więc to nie jest komplet wszystkich usunięć w Twojej organizacji. Odpowiedź 2xx oznacza, że instrukcja dotarła, nigdy że kopia zniknęła.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
reasonstring | nullPowód zapisany przy planowaniu usunięcia; może być null.
recording_sidstring | nullIdentyfikator nagrania w Twilio; null, gdy nie dało się go ustalić.
deletion_kind'hard_deleted' | 'twilio_404'hard_deleted = usunięte przez Heilo; twilio_404 = plik już wcześniej zniknął po stronie Twilio.
deleted_atstring (ISO 8601)Moment usunięcia nagrania (ISO 8601).
call.recording.deleted
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.recording.deleted",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "reason": "user_erasure",
    "recording_sid": null,
    "deletion_kind": "twilio_404",
    "deleted_at": "2026-09-08T10:00:00Z"
  }
}
call.followup_email.draftedWysyłane po przetworzeniu rozmowy dwustronnej, gdy Heilo przygotowało szkic maila follow-up z jej ustaleń. Nie jest wysyłane dla poczty głosowej ani wtedy, gdy szkicu nie udało się przygotować. Heilo NIGDY nie wysyła tego maila do rozmówcy — szkic trafia do handlowca, który go przegląda i wysyła sam.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
subjectstringTemat maila, gotowy do wklejenia.
bodystringTreść maila zwykłym tekstem, BEZ podpisu — podpis dokłada handlowiec przy wysyłce.
languagestringJęzyk szkicu: wykryty język rozmowy, a gdy nie udało się go wykryć — język konta ustawiony w Heilo (nie język numeru).
call.followup_email.drafted
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.followup_email.drafted",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "subject": "Oferta po rozmowie",
    "body": "Dzień dobry, przesyłam ustalenia naszej rozmowy.",
    "language": "pl"
  }
}
call.outcome.changedWysyłany za każdym razem, gdy zmienia się wynik rozmowy: ktoś wybiera, zmienia, potwierdza lub czyści go w Heilo albo ponowna analiza zmienia wynik wybrany wcześniej. Pierwszy wynik wybrany przy pierwszej analizie nagrania nie ma własnego zdarzenia, przychodzi w call.completed i call.transcribed; wynik wybrany po raz pierwszy dopiero przy ponownej analizie dostaje call.outcome.changed. Nie jest wysyłany dla rozmów w koszu ani zaplanowanych do usunięcia. Zdarzenia zmiany mają pierwszeństwo przed wynikiem z call.completed i call.transcribed; porządkuj je według data.changed_at.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
outcomestring | nullWynik po zmianie; null, gdy go wyczyszczono lub wycofano.
outcome_source'ai' | 'user' | nullKto ustawił go po zmianie: ai, user albo null. Pusty wynik z user oznacza, że wyczyścił go człowiek; pusty wynik z null oznacza, że analiza wycofała swój wybór.
previous_outcomestring | nullWynik przed zmianą; null, gdy go nie było.
previous_outcome_source'ai' | 'user' | nullKto ustawił poprzedni wynik: ai, user albo null.
changed_atstring (ISO 8601)Kiedy zmianę zapisano (ISO 8601). Po tym polu porządkuj zdarzenia zmiany: aktualne jest to z najpóźniejszym changed_at. To nie jest created_at z koperty.
call.outcome.changed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.outcome.changed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "outcome": "booking",
    "outcome_source": "user",
    "previous_outcome": "quote_to_send",
    "previous_outcome_source": "ai",
    "changed_at": "2026-09-08T10:05:00Z"
  }
}
call.user_notes.changedWysyłany, gdy zmienią się wpisy, które ktoś zapisał przy rozmowie w Heilo („Notatki do rozmowy”): dodanie, edycja albo usunięcie wpisu. data.notes to CAŁA aktualna lista, a nie różnica, więc CRM podmienia swoją kopię zamiast ją łączyć. Zdarzenie wychodzi około pięciu minut po ostatniej zmianie (przy wpisach pisanych w trakcie rozmowy: około pięciu minut po rozmowie) i nigdy częściej niż raz na pięć minut dla jednej rozmowy. data.revision rośnie z każdą zmianą; odrzuć listę, której revision nie jest wyższe niż to, które już masz (ręczne ponowne wysłanie przysyła starszą listę jeszcze raz). Nie jest wysyłany dla rozmów w koszu ani zaplanowanych do usunięcia.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
revisionintegerLicznik, który rośnie z każdą zmianą wpisów przy rozmowie. Zapamiętaj najwyższe revision dla rozmowy i odrzucaj listy, których revision nie jest wyższe; ręczne ponowne wysłanie i odtworzenie przysyłają starszą listę.
changed_atstring (ISO 8601)Kiedy Heilo zbudowało tę listę (ISO 8601). To nie jest created_at z koperty ani chwila, w której ktoś edytował wpis.
notesobject[]Cała aktualna lista wpisów, od najstarszego, najwyżej 200; pusta, gdy usunięto ostatni wpis. Podmień nią swoją kopię.
notes[].idstring (uuid)Identyfikator wpisu; nie zmienia się po edycji tekstu.
notes[].bodystringTekst wpisu, od 1 do 2000 znaków.
notes[].source'live' | 'after' | 'legacy'live: wpisany na ekranie rozmowy w jej trakcie. after: dopisany później w Heilo. legacy: dawna jedna notatka do rozmowy sprzed 28.10.2026, przeniesiona do wpisów. Mogą dojść nowe wartości.
notes[].author.idstring (uuid) | nullUżytkownik Heilo, który napisał wpis. Null dla wpisu legacy albo gdy to konto zostało usunięte.
notes[].author.namestring | nullImię i nazwisko autora z jego profilu w Heilo; null, gdy profil ich nie ma. Nigdy adres e-mail. Późniejsza zmiana nazwiska pojawi się w kolejnej liście, bez osobnego zdarzenia.
notes[].noted_atstring (ISO 8601)Kiedy człowiek to zapisał (ISO 8601); dla wpisu live to chwila w trakcie rozmowy.
notes[].recording_offset_secondsinteger | nullSekundy od początku nagrania, tylko dla wpisu pisanego w trakcie rozmowy w obrębie nagrania; w pozostałych przypadkach null.
notes[].created_atstring (ISO 8601)Kiedy wpis zapisano (ISO 8601).
notes[].updated_atstring (ISO 8601)Ostatnia edycja tekstu (ISO 8601).
call.user_notes.changed
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.user_notes.changed",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "revision": 3,
    "changed_at": "2026-09-08T10:12:00Z",
    "notes": [
      {
        "id": "f3b0c1d2-4e5f-4a6b-8c7d-9e0f1a2b3c4d",
        "body": "Klient prosi o telefon po 10:00.",
        "source": "live",
        "author": {
          "id": "2ce127a0-c621-483d-b576-e68f69d95e84",
          "name": "Anna Nowak"
        },
        "noted_at": "2026-09-08T10:01:12Z",
        "recording_offset_seconds": 72,
        "created_at": "2026-09-08T10:01:12Z",
        "updated_at": "2026-09-08T10:01:12Z"
      }
    ]
  }
}
call.tracker.matchedWysyłany, gdy co najmniej jeden skonfigurowany tracker słów kluczowych pasuje do przetworzonej transkrypcji. Dopasowanie zawiera znalezione terminy i fragmenty; brak fragmentu oznacza pustą tablicę.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
matchesobject[]Trackery dopasowane w tej rozmowie.
matches[].tracker_idstring (uuid)Identyfikator skonfigurowanego trackera.
matches[].namestringNazwa trackera.
matches[].matched_termsstring[]Dopasowane terminy.
matches[].excerptsstring[]Fragmenty transkrypcji; tablica może być pusta.
call.tracker.matched
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "call.tracker.matched",
  "resource_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "matches": [
      {
        "tracker_id": "cd794362-6117-44d1-b487-c5e7e1ea9082",
        "name": "Oferta",
        "matched_terms": [
          "ofertę"
        ],
        "excerpts": [
          "Proszę o ofertę w przyszłym tygodniu."
        ]
      }
    ]
  }
}
contact.createdWysyłane po utworzeniu nowego kontaktu w Heilo. data.contact to pełny obraz nowego kontaktu; nie zawiera notatek ani tagów.
PoleTypOpis
contactobjectPełny obraz nowego kontaktu (pola poniżej).
contact.idstring (uuid)Identyfikator kontaktu w Heilo.
contact.phonestringNumer telefonu kontaktu.
contact.first_namestring | nullnull, jeśli nie podano.
contact.last_namestring | nullnull, jeśli nie podano.
contact.emailstring | nullnull, jeśli nie podano.
contact.companystring | nullnull, jeśli nie podano.
contact.created
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "contact.created",
  "resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "contact": {
      "id": "86c68698-d54c-43e7-bbbc-328499b98d12",
      "phone": "+447700900123",
      "first_name": "Alicja",
      "last_name": "Testowa",
      "email": "alicja@example.com",
      "company": null
    }
  }
}
contact.updatedWysyłane po edycji kontaktu. W przeciwieństwie do contact.created to nie jest pełny obraz: data.diff zawiera tylko zmienione pola.
PoleTypOpis
contact_idstring (uuid)Identyfikator zaktualizowanego kontaktu.
diffobject (partial)Tylko zmienione pola — klucze nieobecne w diff nie były modyfikowane.
contact.updated
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "contact.updated",
  "resource_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "contact_id": "86c68698-d54c-43e7-bbbc-328499b98d12",
    "diff": {
      "company": "Example",
      "notes": "Oddzwonić",
      "tags": [
        "oferta"
      ]
    }
  }
}

Możliwe klucze w diff: first_name, last_name, email, phone, company, notes, tags

webhook.testWysyłany wyłącznie po naciśnięciu Test przy odbiorcy. resource_id to ID odbiorcy, nie rozmowy. data zawiera syntetyczny payload call.completed i trzy znaczniki testowe opisane poniżej. Test nie potwierdza dostępności prawdziwego audio.
PoleTypOpis
call_idstring (uuid)ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy.
direction'inbound' | 'outbound'Kierunek rozmowy.
caller_phonestring | nullZapisany numer dzwoniącego; null, jeśli niedostępny w call.completed.
customer_phone_e164string | nullNumer klienta do dopasowania kontaktu w CRM-ie; null, jeśli niedostępny w call.completed.
customer_phone_nationalstring | nullTen sam numer klienta w formacie krajowym, gotowy do wklejenia w pole telefonu w CRM-ie; null, gdy zapisana wartość nie jest numerem — na przykład przy zastrzeżonym numerze.
company_phone_e164string | nullNumer, na który ta rozmowa przyszła albo z którego wyszła. Zwykle Twój numer w Heilo; przy przekierowaniu to Twój własny numer, który ją przekazał. Służy do kierowania notatek, gdy masz więcej niż jeden numer; null, gdy nie został zapisany.
call_created_atstring (ISO 8601) | nullKiedy rozmowa została zapisana w Heilo (ISO 8601). To nie to samo co created_at koperty, które jest momentem wysyłki zdarzenia i przy naprawie może być późniejsze o dni.
app_urlstring | nullTrwały odnośnik do rozmowy w Heilo. W odróżnieniu od recording_url nie wygasa, więc można go trzymać w rekordzie CRM-a. Otwarcie wymaga zalogowania do Heilo.
durationnumberDługość nagrania w sekundach.
recording_urlstring | nullLink do nagrania, ważny 7 dni; null, gdy nagranie nie było jeszcze zapisane w chwili przetwarzania. Po wygaśnięciu pobierz świeży link z GET /calls/:id/recording-url.
transcript_processedobjectPrzetworzona analiza rozmowy — patrz spis pól transcript_processed w tej sekcji.
transcript_originalstring | nullSurowa, dosłowna transkrypcja; null, gdy niedostępna.
outcomestring | nullKod wyniku w chwili zbudowania zdarzenia (zobacz kody wyniku niżej); null, gdy nikt go nie ustawił. Klucza brakuje w odtworzeniu starszego zdarzenia albo gdy Heilo nie mogło go odczytać. Późniejsze call.outcome.changed ma pierwszeństwo.
outcome_source'ai' | 'user' | nullKto ustawił wynik: ai (wybrała analiza), user (wybrał lub potwierdził człowiek) albo null (nikt). Brakuje zawsze, gdy brakuje outcome.
_testtrueZawsze true — odróżnia wiadomość testową od prawdziwych zdarzeń.
_messagestringCzytelna informacja, że to test.
_sent_atstring (ISO 8601)Moment wysłania testu (ISO 8601).
webhook.test
{
  "api_version": "2026-06-15",
  "event_id": "1bf3a5e2-4f82-4335-988e-4e044fa648d4",
  "event_type": "webhook.test",
  "resource_id": "c2d38cc8-bc1d-4336-91ea-51b8a549a882",
  "created_at": "2026-09-08T10:00:00Z",
  "data": {
    "call_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "direction": "inbound",
    "caller_phone": "+447700900123",
    "customer_phone_e164": "+447700900123",
    "customer_phone_national": "07700 900123",
    "company_phone_e164": "+48222630000",
    "call_created_at": "2026-09-08T10:00:00Z",
    "app_url": "https://www.heilo.io/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "duration": 87,
    "recording_url": "https://www.heilo.io/api/v1/calls/3fa85f64-5717-4562-b3fc-2c963f66afa6/recording.mp3?token=EXAMPLE&exp=1789466400",
    "transcript_processed": {
      "caller_name": "Alicja Testowa",
      "counterparty_name": null,
      "counterparty_email": null,
      "caller_location": "Warszawa, Mokotów",
      "client_address": "ul. Przykładowa 10",
      "client_city": "Warszawa",
      "client_country": "Poland",
      "service_needed": "Tynki gipsowe w mieszkaniu 65m²",
      "services_match": true,
      "preferred_date": "w przyszłym tygodniu",
      "additional_details": "Klient wspomniał o terminie do końca czerwca. Druga rozmowa po wycenie.",
      "lead_score": 7,
      "summary": "Prośba o wycenę tynków gipsowych w mieszkaniu 65 m² na Mokotowie.",
      "subject": "Wycena tynków — Warszawa, 65 m²",
      "detected_language": "pl"
    },
    "transcript_original": "Proszę o ofertę w przyszłym tygodniu.",
    "outcome": "quote_to_send",
    "outcome_source": "ai",
    "_test": true,
    "_message": "Synthetic webhook test; do not create CRM records.",
    "_sent_at": "2026-09-08T10:00:00Z"
  }
}

transcript_processed — spis pól

Stabilny podzbiór pól, na którym możesz polegać przy mapowaniu do CRM-a. Każde pole jest opcjonalne — ma wartość null, gdy rozmowa nie zawierała tej informacji.

PoleTypOpis
caller_namestring | nullImię i nazwisko rozmówcy, jeśli je podał.
summarystring | nullKrótkie podsumowanie rozmowy.
subjectstring | nullJednolinijkowy tytuł rozmowy (do 80 znaków).
service_neededstring | nullCzego dotyczyła prośba rozmówcy.
services_matchboolean | nullCzy prośba pasuje do usług, które oferujesz.
lead_scorenumber | null (1–10)Ocena jakości leada od 1 do 10 albo null, gdy AI nie dało oceny.
preferred_datestring | nullTermin wspomniany przez rozmówcę, jeśli padł.
client_citystring | nullMiasto, jeśli padło w rozmowie.
client_addressstring | nullAdres, jeśli padł w rozmowie.
additional_detailsstring | nullDodatkowy kontekst z rozmowy.

Pola, które mogą się pojawić

PoleTypOpis
caller_locationstring | nullOdniesienie geograficzne wykryte w rozmowie.
client_countrystring | nullKraj, jeśli padł w rozmowie.
counterparty_namestring | nullNazwa drugiej strony — tylko w rozmowach wychodzących i w rozmowach na żywo, do których dodano Heilo.
counterparty_emailstring | nullAdres e-mail klienta, który padł w rozmowie i zgadza się z transkrypcją — tylko w rozmowach, do których dodano Heilo.
detected_languagestringKod języka rozmowy (np. pl); klucz może w ogóle nie wystąpić.
proposal_itemsobject[] | nullZaproponowane działania i decyzje wyciągnięte z rozmowy.

Analiza może zawierać dodatkowe pola — traktuj nieznane pola jako opcjonalne i nie zakładaj ich obecności.

Planowane funkcje

Te adresy API planujemy dodać w kolejnych wydaniach. Kolejność zależy od potrzeb klientów.

  • GET /contacts — lista kontaktów
  • POST /contacts — tworzenie kontaktu (synchronizacja z CRM-a do Heilo)
  • POST /calls — zainicjuj połączenie wychodzące z Twojego numeru Heilo; rozmowa jest nagrywana, transkrybowana i trafia do Twojego CRM-a jak każda inna

Brakuje konkretnego adresu API? Napisz na support@heilo.io i opisz, co chcesz zautomatyzować.

Planowane funkcje

Brakuje konkretnego adresu API? Napisz na support@heilo.io i opisz, co chcesz zautomatyzować.

Zarządzaj kluczami i webhookami w panelu

Po zalogowaniu wygenerujesz klucze API, dodasz odbiorców webhooków i sprawdzisz historię wysyłek.