Jak pozwolić użytkownikom połączyć konta WhatsApp, Instagram i TikTok z Twoją aplikacją
Aby pozwolić użytkownikom połączyć konta WhatsApp, Instagram i TikTok z Twoją aplikacją, utwórz sesję łączenia w Partner API easyCoexistence i wyślij użytkownika na jej hostowany adres URL. Tam połączy numer WhatsApp przez Embedded Signup firmy Meta albo zaloguje się do Instagrama, Facebooka, TikToka, YouTube, LinkedIna i kolejnych kanałów, a następnie wróci na Twój redirect_url z identyfikatorem nowego połączenia lub kanału. Linki działają godzinę.
Jak długo działa link do połączenia. Po tym czasie sesja ma status expired i potrzebny jest nowy link.
Ile sesji łączenia jedno konto może mieć otwartych naraz, obok limitu 100 nowych sesji na godzinę.
Sesja może być utworzona, otwarta, połączona, anulowana lub wygasła, zgodnie z odpowiedzią GET /connect-sessions/:id.
Najdłuższy alternatywny adres URL callbacku, jaki Meta przyjmuje do kierowania webhooków wiadomości numeru WhatsApp gdzie indziej.
Jak działa link do połączenia?
Jak strona płatności. Twój backend tworzy sesję, Twój interfejs wysyła klienta pod jej adres URL, klient łączy się na stronie easycoexistence.com, a przeglądarka wraca na Twój redirect_url. Następnie Twój backend potwierdza wynik i pobiera poświadczenia nowego połączenia, wszystko za pomocą Twojego klucza API.
Co zawiera żądanie?
Treść JSON wysyłana metodą POST na https://easycoexistence.com/api/v1/connect-sessions, z kluczem API jako tokenem Bearer. Wymagane jest tylko redirect_url:
redirect_url: adres https, na który klient trafia po zakończeniu.- channel: whatsapp, wartość domyślna, albo sieć społecznościowa otwarta dla Twojego konta, podana małymi literami, np. instagram, tiktok lub youtube.
external_ref: Twój własny identyfikator tego klienta, do 200 znaków.partner_name: nazwa wyświetlana na hostowanej stronie, do 80 znaków; domyślnie nazwa Twojego konta.webhook_urlzwebhook_verify_token: tylko dla numerów i zawsze razem. Meta dostarcza tam wiadomości numeru od chwili jego połączenia.
curl -X POST https://easycoexistence.com/api/v1/connect-sessions \
-H "Authorization: Bearer $EC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"channel": "whatsapp",
"redirect_url": "https://app.example.com/connect/return",
"external_ref": "customer_4821",
"partner_name": "ClinicApp",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"webhook_verify_token": "another-long-random-string"
}'Co wraca?
Odpowiedź 201 z sesją. Wyślij klienta pod url i zachowaj id, zaczynające się od cs_, aby później sprawdzić sesję. expires_at przypada godzinę po utworzeniu, a connection_id lub channel_id wypełnia się, gdy klient się połączy, zależnie od kanału sesji. GET /connect-sessions/:id zwraca ten sam kształt w dowolnym momencie.
{
"id": "cs_…",
"url": "https://easycoexistence.com/connect/cs_…",
"channel": "whatsapp",
"status": "created",
"external_ref": "customer_4821",
"connection_id": null,
"channel_id": null,
"token_ready": false,
"redirect_url": "https://app.example.com/connect/return",
"webhook_url": "https://hooks.example.com/wa/<long-random-secret>",
"last_error": null,
"expires_at": "2026-10-31T15:00:00.000Z",
"opened_at": null,
"finished_at": null,
"created_at": "2026-10-31T14:00:00.000Z"
}Jakie błędy może zwrócić utworzenie sesji?
Każdy błąd ma tę samą treść: obiekt z kodem błędu i komunikatem, a komunikat mówi, co naprawić. Utworzenie sesji może zwrócić:
- 400
invalid_jsonlubinvalid_request: treść nie jest obiektem JSON albo pole nie przeszło walidacji, np.redirect_url, który nie jest https. - 400
channel_unavailable: kanał nie jest otwarty dla tego konta; komunikat wymienia te, które są. - 401 unauthorized: klucz API jest brakujący lub nieprawidłowy.
- 402
billing_required: konto nie ma jeszcze karty, a wszystko połączone przez nie jest rozliczane na nie. - 429
cap_reached: otwarte są już 50 sesji; poczekaj, aż niektóre się zakończą lub wygasną. - 429
rate_limited: ponad 100 sesji w ciągu godziny; komunikat mówi, jak długo czekać.
Dokąd klient trafia potem?
Na Twój redirect_url, z wynikiem dopisanym do jego parametrów zapytania. Ten sam wynik jest w sesji, którą Twój backend odczytuje przez GET /connect-sessions/:id:
- session: identyfikator sesji, cs_ i losowe znaki.
- status: connected albo cancelled, gdy klient wybrał Anuluj i wróć.
external_ref: Twój identyfikator klienta, jeśli sesja go zawierała.connection_id: identyfikator nowego numeru, do /connections.channel_id: identyfikator nowego konta społecznościowego, do /channels.
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…Jakie statusy może mieć sesja?
Pięć. GET /connect-sessions/:id zwraca bieżący, wraz z opened_at, finished_at i last_error, które podaje, dlaczego ostatnia próba się nie udała:
- created: utworzona przez Twój backend, jeszcze nieotwarta.
- opened: klient załadował hostowaną stronę.
- connected: numer lub konto społecznościowe zostało połączone, a jego identyfikator jest w sesji.
- cancelled: klient wyszedł przez Anuluj i wróć.
- expired: godzina minęła, zanim sesja się zakończyła.
Jak długo działa link?
Godzinę od utworzenia. Potem hostowana strona informuje klienta, że link wygasł, i pokazuje przycisk powrotu na Twój redirect_url ze statusem status=cancelled, a sesja ma status expired. Konto może mieć 50 otwartych sesji i tworzyć 100 na godzinę, ponieważ Meta liczy każde pierwsze wdrożenie wobec limitu dla całej aplikacji, który dzielą wszystkie konta.
Do czego służy external_ref?
Wiąże każde połączenie z Twoim klientem. Wartość, którą wysyłasz, jest zapisywana przy numerze lub kanale, który sesja tworzy, dopisywana do przekierowania i zawarta w każdym zdarzeniu statusu o nim, więc GET /connections?external_ref=customer_4821 oraz GET /channels?external_ref=customer_4821 wyświetlają, co ten klient połączył. Logowanie przez Facebooka lub LinkedIn może od razu przynieść kilka stron: przekierowanie wymienia pierwszą, a filtr zwraca resztę. Użyj stabilnego identyfikatora z własnej bazy danych, a nie adresu e-mail, który może się zmienić.
Co, jeśli klient anuluje albo logowanie się nie uda?
Zależy to od miejsca, w którym to się stało, a sesja zachowuje zapis:
- Okno Meta nie otwiera się lub zostało zamknięte: klient naciska Połącz ponownie na tej samej stronie, dopóki link jest otwarty.
- Logowanie społecznościowe zostało anulowane lub odrzucone: klient wraca na hostowaną stronę z powodem i może spróbować ponownie, aż link wygaśnie.
- Konto jest już połączone przez inne konto easyCoexistence:
last_errorto podaje, a klient loguje się innym kontem. - Klient wybrał Anuluj i wróć: Twój
redirect_urldostaje status=cancelled, a sesja się zamyka, więc na kolejną próbę utwórz nową. - Link wygasł: utwórz nową sesję.
Co, jeśli numer połączy się bez tokenu klienta?
Meta czasem kończy Embedded Signup bez wystawienia własnego tokenu firmy klienta. Hostowana strona prosi wtedy o jeszcze jedno przejście, które trwa kilka sekund. Jeśli klient je pominie, sesja ma status connected z token_ready false, a Twój adres zdarzeń dostaje connection.token_missing: numer odbiera wiadomości, bo jego identyfikatory są prawidłowe, ale nie może wysyłać, dopóki nowa sesja łączenia go nie połączy ponownie i nie wystawi tokenu.
Co, jeśli webhook_url nie przejdzie sprawdzenia Meta?
Numer połączy się mimo to. Meta sprawdza webhook_url uzgadnianiem GET, które Twój endpoint przechodzi, odsyłając hub.challenge, gdy hub.verify_token się zgadza. Jeśli nie przejdzie, last_error sesji zaczyna się od webhook_url was not applied i podaje powód Meta, a PUT /connections/:id/webhook ustawia cel, gdy endpoint już odpowiada. Ustawiony w ciągu 24 godzin od połączenia, nadal otrzyma jednorazowy import kontaktów i, jeśli klient się na to zgodził, historię czatów.
Co widzi klient?
Stronę na easycoexistence.com z Twoją nazwą z partner_name i bez konta, adresu e-mail ani karty do uzupełnienia. Przy numerze WhatsApp pokazuje krótką listę kontrolną kwalifikacji, potem wyskakujące okno Meta i kod QR do zeskanowania aplikacją WhatsApp Business. Przy koncie społecznościowym pokazuje jeden przycisk, np. Kontynuuj z TikTok, który otwiera ekran zgody danej sieci w tej samej zakładce, więc działa też na telefonach.
Typowe błędy
- Ufanie samemu parametrowi zapytania. Każdy może wpisać status=connected w adres URL, więc potwierdź przez GET /connect-sessions/:id z backendu, zanim oznaczysz klienta jako połączonego.
- Osadzanie linku w iframe. Wyślij klienta na link przekierowaniem albo w nowej zakładce, bo tak mają działać hostowana strona i logowania, które otwiera.
- Tworzenie linków z wyprzedzeniem. Każdy działa godzinę, a każdy otwarty liczy się do limitu 50, więc utwórz sesję, gdy klient ma się zaraz połączyć.
- Wysyłanie webhook_url dłuższego niż 200 znaków. Meta przyjmuje alternatywne adresy callbacków do 200 znaków, więc dłuższy nie zostanie zastosowany, a numer połączy się bez niego.
easyCoexistence łączy numery WhatsApp Twoich klientów oraz ich konta na Instagramie, Facebooku, TikToku, YouTube i LinkedInie, a także kolejne kanały, z Twoim oprogramowaniem przez jeden hostowany link. Następnie przekazuje Twojemu backendowi dane dostępowe każdego połączenia, webhooki i podpisane zdarzenia statusu. Od US$ 9 do US$ 0.75 za połączenie miesięcznie, spadając wraz z liczbą połączeń, z bezpłatnym okresem próbnym: pierwsze 3 dni.
Najczęściej zadawane pytania
Czy jeden link do połączenia można użyć dwa razy?
Nie. Link kończy się jednym numerem albo jednym logowaniem społecznościowym, które na Facebooku lub LinkedIn może przynieść kilka stron. Potem ma status connected, więc na kolejne połączenie utwórz nową sesję.
Czy mogę wysłać link e-mailem lub czatem?
Tak, o ile klient otworzy go w ciągu godziny. Identyfikator sesji w adresie URL autoryzuje stronę, więc wysyłaj każdy link tylko klientowi, dla którego został utworzony.
Czy hostowana strona działa na telefonach?
Logowania społecznościowe tak, bo otwierają się w tej samej zakładce. Numer WhatsApp najlepiej połączyć z komputera: na telefonie wyskakujące okno Meta otwiera się jako nowa zakładka, a do zeskanowania kodu QR potrzebny jest właśnie telefon.
Jak dowiedzieć się, że klient się połączył, bez odpytywania?
Ustaw adres zdarzeń statusu w panelu, w sekcji Profil, Developers. easyCoexistence wysyła wtedy connection.connected lub channel.connected, podpisane i zawierające Twój external_ref, zaraz po nawiązaniu połączenia.
Czytaj dalej
Połącz pierwszy kanał w dwie minuty.
Bez czekania na weryfikację przez platformy. Połącz WhatsApp, Instagram, TikTok lub inny kanał, a potem poproś swoją AI o opublikowanie posta, odpowiedź lub raport i zobacz, jak działa.
- 3 dni za darmo
- Rezygnacja w każdej chwili
- Tylko oficjalne API
- Monitorowanie 24/7
Zweryfikowano w