Jakie endpointy są potrzebne do ujednoliconego inboxu?

GET /v2/accounts/ do pobrania listy kont, potem GET /v2/{account_id}/chats i GET /v2/{account_id}/emails dla każdego konta, a następnie GET /v2/{account_id}/chats/{chat_id}/messages, aby otworzyć rozmowę. Odpowiedzi wysyła się przez POST /v2/{account_id}/chats/{chat_id}/messages/send i POST /v2/{account_id}/emails/send.

Unipile MCP · Ujednolicony inbox

Ujednolicony inbox zbudowany z agentem kodującym

Q: Czy jedno wywołanie API może zwrócić wiadomości ze wszystkich podłączonych kont?

Nie, i to celowo. account_id jest częścią ścieżki, więc wywołuje się endpoint raz na konto i scala wyniki w aplikacji. API ujednolica format obiektów, a nie liczbę wywołań.

Q: Jak działa paginacja przy kilku kontach?

Osobny kursor na konto. Każdy endpoint listy zwraca data, total_count i next_cursor. Wartość next_cursor należy przekazać z powrotem w parametrze cursor i przechowywać w stanie aplikacji mapę kursorów, po jednym na konto.

Q: Jak utrzymać aktualny inbox bez odpytywania?

Za pomocą endpointu webhooka zasubskrybowanego na message.new i email.new. Osobna strona pokazuje, jak agent go podłącza.

Rozmowy z LinkedIn, WhatsApp i e-maila na jednej liście, z odpowiedzią z tego samego ekranu. Wystarczy serwer Unipile MCP, a agent sam napisze pobieranie i scalanie danych.

Zbuduj ujednolicony inbox z agentem Dokumentacja wiadomości

7 dni za darmo, bez karty kredytowej.

Zbuduj ujednolicony inbox dla LinkedIn, WhatsApp i e-maila.

Wykonaj zapytanieGET /v2/accounts/3 konta

Dodano GET /api/inbox: jedno wywołanie na konto, jeden format elementu, sortowanie po dacie.

3 zmienione pliki · 3 kanały na jednej liście

Opisz kolejną funkcję…

Zadanie

Co trzeba zrobić

Pokazać użytkownikom na jednej liście wszystkie rozmowy z kont, które podłączyli, i pozwolić im odpowiadać bez opuszczania produktu. Najpierw uczciwie: account_id jest w ścieżce każdego endpointu, więc ujednolicony inbox to jedno wywołanie na konto, a potem scalenie w aplikacji. API ujednolica format obiektów, a nie liczbę wywołań.

Bez tego Osobny klient dla każdego dostawcy, każdy z innym formatem

Klient LinkedIn, klient WhatsApp i klient e-mail, każdy z własnym modelem i własną paginacją.

Jedno wspólne „Załaduj więcej”, które gubi wiadomości, gdy tylko jednemu kontu skończą się strony wcześniej niż innym.

Odpowiedź wysłana z niewłaściwego konta, bo czat i konto nie były przechowywane razem.

Z serwerem Unipile MCP Efekt w aplikacji

Jedna lista rozmów z LinkedIn, WhatsApp i e-maila, posortowana po dacie, z kanałem oznaczonym etykietą.

„Załaduj więcej”, które przesuwa osobny kursor dla każdego konta i nigdy nie gubi wiadomości.

Odpowiedź prosto z listy, z konta, do którego należy czat, przetestowana w aplikacji Development.

Prompt, kroki, kod

Prompt dla agenta

Dwa prompty, a przy każdym endpointy Unipile, które agent czyta i wywołuje, oraz to, co trafia do projektu. Ścieżki są pełne, względem bazowego URL API https://api.unipile.com, z kluczem przypisanym do Scope w nagłówku X-API-KEY każdego żądania.

Agent · support-consoleAplikacja Development

Zbuduj w tej aplikacji ujednolicony inbox dla LinkedIn, WhatsApp i e-maila: pobierz listę podłączonych kont, dla każdego konta pobierz jedną stronę czatów i jedną stronę e-maili, znormalizuj je do jednego formatu elementu i posortuj po dacie.

Wykonaj zapytanieGET /v2/accounts/3 konta

Wykonaj zapytanieGET /v2/{account_id}/chats200 · next_cursor

Dodano GET /api/inbox: pobiera listę kont, wywołuje GET /v2/{account_id}/chats i GET /v2/{account_id}/emails równolegle, mapuje oba wyniki na jeden typ InboxItem (id, account_id, channel, counterpart, preview, date, unread) i sortuje po dacie. Otwarcie elementu wywołuje endpoint wiadomości danego czatu. Uruchomione w aplikacji Development z testowym kontem LinkedIn, WhatsApp i Gmail.4 zmienione pliki · przetestowane w aplikacji Development

