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.
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.
- Przygotuj adres URL w CRM-ie, Zapierze, Make albo własnym systemie, na który Heilo ma wysyłać dane.
- W Heilo dodaj odbiorcę na zdarzenie call.completed. Opcjonalnie dodaj też call.outbound.attempted, jeśli chcesz śledzić próby połączeń wychodzących.
- Odbieraj call.completed i sprawdzaj podpis Heilo-Signature, żeby upewnić się, że wiadomość przyszła z Heilo.
- Nie twórz duplikatów: zapisuj event_id z nagłówka heilo-event-id. data.call_id oznacza konkretną rozmowę.
- 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.calls | Odczyt rozmów: GET /api/v1/calls, GET /api/v1/calls/:id |
| read.recordings | Wydanie 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.transcripts | Dodaje 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_keys | Zarezerwowane 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" }
}| HTTP | code | Znaczenie |
|---|---|---|
| 400 | BAD_REQUEST | Niepoprawne parametry zapytania lub treści (ogólna walidacja) |
| 401 | UNAUTHORIZED | Brak lub niepoprawny klucz API |
| 402 | SUBSCRIPTION_INACTIVE | Subskrypcja nieaktywna — odnów płatność, aby znów włączyć klucz |
| 403 | FORBIDDEN | Klucz API nie ma potrzebnego uprawnienia |
| 404 | NOT_FOUND | Zasób nie istnieje lub znajduje się poza organizacją przypisaną do klucza API. |
| 400 | VALIDATION_ERROR | Parametr nie przeszedł sprawdzenia (np. phone nie jest numerem telefonu) |
| 429 | RATE_LIMITED | Przekroczono limit zapytań |
| 500 | DATABASE_ERROR | Błąd serwera lub bazy — można spróbować ponownie później |
| 503 | MAINTENANCE | Publiczne API jest tymczasowo wyłączone |
| 503 | SERVICE_UNAVAILABLE | Część 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 |
| 503 | WEBHOOK_ACTIVATION_LOCKED | Włączanie subskrypcji webhooków jest wstrzymane na czas migracji; istniejące subskrypcje działają dalej — spróbuj później |
| 422 | SUBSCRIPTION_LIMIT | Organizacja 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ą.
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", "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
| Parametr | Typ | Wartości |
|---|---|---|
| page | int | od 1 (domyślnie 1) |
| limit | int | 1–100 (domyślnie 20) |
| direction | enum | inbound | outbound |
| status | enum | new | to_call | contacted | qualified |
| dateFrom / dateTo | string | data 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 |
| phone | string | numer klienta z rozmowy, z numerem kierunkowym kraju; spacje, myślniki i wiodący + są opcjonalne, np. +48 600 100 200 |
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",
"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.
curl https://www.heilo.io/api/v1/calls/<id> \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"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.
curl https://www.heilo.io/api/v1/calls/<id>/recording-url \ -H "Authorization: Bearer hk_live_AbC1MnPq..."
{
"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.
| Dane | REST | Webhook |
|---|---|---|
| Metadane rozmowy: kierunek, numery, czas trwania, data | jest | jest |
| Status w CRM-ie i status przeglądu | jest | brak |
| Wynik rozmowy i kto go ustawił | jest | jest |
| Notatki do rozmowy (w REST tylko w GET /calls/:id) | jest | jest |
| Podsumowanie, imię dzwoniącego, potrzeba klienta | jest | jest |
| Pozostałe pola analizy: miasto, adres, ocena leada, preferowany termin, język | częściowo: GET /calls/:id ma miasto, ocenę leada i język; adres i preferowany termin tylko w webhooku | jest |
| Zapis rozmowy słowo w słowo | tak, GET /calls/:id z read.transcripts | jest |
| Link do nagrania | jest, przez /calls/:id/recording-url | jest, 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.
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ć.
- Przygotuj nowy sekret w ustawieniach odbiorcy. Pokazujemy go raz, a on czeka na aktywację przez 24 godziny.
- Zainstaluj nowy sekret OBOK obecnego — Twój odbiornik musi akceptować podpis zrobiony którymkolwiek z nich.
- 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.
- Aktywuj rotację.
- 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 techniczna | Opis |
|---|---|
| call.completed | Zakończona rozmowa, transkrypcja gotowa |
| call.missed | Połączenie przychodzące zakończone bez transkrypcji (nieodebrane, bez wiadomości albo niezarejestrowane) |
| call.outbound.attempted | Próba połączenia wychodzącego osiągnęła stan końcowy (rozmowa lub niepowodzenie) |
| call.recording.ready | Nagranie gotowe do pobrania |
| call.transcribed | Transkrypcja gotowa |
| call.failed | Rozmowa nieudana (zajęte / brak odpowiedzi / błąd) |
| call.outbound.lifecycle_repaired | Korekta statusu rozmowy wychodzącej |
| call.deletion_scheduled | Rozmowa zaplanowana do usunięcia (RODO) |
| call.recording.deleted | Nagranie usunięte (RODO) |
| call.followup_email.drafted | Draft maila follow-up gotowy |
| call.outcome.changed | Ustawiono lub zmieniono wynik rozmowy |
| call.user_notes.changed | Dodano, zmieniono lub usunięto notatki do rozmowy |
| call.tracker.matched | Wzmianka o śledzonej frazie |
| contact.created | Nowy kontakt utworzony |
| contact.updated | Kontakt 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"
}
}| Pole | Typ | Opis |
|---|---|---|
| call_id | string (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_phone | string | null | Zapisany numer dzwoniącego; null, jeśli niedostępny w call.completed. |
| customer_phone_e164 | string | null | Numer klienta do dopasowania kontaktu w CRM-ie; null, jeśli niedostępny w call.completed. |
| customer_phone_national | string | null | Ten 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_e164 | string | null | Numer, 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_at | string (ISO 8601) | null | Kiedy 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_url | string | null | Trwał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. |
| duration | number | Długość nagrania w sekundach. |
| recording_url | string | null | Link 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_processed | object | Przetworzona analiza rozmowy — patrz spis pól transcript_processed w tej sekcji. |
| transcript_original | string | null | Surowa, dosłowna transkrypcja; null, gdy niedostępna. |
| outcome | string | null | Kod 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' | null | Kto 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.
| Kod | Znaczenie |
|---|---|
| booking | Umówiono rezerwację, wizytę lub termin. |
| cancellation_or_reschedule | Dzwoniący odwołał albo prosi o nowy termin. |
| information_request | Dzwoniący pytał o informacje. |
| quote_to_send | Dzwoniący czeka na ofertę lub wycenę. |
| awaiting_customer_decision | Klient się zastanawia i sam da znać. |
| deal_won | Klient zgodził się w rozmowie kupić, zamówić lub przyjął ofertę. Automatyzację „wygrana” w CRM-ie uruchamiaj tylko przy outcome_source równym user. |
| callback_scheduled | Ustalono ponowny kontakt. |
| not_interested | Dzwoniący nie jest zainteresowany. |
| spam_wrong_number | Pusta wiadomość, spam lub pomyłka. |
| new_opportunity | Nowa szansa sprzedaży.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach |
| existing_deal_update | Aktualizacja istniejącego projektu.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach |
| follow_up | Kolejny kontakt po wcześniejszej rozmowie.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach |
| no_answer | Nikt nie odebrał.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach |
| voicemail | Dzwoniący zostawił wiadomość głosową.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach |
| support | Zgłoszenie do obsługi klienta.dawny: już nieoferowany, może jeszcze występować w starszych rozmowach |
| complaint | Reklamacja.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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (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_e164 | string | null | Numer klienta do dopasowania kontaktu w CRM-ie; null, jeśli niedostępny w call.completed. |
| customer_phone_national | string | null | Ten 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_e164 | string | null | Numer, 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_at | string (ISO 8601) | null | Kiedy 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_url | string | null | Trwał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_recording | boolean | true, gdy istnieje nagranie tej rozmowy; klucz API z uprawnieniem read.recordings pobierze link do niego z GET /calls/:id/recording-url. |
| answered | boolean | true, 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. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| agent_user_id | string (uuid) | Identyfikator użytkownika Heilo, który dzwonił. |
| customer_phone | string | Wybierany numer klienta. |
| customer_phone_e164 | string | Numer 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. |
| duration | number | null | Czas rozmowy w sekundach; null, gdy połączenie nie doszło do skutku przy nawiązywaniu albo czas nie jest jeszcze znany. |
| attempted_at | string (ISO 8601) | Moment wysłania zdarzenia (ISO 8601). |
| has_recording | boolean | true tylko wtedy, gdy outbound_lifecycle to completed i rozmowa nie była w trybie no_recording — nagranie przyjdzie wtedy jako call.recording.ready. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| recording_url | string | null | Link 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. |
| duration | number | null | Czas trwania w sekundach; null, gdy jeszcze nieznany. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| transcript_original | string | null | Surowa, dosłowna transkrypcja; null, gdy niedostępna. |
| transcript_processed | object | Przetworzona analiza rozmowy — patrz spis pól transcript_processed w tej sekcji. |
| outcome | string | null | Kod 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' | null | Kto ustawił wynik: ai (wybrała analiza), user (wybrał lub potwierdził człowiek) albo null (nikt). Brakuje zawsze, gdy brakuje outcome. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (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_reason | string | null | Techniczny kod przyczyny (np. customer_busy, agent_no_confirmation albo carrier_rejected, gdy operator odrzucił połączenie do telefonu handlowca); może być null. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (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_at | string (ISO 8601) | Moment korekty (ISO 8601). |
{
"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ś.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| pending_deletion_at | string (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. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| reason | string | null | Powód zapisany przy planowaniu usunięcia; może być null. |
| recording_sid | string | null | Identyfikator 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_at | string (ISO 8601) | Moment usunięcia nagrania (ISO 8601). |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| subject | string | Temat maila, gotowy do wklejenia. |
| body | string | Treść maila zwykłym tekstem, BEZ podpisu — podpis dokłada handlowiec przy wysyłce. |
| language | string | Język szkicu: wykryty język rozmowy, a gdy nie udało się go wykryć — język konta ustawiony w Heilo (nie język numeru). |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| outcome | string | null | Wynik po zmianie; null, gdy go wyczyszczono lub wycofano. |
| outcome_source | 'ai' | 'user' | null | Kto 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_outcome | string | null | Wynik przed zmianą; null, gdy go nie było. |
| previous_outcome_source | 'ai' | 'user' | null | Kto ustawił poprzedni wynik: ai, user albo null. |
| changed_at | string (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. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| revision | integer | Licznik, 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_at | string (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. |
| notes | object[] | Cała aktualna lista wpisów, od najstarszego, najwyżej 200; pusta, gdy usunięto ostatni wpis. Podmień nią swoją kopię. |
| notes[].id | string (uuid) | Identyfikator wpisu; nie zmienia się po edycji tekstu. |
| notes[].body | string | Tekst 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.id | string (uuid) | null | Użytkownik Heilo, który napisał wpis. Null dla wpisu legacy albo gdy to konto zostało usunięte. |
| notes[].author.name | string | null | Imię 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_at | string (ISO 8601) | Kiedy człowiek to zapisał (ISO 8601); dla wpisu live to chwila w trakcie rozmowy. |
| notes[].recording_offset_seconds | integer | null | Sekundy od początku nagrania, tylko dla wpisu pisanego w trakcie rozmowy w obrębie nagrania; w pozostałych przypadkach null. |
| notes[].created_at | string (ISO 8601) | Kiedy wpis zapisano (ISO 8601). |
| notes[].updated_at | string (ISO 8601) | Ostatnia edycja tekstu (ISO 8601). |
{
"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ę.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (uuid) | ID rozmowy w Heilo. Dla biznesowych zdarzeń rozmowy równe resource_id; w webhook.test jest to syntetyczne ID rozmowy. |
| matches | object[] | Trackery dopasowane w tej rozmowie. |
| matches[].tracker_id | string (uuid) | Identyfikator skonfigurowanego trackera. |
| matches[].name | string | Nazwa trackera. |
| matches[].matched_terms | string[] | Dopasowane terminy. |
| matches[].excerpts | string[] | Fragmenty transkrypcji; tablica może być pusta. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| contact | object | Pełny obraz nowego kontaktu (pola poniżej). |
| contact.id | string (uuid) | Identyfikator kontaktu w Heilo. |
| contact.phone | string | Numer telefonu kontaktu. |
| contact.first_name | string | null | null, jeśli nie podano. |
| contact.last_name | string | null | null, jeśli nie podano. |
| contact.email | string | null | null, jeśli nie podano. |
| contact.company | string | null | null, jeśli nie podano. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| contact_id | string (uuid) | Identyfikator zaktualizowanego kontaktu. |
| diff | object (partial) | Tylko zmienione pola — klucze nieobecne w diff nie były modyfikowane. |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| call_id | string (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_phone | string | null | Zapisany numer dzwoniącego; null, jeśli niedostępny w call.completed. |
| customer_phone_e164 | string | null | Numer klienta do dopasowania kontaktu w CRM-ie; null, jeśli niedostępny w call.completed. |
| customer_phone_national | string | null | Ten 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_e164 | string | null | Numer, 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_at | string (ISO 8601) | null | Kiedy 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_url | string | null | Trwał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. |
| duration | number | Długość nagrania w sekundach. |
| recording_url | string | null | Link 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_processed | object | Przetworzona analiza rozmowy — patrz spis pól transcript_processed w tej sekcji. |
| transcript_original | string | null | Surowa, dosłowna transkrypcja; null, gdy niedostępna. |
| outcome | string | null | Kod 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' | null | Kto ustawił wynik: ai (wybrała analiza), user (wybrał lub potwierdził człowiek) albo null (nikt). Brakuje zawsze, gdy brakuje outcome. |
| _test | true | Zawsze true — odróżnia wiadomość testową od prawdziwych zdarzeń. |
| _message | string | Czytelna informacja, że to test. |
| _sent_at | string (ISO 8601) | Moment wysłania testu (ISO 8601). |
{
"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.
| Pole | Typ | Opis |
|---|---|---|
| caller_name | string | null | Imię i nazwisko rozmówcy, jeśli je podał. |
| summary | string | null | Krótkie podsumowanie rozmowy. |
| subject | string | null | Jednolinijkowy tytuł rozmowy (do 80 znaków). |
| service_needed | string | null | Czego dotyczyła prośba rozmówcy. |
| services_match | boolean | null | Czy prośba pasuje do usług, które oferujesz. |
| lead_score | number | null (1–10) | Ocena jakości leada od 1 do 10 albo null, gdy AI nie dało oceny. |
| preferred_date | string | null | Termin wspomniany przez rozmówcę, jeśli padł. |
| client_city | string | null | Miasto, jeśli padło w rozmowie. |
| client_address | string | null | Adres, jeśli padł w rozmowie. |
| additional_details | string | null | Dodatkowy kontekst z rozmowy. |
Pola, które mogą się pojawić
| Pole | Typ | Opis |
|---|---|---|
| caller_location | string | null | Odniesienie geograficzne wykryte w rozmowie. |
| client_country | string | null | Kraj, jeśli padł w rozmowie. |
| counterparty_name | string | null | Nazwa drugiej strony — tylko w rozmowach wychodzących i w rozmowach na żywo, do których dodano Heilo. |
| counterparty_email | string | null | Adres e-mail klienta, który padł w rozmowie i zgadza się z transkrypcją — tylko w rozmowach, do których dodano Heilo. |
| detected_language | string | Kod języka rozmowy (np. pl); klucz może w ogóle nie wystąpić. |
| proposal_items | object[] | null | Zaproponowane 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.