Integracje i webhooki

Integracje przekazują zdarzenia firmy do innej usługi od razu, gdy się pojawią: nową rozmowę, rezerwację, prośbę o członka zespołu, zgłoszenie. Dzięki Zapier lub Make możesz na przykład dodać wiersz do arkusza, wysłać wiadomość na czacie albo utworzyć kartę w CRM bez ręcznego kopiowania danych.

Gdzie to znaleźć

W górnym menu otwórz „Moduły”, podłącz moduł „Integracje” (domyślnie jest wyłączony) i kliknij „Otwórz integracje” na jego karcie. Otworzy się zakładka „Webhooki”, obok niej jest zakładka „Dziennik zdarzeń”. Sekcję otwierają tylko Właściciel i Administrator: adres odbiorcy może zawierać prywatny token. Gdy moduł jest wyłączony, nic nie jest dostarczane, a zdarzenia z tego czasu nie zostaną wysłane później. Odbiorcy pozostają skonfigurowani, a dziennik zdarzeń jest nadal prowadzony.

Jak dodać odbiorcę

1. W Zapier utwórz Zap z wyzwalaczem „Webhooks by Zapier” i zdarzeniem „Catch Hook”, a następnie skopiuj podany adres. W Make dodaj moduł „Custom webhook” i skopiuj jego adres.
2. Na stronie integracji wypełnij pola „Nazwa” (na przykład nazwa Zapa) i „Adres odbiorcy” (skopiowany adres).
3. W polu „Zdarzenia do wysłania” zaznacz, co wysyłać.
4. Kliknij „Dodaj odbiorcę”.
5. Sekret podpisu pojawia się tylko raz. Skopiuj go i przechowuj bezpiecznie. Zapier i Make go nie potrzebują; własny serwer używa go do sprawdzania podpisu. Jeśli go zgubisz, utwórz nowy przez „Zmień sekret”.
6. Na karcie odbiorcy kliknij „Wyślij test”. Wynik to Dostarczono lub Nie dostarczono wraz z powodem.

Adres musi być publiczny i zaczynać się od https. Odrzucane są, z podaniem powodu: adresy http, adresy IP zamiast domeny, niestandardowe porty, adresy z loginem i hasłem, adresy wewnętrzne i adresy w domenach ReceptionWorks. Strona pokazuje tylko domenę i ścieżkę adresu: część po znaku zapytania może zawierać token odbiorcy.

Jakie zdarzenia są wysyłane

• „Nowa rozmowa” (conversation.started): klient rozpoczął nową rozmowę w dowolnym kanale. Rozmowy testowe i zablokowani klienci nie są wysyłani.
• „Poproszono o członka zespołu” (conversation.handoff_requested): pracownik AI lub system poprosił o członka zespołu. Zdarzenie zawiera powód: prośbę samego pracownika AI, wstrzymane automatyczne odpowiedzi, tryb ręczny, niedostępnego pracownika AI, wyczerpany limit odpowiedzi lub nieaktywny plan.
• „Przekazano rozmowę członkowi zespołu” (conversation.handed_off): członek zespołu przejął rozmowę. Wysyłane za każdym razem.
• „Nowa rezerwacja”, „Zmieniono rezerwację” i „Anulowano rezerwację” (booking.created, booking.changed, booking.cancelled): rezerwację utworzył, zmienił lub anulował pracownik AI, Ty w kalendarzu albo asystent biznesowy.
• „Nowe zgłoszenie” (support_case.created) i „Zmieniono zgłoszenie” (support_case.updated): utworzono zgłoszenie albo zmienił się jego status, priorytet lub opis. Wewnętrzne notatki zespołu nie są wysyłane.
• „Nowa wiadomość” (message.created): każda wiadomość widoczna dla klienta, wysyłana, gdy tylko zostanie napisana: od klienta, pracownika AI, członka zespołu lub systemu (komunikat w rozmowie). Zawiera tekst wiadomości.
• „Cała rozmowa” (conversation.transcript): cała rozmowa, wysyłana, gdy przez 30 minut nie było w niej wiadomości. Jeśli rozmowa trwa dalej, jest wysyłana ponownie po każdej kolejnej przerwie.