Jedno wywołanie na konto, jeden format elementu, jedno sortowanie

Agent czyta przez serwer schematy Chat i Email, po czym ustala minimalny wspólny format: identyfikator, datę, nadawcę, podgląd i kanał. Wszystko, co specyficzne dla dostawcy, pozostaje dostępne w surowym obiekcie na potrzeby widoku szczegółów. Instagram i Telegram korzystają z tych samych endpointów czatów, więc czwarty kanał to po prostu kolejne konto, a nie kolejny klient.

Endpointy używane przez agenta

GET/v2/accounts/GET/v2/{account_id}/chatsGET/v2/{account_id}/emailsGET/v2/{account_id}/chats/{chat_id}/messagesPOST/v2/{account_id}/chats/{chat_id}/messages/sendPOST/v2/{account_id}/emails/send

Częsty błąd: Szukanie filtra account_id w parametrach zapytania. Jest on w ścieżce: jedno wywołanie na konto, potem scalenie w aplikacji.

Szczegółowo: część LinkedIn

Agent · support-consoleAplikacja Development

Dodaj paginację do ujednoliconego inboxu: przechowuj osobny kursor dla każdego podłączonego konta, przesuwaj każdy niezależnie przy „Załaduj więcej” i zatrzymuj konto, gdy brakuje jego next_cursor.

Odczyt endpointuGET /v2/{account_id}/chatsdata, total_count, next_cursor

Wykonaj zapytanieGET /v2/{account_id}/emails?cursor=…200 OK

Zastąpiono globalny offset strukturą Map<account_id, next_cursor> przechowywaną w stanie inboxu. „Załaduj więcej” równolegle przesuwa każde konto, które wciąż ma kursor, a następnie ponownie sortuje scaloną listę. Konto bez next_cursor jest oznaczane jako wyczerpane i pomijane. Sprawdzone na trzech kontach o różnej wielkości w aplikacji Development.2 zmienione pliki · żadna wiadomość nie ginie przy „Załaduj więcej”

Koperta odpowiedzi jest wszędzie taka sama: data, total_count, next_cursor

Każdy endpoint listy zwraca tę samą kopertę. Wartość next_cursor należy przekazać z powrotem w parametrze cursor i w ten sposób pobrać następną stronę. Kontrakt każe używać kursora, gdy dostawca go obsługuje, w przeciwnym razie parametru offset i zaznacza, że limit to górny limit, a nie gwarancja: o końcu listy świadczy nie krótka strona, lecz brak next_cursor w odpowiedzi.

Endpointy używane przez agenta

GET/v2/{account_id}/chatsGET/v2/{account_id}/emailsGET/v2/{account_id}/chats/{chat_id}/participants

Częsty błąd: Jeden kursor dla całego inboxu. Każde konto paginuje własnym kursorem; wspólny kursor gubi wiadomości, gdy tylko jedno konto skończy się wcześniej niż inne.

Lista na żywo dzięki webhookom

Paginacja

Jedna koperta, osobny kursor na konto

Dosłownie z kontraktu v2, który agent czyta przez serwer. Te same trzy pola wracają z każdego endpointu listy.

1Kopertadata zawiera stronę, total_count jej rozmiar, gdy dostawca go podaje, a next_cursor token następnej strony. Brak next_cursor oznacza koniec listy danego konta.GET https://api.unipile.com/v2/{account_id}/chats?limit=20 { "object": "ChatList", "items": [ … ], "cursor": "…" }

2Kursor czy offsetUżywaj next_cursor zawsze, gdy dostawca go obsługuje, a w przeciwnym razie offset. Kod, który zakłada jedno z dwóch dla każdego dostawcy, przestaje działać przy pierwszej skrzynce IMAP.GET https://api.unipile.com/v2/{account_id}/emails?cursor=…&limit=20 GET https://api.unipile.com/v2/{account_id}/chats?offset=40&limit=20

3Mapa kursorówJeden wpis na konto w stanie aplikacji. „Załaduj więcej” przesuwa każde konto, które wciąż ma kursor, i odrzuca te, które go nie zwróciły.{ "acc_1a…": "eyJ…", "acc_9c…": null, "acc_f2…": "eyJ…" } limit to górny limit, a nie gwarancja

Od Development do produkcji

Najpierw testy w aplikacji Development

Dashboard Unipile oddziela aplikację Development od Production. Agent dostaje klucz przypisany do Scope z Development i jedno konto testowe na kanał: prawdziwe rozmiary stron, żadnego prawdziwego klienta.

