# Kanały niestandardowe Połącz dowolną platformę komunikacyjną lub narzędzie do przesyłania wiadomości z platformą, korzystając z kanałów niestandardowych. Pozwala to na przesyłanie wiadomości z platform takich jak widżety czatu na żywo na stronach internetowych, systemy poczty e-mail, systemy CRM lub dowolne inne usługi do Twojej skrzynki odbiorczej — i odpowiadanie na nie za pomocą Twojego Agenta AI. --- ## Czym są kanały niestandardowe? Kanały niestandardowe rozszerzają możliwości platformy poza jej wbudowane platformy komunikacyjne ([WhatsApp](whatsapp-business.md), [SMS](sms.md), [Instagram](instagram-dms.md), [Messenger](facebook-messenger.md)). Dzięki kanałom niestandardowym możesz: - **Odbierać wiadomości** z dowolnej zewnętrznej platformy w ujednoliconej skrzynce odbiorczej platformy. - **Wysyłać odpowiedzi** z aplikacji z powrotem do zewnętrznej platformy automatycznie. - **Używać Agenta AI** do odpowiadania na wiadomości z dowolnego źródła. - **Śledzić wszystkie konwersacje** wraz z innymi kanałami w jednej skrzynce odbiorczej. Jest to idealne rozwiązanie dla firm, które korzystają ze specjalistycznych narzędzi komunikacyjnych, posiadają własną, niestandardową platformę lub chcą mieć wszystkie wiadomości od klientów w jednym miejscu. ::: note **Uwaga:** Kanały niestandardowe wymagają pewnej konfiguracji technicznej. Jeśli Ty lub Twój zespół nie czujecie się pewnie w integracjach technicznych, warto poprosić o pomoc w tej sekcji swojego programistę lub zespół IT. ::: --- ## Jak to działa Kanały niestandardowe działają poprzez przesyłanie wiadomości między Twoją zewnętrzną platformą a platformą przy użyciu **webhooków** (zautomatyzowanych wiadomości przesyłanych między systemami przez internet). Oto przebieg procesu: ``` Your Platform ──(sends message to)──> The App | AI Agent responds Contact saved Message stored | The App ──(sends reply to)──> Your Platform ``` 1. **Wiadomości przychodzące:** Twoja zewnętrzna platforma wysyła wiadomości na adres internetowy (URL). Pomyśl o tym jak o „wysyłaniu” wiadomości przez Twoją platformę do skrzynki pocztowej platformy. 2. **Przetwarzanie:** Platforma tworzy lub aktualizuje kontakt, zapisuje wiadomość i zleca Agentowi AI wygenerowanie odpowiedzi (jeśli jest aktywny). 3. **Wiadomości wychodzące:** Gdy platforma wysyła odpowiedź (niezależnie od tego, czy pochodzi ona od AI, czy została wpisana przez Ciebie), wysyła wiadomość na adres URL w Twojej platformie, skąd Twój system może dostarczyć ją do użytkownika końcowego. --- ## Konfiguracja wiadomości przychodzących (Twoja platforma do aplikacji) Aby wysyłać wiadomości z zewnętrznej platformy do aplikacji, Twoja platforma musi przesyłać dane na poniższy adres URL. Twój programista rozpozna to jako standardowe żądanie POST (powszechny sposób przesyłania danych między systemami przez internet). ### Gdzie wysyłać wiadomości ``` POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY ``` Zastąp `YOUR_API_KEY` swoim kluczem API (prywatnym kodem, który potwierdza platformie, że Twoja platforma ma uprawnienia do wysyłania wiadomości). Znajdziesz go lub wygenerujesz w sekcji **Ustawienia → Integracje → Klucz API**. ### Format wiadomości Wyślij dane wiadomości w następującym formacie (JSON): ```json { "customData": { "messageSid": "unique-message-id-123", "fromId": "user-456", "toId": "your-business-id", "body": "Hello, I have a question about your service.", "status": "received", "channel": "my-live-chat", "campaignId": "optional-campaign-id", "firstName": "John", "lastName": "Doe", "email": "john@example.com", "mediaUrl": null, "mediaContentType": null }, "messageType": "text" } ``` **Co oznacza każda część:** - `messageSid` - Unikalny identyfikator tej konkretnej wiadomości (tworzony przez Twój system). Służy do zapobiegania dwukrotnemu przetworzeniu tej samej wiadomości. - `fromId` - Kto wysłał wiadomość (może to być identyfikator użytkownika, adres e-mail lub numer telefonu z Twojego systemu). - `toId` - Twój identyfikator biznesowy (może to być dowolna wybrana przez Ciebie etykieta). - `body` - Właściwa treść wiadomości. - `channel` - Wybrana przez Ciebie etykieta identyfikująca źródło wiadomości (np. "website-chat", "email"). ### Pełna dokumentacja pól | Pole | Wymagane? | Opis działania | |---|---|---| | `customData.messageSid` lub `customData.id` | Tak | Unikalny identyfikator wiadomości (zapobiega duplikatom) | | `customData.fromId` | Tak | Identyfikuje nadawcę wiadomości (np. identyfikator użytkownika, e-mail lub numer telefonu z Twojego systemu) | | `customData.toId` | Tak | Identyfikuje stronę odbierającą (Twoją firmę). Może to być dowolny wybrany tekst. | | `customData.body` | Tak | Właściwa treść wiadomości. Nie może być pusta. | | `customData.status` | Nie | Status wiadomości. Pozostaw puste, aby użyć wartości domyślnej (`"received"`). | | `customData.channel` | Nie | Etykieta źródła (np. `"live-chat"`, `"email"`, `"my-crm"`). Pomaga zidentyfikować pochodzenie wiadomości w skrzynce odbiorczej. | | `customData.campaignId` | Nie | Identyfikator kampanii/agenta. Użyj tego, aby skierować wiadomość do konkretnej konfiguracji AI. | | `customData.firstName` | Nie | Imię kontaktu. Uwzględniane podczas tworzenia nowego rekordu kontaktu. | | `customData.lastName` | Nie | Nazwisko kontaktu. Uwzględniane podczas tworzenia nowego rekordu kontaktu. | | `customData.email` | Nie | Adres e-mail kontaktu. Uwzględniane podczas tworzenia nowego rekordu kontaktu. | | `customData.mediaUrl` | Nie | Link do załączonego pliku (obraz, wideo, audio lub dokument). Może to być również plik zakodowany w base64 (patrz poniżej). | | `customData.mediaContentType` | Nie | Typ pliku (np. `"image/jpeg"`, `"video/mp4"`, `"audio/ogg"`, `"application/pdf"`). Wymagane, jeśli dołączasz `mediaUrl`. | | `messageType` | Nie | Typ wiadomości. Pozostaw puste dla zwykłego tekstu. Ustaw na `"reaction"` dla reakcji emoji. | ### Reakcje emoji Jeśli Twoja platforma obsługuje reakcje emoji (na przykład kciuk w górę przy wiadomości), wysyłaj je jako reakcję, a nie jako wiadomość tekstową: ustaw `messageType` na `"reaction"` i umieść tylko emoji w `customData.body`. ```json { "messageType": "reaction", "customData": { "messageSid": "reaction-123", "fromId": "user-42", "toId": "my-business", "body": "👍" } } ``` Asystent potraktuje to wtedy w oczekiwany sposób: - Reakcja na pytanie zadane przez asystenta (na przykład „Czy czwartek pasuje?”) jest traktowana jako odpowiedź, na którą asystent odpowie. - Reakcja na wiadomość kończącą (na przykład „Do usłyszenia!”) kończy rozmowę w sposób dyskretny. Żadna odpowiedź nie jest wysyłana. Jeśli Twoja platforma zamienia reakcje na tekst, taki jak „Zareagowano: 👍”, asystent widzi zwykłą wiadomość tekstową i samodzielnie decyduje, czy odpowiedzieć. Wysłanie typu reakcji pozwala tego uniknąć. ### Co otrzymasz w odpowiedzi Poprawne żądanie zwraca: ```json { "success": true, "messageId": "1234567890" } ``` Jeśli coś pójdzie nie tak, otrzymasz komunikat o błędzie wyjaśniający problem: ```json { "error": "Message body cannot be empty" } ``` ### Kody statusu | Kod | Co to oznacza | |---|---| | `200` | Sukces - wiadomość odebrana i przetwarzana | | `400` | Coś jest nie tak z Twoim żądaniem - sprawdź, czy nie brakuje wymaganych pól lub czy treść wiadomości nie jest pusta | | `401` | Nieprawidłowy klucz API - sprawdź klucz w sekcji **Ustawienia → Integracje → Klucz API** | | `405` | Błędna metoda żądania - upewnij się, że używasz POST, a nie GET | | `500` | Wystąpił błąd po stronie platformy - spróbuj ponownie za chwilę | > Jeśli ustawisz `customData.status`, jedyną akceptowaną wartością jest `"received"` — pozostaw to pole puste, aby użyć wartości domyślnej, zamiast wysyłać cokolwiek innego, w przeciwnym razie otrzymasz `400`. --- ## Wysyłanie załączników multimedialnych (obrazy, wideo, pliki) Do wiadomości możesz dołączać pliki (obrazy, wideo, audio, dokumenty). Można to zrobić na dwa sposoby: ### Opcja 1: Link do pliku Jeśli plik jest już hostowany online, podaj adres URL (adres internetowy), z którego platforma może go pobrać: ```json { "customData": { "messageSid": "msg-789", "fromId": "user-456", "toId": "business-1", "body": "Here is a photo of the issue.", "channel": "support-portal", "mediaUrl": "https://example.com/uploads/photo.jpg", "mediaContentType": "image/jpeg" }, "messageType": "text" } ``` ### Opcja 2: Bezpośrednie osadzenie pliku (Base64) Jeśli plik nie jest hostowany online, możesz osadzić go bezpośrednio w wiadomości jako tekst zakodowany (format base64). Jest to powszechne w integracjach technicznych, w których system generuje pliki w locie. Platforma automatycznie zdekoduje i zapisze plik: ```json { "customData": { "messageSid": "msg-790", "fromId": "user-456", "toId": "business-1", "body": "Screenshot attached.", "channel": "support-portal", "mediaUrl": "data:image/png;base64,iVBORw0KGgo...", "mediaContentType": "image/png" }, "messageType": "text" } ``` ::: note **Uwaga:** Osadzanie plików bezpośrednio sprawia, że dane wiadomości stają się znacznie większe. W przypadku dużych plików lepiej jest hostować plik online i wysłać link (Opcja 1). ::: --- ## Konfigurowanie wiadomości wychodzących (platforma do Twojej platformy) Gdy platforma wysyła odpowiedź na kanale niestandardowym (niezależnie od tego, czy pochodzi ona od AI, czy została wpisana przez Ciebie), automatycznie wysyła ją na adres URL w Twojej platformie, aby Twój system mógł dostarczyć ją użytkownikowi końcowemu. > **Najpierw ustaw adres URL webhooka.** Musisz zapisać adres URL webhooka kanału niestandardowego, zanim jakiekolwiek odpowiedzi będą mogły zostać dostarczone. Jeśli żaden adres URL nie zostanie zapisany, odpowiedzi będą nadal generowane i przechowywane, ale nigdy nie zostaną wysłane — i **nie** będą wyświetlać statusu „Niepowodzenie”, więc nic w Twojej skrzynce odbiorczej nie zasygnalizuje problemu. Zawsze konfiguruj adres URL webhooka przed uruchomieniem usługi. ### Poinformuj aplikację, gdzie wysyłać odpowiedzi 1. Na lewym pasku bocznym kliknij **Ustawienia** (Settings) w pobliżu dołu. 2. Na lewym panelu ustawień, w sekcji **Kanały** (Channels), kliknij **Kanały** (Channels). 3. Znajdź kartę **Kanał niestandardowy** (Custom channel) na samym dole strony (za Android SMS Gateway, iMessage, widżetem czatu na stronie, kontem Twilio i zgodnością z przepisami). 4. Wprowadź **adres URL webhooka** (Webhook URL) — adres URL w Twojej platformie, na który AI powinna wysyłać wiadomości wychodzące (Twój programista konfiguruje to tak, aby odbierać i przetwarzać odpowiedzi). Musi to być **publiczny adres HTTPS URL** — adresy `http://` i hosty niepubliczne są odrzucane. 5. Kliknij **Zapisz** (Save). ### Co platforma wysyła do Twojej platformy Gdy platforma wysyła odpowiedź, Twoja platforma otrzyma następujące dane: ```json { "contactId": "abc123", "messageId": "msg-456", "userId": "your-user-id", "body": "Thank you for your message! Here is the information you requested...", "toId": "user-456", "channel": "my-live-chat" } ``` ### Co oznacza każde pole | Pole | Co zawiera | |---|---| | `contactId` | wewnętrzny identyfikator tego kontaktu na platformie | | `messageId` | Unikalny identyfikator tej wiadomości w aplikacji | | `userId` | Twój identyfikator użytkownika | | `body` | Treść odpowiedzi | | `toId` | Identyfikator kontaktu na Twojej platformie (odpowiada on `fromId` wysłanemu w wiadomości przychodzącej) | | `channel` | Przypisana etykieta kanału niestandardowego | Twoja platforma otrzymuje te dane i wykorzystuje je do dostarczenia odpowiedzi użytkownikowi końcowemu za pośrednictwem Twojego własnego systemu. ### Jak platforma śledzi dostarczanie Po wysłaniu odpowiedzi do Twojej platformy, platforma aktualizuje status wiadomości: - **Wysłano** - Twoja platforma pomyślnie odebrała wiadomość. - **Niepowodzenie** - Twoja platforma zwróciła błąd lub nie można było się z nią połączyć. Platforma przechowuje szczegóły błędu wraz z wiadomością, aby umożliwić Ci rozwiązanie problemu. --- ## Wysyłanie wiadomości z Twojego systemu do aplikacji Oprócz odbierania wiadomości możesz również wysyłać wiadomości wychodzące za pośrednictwem niestandardowego kanału bezpośrednio z własnego systemu. Jest to przydatne, gdy chcesz rozpocząć rozmowę lub wysłać wiadomość proaktywną. > **Wymagania planu.** Wysyłanie i synchronizowanie wiadomości przez API wymaga planu obejmującego dostęp do API oraz co najmniej jeden kanał komunikacji. Jeśli otrzymasz błąd `403` „permission denied / feature not enabled”, oznacza to, że Twój obecny plan nie obejmuje tej funkcji — zmień plan na wyższy lub skontaktuj się z pomocą techniczną. ### Gdzie wysyłać ``` POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY ``` ### Format wiadomości ```json { "customData": { "fromId": "user-456", "customChannel": "my-live-chat", "body": "Hello! How can I help you today?", "campaignId": "optional-campaign-id", "firstName": "John", "lastName": "Doe", "email": "john@example.com" } } ``` ### Wymagane pola | Pole | Opis działania | |---|---| | `customData.fromId` | Identyfikator kontaktu na Twojej platformie | | `customData.customChannel` | Nazwa Twojego niestandardowego kanału (np. „my-live-chat”) | | `customData.body` | Treść wiadomości do wysłania | Pola opcjonalne (`campaignId`, `firstName`, `lastName`, `email`) działają tak samo jak w przypadku wiadomości przychodzących — pomagają platformie utworzyć lub zaktualizować rekord kontaktu. ### Co otrzymasz w odpowiedzi ```json { "success": true, "messageId": "generated-message-id", "contactId": "contact-id", "message": "Message sent successfully" } ``` --- ## Rejestrowanie wiadomości wysłanych z innego systemu Czasami wiadomość została już wysłana do kontaktu z innego narzędzia (na przykład w ramach przepływu pracy w innej platformie) i po prostu chcesz, aby platforma o tym wiedziała, dzięki czemu sztuczna inteligencja będzie miała pełny kontekst. Różni się to od wysyłania: platforma rejestruje wiadomość, ale **nie** dostarcza jej ponownie do kontaktu. ### Gdzie wysyłać ``` POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY ``` Uwzględnij `customData.fromId` (identyfikator kontaktu na Twojej platformie) oraz `customData.body` (treść wiadomości, która została już wysłana). ### Jak to działa - **Wiadomość jest rejestrowana, a nie wysyłana ponownie.** Platforma przechowuje ją w konwersacji wyłącznie w celach kontekstowych. - **Sztuczna inteligencja jest domyślnie wstrzymana dla tego kontaktu.** Zapobiega to sytuacji, w której bot odpowiada na wiadomość, którą zajął się już człowiek. Aby utrzymać aktywność bota, przekaż `customData.pauseAi: false`. - **Nowe kontakty mogą być tworzone automatycznie.** Dołącz `customData.customChannel`, a kontakt zostanie utworzony, jeśli jeszcze nie istnieje. - **Duplikaty są ignorowane.** Jeśli użyjesz ponownie tego samego `messageSid`, platforma rozpozna, że wiadomość została już zarejestrowana i nie wprowadzi żadnych zmian. > **Wymagania planu.** Podobnie jak wysyłanie, rejestrowanie wiadomości przez API wymaga planu obejmującego dostęp do API oraz co najmniej jeden kanał przesyłania wiadomości. Błąd `403` „permission denied / feature not enabled” oznacza, że Twój obecny plan tego nie obejmuje. --- ## Przykłady z życia wzięte ### Czat na żywo na stronie internetowej Połącz widżet czatu na żywo na swojej stronie internetowej z platformą, aby Twój Agent AI mógł odpowiadać na pytania odwiedzających: 1. Odwiedzający wpisuje wiadomość w widżecie czatu na Twojej stronie. 2. Twój widżet czatu wysyła wiadomość do platformy. 3. Agent AI generuje odpowiedź. 4. Odpowiedź jest odsyłana do widżetu czatu, który wyświetla ją odwiedzającemu. **Dlaczego jest to przydatne:** Odwiedzający Twoją stronę otrzymują natychmiastowe odpowiedzi generowane przez AI na swoje pytania, bez konieczności bycia przez Ciebie online. ### E-mail Kieruj konwersacje e-mailowe przez platformę, aby Twój Agent AI mógł odpowiadać na wiadomości e-mail: 1. Skonfiguruj system, który przekazuje przychodzące wiadomości e-mail do platformy (używając adresu nadawcy e-mail jako `fromId`, tematu i treści wiadomości jako `body` oraz `"email"` jako `channel`). 2. Agent AI odczytuje wiadomość e-mail i generuje odpowiedź. 3. Odpowiedź jest odsyłana do Twojego systemu pocztowego, który wysyła ją jako standardową odpowiedź e-mail. **Dlaczego jest to przydatne:** Typowe pytania przesyłane e-mailem (o cennik, godziny pracy, dostępność) są natychmiastowo obsługiwane przez Twojego Agenta AI. > Jeśli Twój system pocztowy obsługuje IMAP/SMTP lub OAuth, wbudowany [kanał e-mail](email.md) może być prostszym rozwiązaniem niż niestandardowa integracja. ### Integracja z CRM Połącz swój istniejący system CRM (zarządzania relacjami z klientami) z platformą: 1. Gdy potencjalny klient wyśle wiadomość przez Twój system CRM, przekaż ją do platformy. 2. Agent AI odpowie i będzie śledzić konwersację. 3. Odpowiedź AI zostanie odesłana do Twojego systemu CRM w celu dostarczenia. 4. Pełna historia konwersacji będzie dostępna zarówno na platformie, jak i w Twoim systemie CRM. **Dlaczego jest to przydatne:** Twój zespół sprzedaży otrzymuje odpowiedzi wspomagane przez AI dla potencjalnych klientów bez opuszczania systemu CRM. ### System zgłoszeń wsparcia Użyj platformy jako wspieranego przez AI pierwszego punktu kontaktu w obsłudze klienta: 1. Twój system zgłoszeń przesyła nowe zgłoszenia do platformy. 2. Agent AI wysyła wstępną odpowiedź (np. potwierdzenie otrzymania zgłoszenia i prośbę o doprecyzowanie). 3. Odpowiedź zostaje dołączona do zgłoszenia w Twoim systemie wsparcia. 4. Twój zespół wsparcia może przejrzeć odpowiedź AI i przejąć sprawę, gdy zajdzie taka potrzeba. **Dlaczego jest to przydatne:** Klienci otrzymują natychmiastowe potwierdzenie i wstępną pomoc, nawet poza godzinami pracy. --- ## Rozwiązywanie problemów ### Wiadomości nie są odbierane przez platformę - Sprawdź, czy Twój klucz API jest poprawny i aktywny (sprawdź **Ustawienia → Integracje → Klucz API**). - Upewnij się, że wysyłasz żądanie POST (nie GET). Twój programista będzie znał różnicę. - Sprawdź, czy pole `customData.body` nie jest puste lub nie zawiera tylko białych znaków. - Zweryfikuj, czy pole `customData.fromId` zostało uwzględnione. - Przeczytaj treść komunikatu odpowiedzi, aby uzyskać szczegółowe informacje o błędzie. ### Odpowiedzi nie docierają do Twojej platformy - Upewnij się, że wprowadziłeś adres URL swojej platformy w karcie **Kanał niestandardowy** na stronie Kanały. Jeśli żaden adres URL nie zostanie zapisany, odpowiedzi są generowane i przechowywane, ale nigdy nie są wysyłane — i **nie** zostaną oznaczone jako „Nieudane”, więc sprawdź to w pierwszej kolejności. - Zweryfikuj, czy adres URL jest publicznie dostępny (nie znajduje się za logowaniem lub zaporą sieciową) i zwraca odpowiedź o powodzeniu. - Do Twojego adresu URL wysyłane są tylko odpowiedzi (wiadomości wychodzące) — wiadomości przychodzące nie wyzwalają tego procesu. - Sprawdź szczegóły błędu przy wiadomości w swojej skrzynce odbiorczej. ### Kontakt nie jest tworzony - Upewnij się, że wartość `fromId` jest spójna dla tego samego użytkownika we wszystkich jego wiadomościach. Platforma używa tej wartości do identyfikacji kontaktów — jeśli zmieni się ona między wiadomościami, platforma za każdym razem utworzy nowy kontakt. - Uwzględnij `firstName`, `lastName` oraz `email` w pierwszej wiadomości od nowego kontaktu, aby utworzyć kompletny rekord kontaktu. ### Załączniki multimedialne nie działają - W przypadku linków do plików (URL) upewnij się, że plik jest publicznie dostępny (dostęp do niego nie wymaga logowania). - Zawsze dołączaj `mediaContentType`, gdy dołączasz `mediaUrl`. - W przypadku plików osadzonych (base64) zweryfikuj, czy format to `data:MIME_TYPE;base64,ENCODED_DATA`. - Upewnij się, że określony typ pliku odpowiada rzeczywistej zawartości pliku. --- ## Dobre praktyki - **Używaj spójnych wartości `fromId`.** Każdy użytkownik na Twojej platformie powinien zawsze mieć ten sam `fromId`. Dzięki temu platforma grupuje wszystkie jego wiadomości w jedną konwersację zamiast tworzyć zduplikowane kontakty. - **Wybierz jasną nazwę `channel`.** Wybierz coś opisowego, np. `"website-chat"`, `"email"` lub `"zendesk"`, aby łatwo było zidentyfikować źródło wiadomości podczas przeglądania skrzynki odbiorczej. - **Uwzględnij dane kontaktowe** (`firstName`, `lastName`, `email`) w pierwszej wiadomości od nowego kontaktu. Pozwala to od razu utworzyć kompletny i użyteczny rekord kontaktu. - **Zaimplementuj logikę ponawiania prób.** Skonfiguruj swoją platformę tak, aby ponawiała wysyłkę wiadomości, jeśli platforma nie odpowie za pierwszym razem (problemy z siecią się zdarzają). - **Używaj unikalnych wartości `messageSid`** dla każdej wiadomości. Zapobiega to dwukrotnemu przetworzeniu tej samej wiadomości, jeśli Twój system wyśle ją więcej niż raz. - **Używaj `campaignId`**, aby kierować wiadomości do różnych Agentów AI, gdy masz wiele przypadków użycia (np. zapytania sprzedażowe kontra pytania techniczne). - **Przetestuj przed uruchomieniem.** Wyślij wiadomości testowe w obu kierunkach i sprawdź, czy kontakty, konwersacje i odpowiedzi AI działają poprawnie, zanim udostępnisz rozwiązanie prawdziwym użytkownikom.