Zdarzenia z czatu testowego nie są wysyłane. Odbiorca dostaje tylko zdarzenia, które nastąpiły po jego dodaniu i gdy jest włączony: to, co wydarzyło się podczas pauzy lub wyłączenia, nie jest wysyłane później.

„Nowa wiadomość” i „Cała rozmowa” zawierają pełny tekst rozmów, także to, co piszą klienci. Tekst opuszcza ReceptionWorks i trafia do wybranego przez Ciebie odbiorcy, więc zaznaczaj je tylko dla odbiorców, którym ufasz. Nowy odbiorca zaczyna z tymi dwoma niezaznaczonymi. Są wysyłane tylko wtedy, gdy jakiś odbiorca je zaznaczył, i nie pojawiają się w dzienniku zdarzeń ani w jego eksporcie: sama rozmowa jest w skrzynce odbiorczej. Rozmowy testowe i zablokowani klienci nie są wysyłani.

Co otrzymuje odbiorca

Każde zdarzenie to żądanie POST z treścią JSON. Przykład prośby o członka zespołu zgłoszonej przez pracownika AI:

{
  "schema_version": "business-webhook.v1",
  "id": "5b0c5e2e-0000-4000-8000-000000000001",
  "type": "conversation.handoff_requested",
  "occurred_at": "2026-10-07T09:30:00.000Z",
  "business": { "name": "Example Studio" },
  "actor": { "kind": "ai_employee" },
  "channel": "telegram",
  "employee": { "name": "Anna" },
  "conversation": { "url": "https://app.example.com/businesses/studio/inbox?conversation=example" },
  "customer": { "name": "Maria", "email": "maria@example.com", "phone": "+1 555 0100" },
  "booking": null,
  "handoff": { "reason": "ai_request", "reason_text": "The customer wants to discuss a discount" },
  "support_case": null
}

• id: identyfikator zdarzenia. Przy kolejnych próbach się nie zmienia, więc ignoruj id, które już przetworzono.
• type: typ zdarzenia z powyższej listy; occurred_at: czas w UTC.
• business: nazwa Twojej firmy.
• actor: kto wywołał zdarzenie. kind to customer, ai_employee, team_member (członek zespołu lub asystent biznesowy) albo system.
• channel: web, telegram, instagram, whatsapp lub messenger, albo null, gdy zdarzenie nie ma rozmowy.
• employee: imię pracownika AI albo null, gdy działał zespół lub asystent biznesowy.
• conversation.url: link do rozmowy; otwiera się dla zalogowanych członków zespołu. null, gdy nie ma rozmowy.
• customer: imię, e-mail i telefon w chwili wysyłki albo null. Dane kontaktowe są wysyłane w całości, dlatego dodawaj tylko odbiorców, którym ufasz.
• booking: tylko w zdarzeniach rezerwacji: service, starts_at, ends_at, status i location.
• handoff: tylko dla „Poproszono o członka zespołu”: reason (ai_request, automation_stopped, manual_mode, ai_unavailable, quota_exhausted lub plan_inactive) i reason_text — własne wyjaśnienie pracownika AI albo null.
• support_case: tylko w zdarzeniach zgłoszeń: subject, status (open, in_progress, waiting_customer, resolved lub closed) i priority (low, normal, high lub urgent).
• message: tylko dla „Nowa wiadomość”: id, sequence (miejsce wiadomości w rozmowie), author (customer, ai_employee, team_member lub system), text, created_at i attachments: lista z kind (zawsze image), name i media_type. Wysyłane są tylko nazwa i typ załącznika, bez samego pliku.
• transcript: tylko dla „Cała rozmowa”: message_count (wiadomości w rozmowie), truncated i messages: wiadomości w tej samej postaci co message. Zapis zawiera co najwyżej 500 najnowszych wiadomości i 512 KiB tekstu; truncated ma wartość true, gdy pominięto starsze wiadomości.

Sekcje, które nie dotyczą zdarzenia, mają wartość null. Zdarzenie z „Wyślij test” ma typ webhook.test, a wszystkie sekcje poza business mają wartość null. Dane nie zawierają przetłumaczonego tekstu: nazwy są takie, jak zapisano, kody to stałe angielskie słowa, a czas jest w UTC.