1Pobierz jedną stronę na kontoLinkedIn, WhatsApp i konto e-mail scalone w jedną listę posortowaną po dacie.

2Odpowiedz z listyWysyłka idzie z konta, do którego należy czat.

3„Załaduj więcej” przy nierównych kontachŻadna wiadomość nie ginie, wyczerpane konta są pomijane, potem można przełączyć klucz na Production.

crm-app · DevelopmentUżywana przez agenta

Scopedev-tests · 2 konta

Kluczklucz Account API przypisany do Scope

KontaTestowe konto LinkedIn, testowa skrzynka Gmail

Webhooki1 endpoint · zdarzenia wiadomości

crm-app · ProductionNietknięta

Scopejeden na workspace

Kluczklucze przypisane do Scope, tylko w backendzie

Kontawłasne konta użytkowników, przez Hosted Auth

Rozwiązywanie problemów

Częste błędy i ich znaczenie

Cztery błędy, które psują ujednolicony inbox, i rozwiązanie każdego z nich. Trzy dotyczą paginacji.

Szukanie account_id jako filtra w zapytaniu

Oczekiwanie, że jedno wywołanie zwróci wszystkie konta. Rozwiązanieaccount_id jest w ścieżce. Wywołaj endpoint raz na konto i scal wyniki w aplikacji; API ujednolica format, a nie liczbę wywołań.

Jeden kursor dla całego inboxu

„Załaduj więcej” gubi wiadomości, gdy jedno konto skończy się wcześniej niż inne. RozwiązaniePrzechowuj mapę z account_id do next_cursor. Przesuwaj każde konto niezależnie i zatrzymuj te, które nie zwróciły kursora.

Mieszanie cursor i offset

Kod działa u jednego dostawcy, a u innego przestaje. RozwiązanieUżywaj next_cursor wtedy, gdy dostawca go obsługuje, a w przeciwnym razie offset zgodnie z kontraktem. Czytaj kopertę każdego konta, zamiast zakładać z góry.

Traktowanie limit jako gwarancji

Krótka strona jest odczytywana jako koniec listy. Rozwiązanielimit to górny limit. Listę konta kończy wyłącznie brak next_cursor w odpowiedzi; strona z mniejszą liczbą elementów niż żądano jej nie kończy.

6000+ Firmy, które wprowadzają innowacje z Unipile

Zaufali nam liderzy branży

1 API

Usprawnij obsługę wszystkich głównych kanałów komunikacji

2 dni

Szybkie uruchomienie integracji przy minimalnej konfiguracji

30%

Mniej pracy i zasobów na utrzymanie

Wbudowane bezpieczeństwo i zgodność

Ochrona klasy enterprise dla danych i procesów Więcej o naszym bezpieczeństwie

SOC 2 Type II

Certyfikat

Niezależnie audytowane mechanizmy bezpieczeństwa, które zapewniają ochronę danych i ciągłość działania.

GDPR

Zgodność

Pełna zgodność z europejskimi przepisami o ochronie danych osobowych.

99.9%

Dostępności platformy w ciągu ostatnich 24 miesięcy

24/7

Globalne wsparcie i wydajne API

FAQ: ujednolicony inbox

Jedno wywołanie na konto, potrzebne endpointy, paginacja między kontami, format wiadomości i e-maili oraz utrzymywanie listy na żywo.

Nie, i to celowo. account_id jest częścią ścieżki, więc wywołuje się endpoint raz na konto i scala wyniki w aplikacji. API ujednolica format obiektów, a nie liczbę wywołań.

GET /v2/accounts/ do pobrania listy kont, potem GET /v2/{account_id}/chats i GET /v2/{account_id}/emails dla każdego konta, a następnie GET /v2/{account_id}/chats/{chat_id}/messages do otwarcia rozmowy. Odpowiedzi wysyła się przez POST /v2/{account_id}/chats/{chat_id}/messages/send i POST /v2/{account_id}/emails/send.

Osobny kursor na konto. Każdy endpoint listy zwraca data, total_count i next_cursor. Wartość next_cursor należy przekazać z powrotem w parametrze cursor i przechowywać w stanie aplikacji mapę kursorów, po jednym na konto.

Rozmowy z komunikatorów to obiekty Chat, a e-maile to obiekty Email, każdy z własnymi polami. Normalizacja odbywa się w aplikacji na co najmniej trzech polach: identyfikatorze, dacie i nadawcy. Agent czyta oba schematy przez serwer i pisze to mapowanie.

Za pomocą endpointu webhooka zasubskrybowanego na message.new i email.new. Osobna strona pokazuje, jak agent go podłącza.