"message": {
  "id": "6c1d0f52-0000-4000-8000-000000000002",
  "sequence": 12,
  "author": "customer",
  "text": "Hello, can I book for Friday?",
  "created_at": "2026-10-07T09:29:41.000Z",
  "attachments": [{ "kind": "image", "name": "photo.jpg", "media_type": "image/jpeg" }]
}

Wiadomości i zapisy rozmów mogą docierać w złej kolejności i się powtarzać, więc nie polegaj na kolejności dotarcia. Użyj sequence, aby odtworzyć kolejność wiadomości w rozmowie, a dostawę z już przetworzonym webhook-id odrzuć. Zapis rozmowy powtarza wiadomości, które mogłeś już dostać pojedynczo: użyj go, aby sprawdzić lub odbudować całą rozmowę.

Jak sprawdzić podpis

Każde żądanie ma trzy nagłówki standardu Standard Webhooks: webhook-id, webhook-timestamp i webhook-signature. Zapier i Make ich nie sprawdzają. Na własnym serwerze użyj oficjalnej biblioteki Standard Webhooks dla swojego języka: przekaż jej sekret dokładnie tak, jak jest pokazany (zaczyna się od whsec_), niezmienioną surową treść żądania i trzy nagłówki. Sprawdzenie ręczne:

signed_content = webhook-id + "." + webhook-timestamp + "." + raw request body
signature      = "v1," + base64( HMAC-SHA256( key, signed_content ) )
key            = base64-decoded part of the secret after "whsec_"

Nagłówek webhook-signature zawiera v1, i podpis. Po „Zmień sekret” zawiera dwa podpisy oddzielone spacją: przyjmij żądanie, jeśli pasuje którykolwiek. Odrzucaj żądania, których znacznik czasu różni się od Twojego zegara o więcej niż pięć minut.

Ponawianie i automatyczne wyłączenie

Odbiorca musi odpowiedzieć kodem 2xx w ciągu 10 sekund. Przekierowania nie są wykonywane: adres, który przekierowuje, jest traktowany jako błąd. W przeciwnym razie ReceptionWorks próbuje ponownie: od razu, potem po 1 minucie, 5 minutach, 30 minutach, 2 godzinach, 6 godzinach i 12 godzinach. To 7 prób w około 21 godzin. Jeśli wszystkie zawiodą, dostawa dostaje w „Dziennik dostaw” status Nie dostarczono i możesz kliknąć „Wyślij ponownie”. Ponowienia niosą ten sam webhook-id, więc odbiorca może odrzucać duplikaty.

Odbiorca jest wyłączany automatycznie, gdy odpowie, że adres już nie istnieje (kod 410), albo gdy pięć zdarzeń z rzędu nie zostanie dostarczonych. Na karcie pojawia się wtedy „Wyłączony automatycznie” z powodem, a zespół dostaje powiadomienie. Popraw adres i kliknij „Włącz”: zdarzenia pominięte w międzyczasie nie są wysyłane.

Pauza, nowy sekret, usuwanie

• „Wstrzymaj” wstrzymuje wysyłanie bez usuwania odbiorcy; kliknij „Włącz”, aby kontynuować.
• „Zmień sekret”, a potem „Utwórz nowy sekret”: nowy sekret jest pokazywany raz. Stary działa jeszcze 24 godziny, aby można było zaktualizować odbiorcę bez utraty zdarzeń.
• „Usuń”, a potem „Usuń odbiorcę” usuwają odbiorcę na stałe.

Warto wiedzieć

• Integracjami zarządzają tylko Właściciel i Administrator. Firma może mieć do 5 odbiorców.
• Dziennik dostaw pokazuje zdarzenie, odbiorcę, czas, status, próby i następną próbę. Nie przechowuje treści żądań.
• Test przyciskiem „Wyślij test” nie tworzy wpisu w dzienniku i nie wymaga prawdziwego zdarzenia.

Co dalej

• Dziennik zdarzeń i eksport
• Wiadomości: rozmowy z klientami
• Zespół i role