Zo laat je je gebruikers WhatsApp-, Instagram- en TikTok-accounts aan je app koppelen
Om je gebruikers WhatsApp-, Instagram- en TikTok-accounts aan je app te laten koppelen, maak je een verbindingssessie aan met de Partner API van easyCoexistence en stuur je de gebruiker naar de gehoste url. Daar koppelt de gebruiker een WhatsApp-nummer via Embedded Signup van Meta of logt hij in bij Instagram, Facebook, TikTok, YouTube, LinkedIn en meer kanalen. Daarna keert de gebruiker terug naar je redirect_url met de nieuwe verbinding- of kanaal-id. Koppellinks blijven een uur geldig.
Hoe lang een koppellink werkt; daarna staat de sessie op expired en is een nieuwe nodig.
Hoeveel verbindingssessies één account tegelijk open mag hebben, naast een limiet van 100 nieuwe sessies per uur.
Een sessie wordt aangemaakt, geopend, verbonden, geannuleerd of verlopen, zoals GET /connect-sessions/:id aangeeft.
De langste alternatieve callback-URL die Meta accepteert om de webhooks voor berichten van een WhatsApp-nummer elders te routeren.
Hoe werkt een koppellink?
Net als een afrekenpagina. Je backend maakt een sessie aan, je interface stuurt de klant naar de url, de klant verbindt zich op een pagina op easycoexistence.com en de browser keert terug naar je redirect_url. Daarna bevestigt je backend het resultaat en haalt de inloggegevens van de nieuwe verbinding op, allemaal met je API-sleutel.
Wat zit er in het verzoek?
Een JSON-inhoud die naar https://easycoexistence.com/api/v1/connect-sessions wordt verstuurd, met je API-sleutel als Bearer-token. Alleen redirect_url is verplicht:
redirect_url: een https-URL waar de klant daarna terechtkomt.- channel: whatsapp, de standaard, of een sociaal netwerk dat openstaat voor je account, in kleine letters, zoals instagram, tiktok of youtube.
external_ref: je eigen id voor deze klant, tot 200 tekens.partner_name: de naam die de gehoste pagina toont, tot 80 tekens; standaard je accountnaam.webhook_urlmetwebhook_verify_token: alleen voor nummers, en altijd samen. Meta levert de berichten van het nummer daar vanaf het moment dat het verbindt.
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"
}'Wat komt er terug?
Een 201 met de sessie. Stuur de klant naar de url en bewaar de id, die begint met cs_, om de sessie later op te zoeken. expires_at valt een uur na het aanmaken, en connection_id of channel_id wordt ingevuld zodra de klant verbindt, afhankelijk van het kanaal van de sessie. GET /connect-sessions/:id geeft op elk moment dezelfde vorm terug.
{
"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"
}Welke fouten kan het aanmaken van een sessie teruggeven?
Elke fout heeft dezelfde opbouw: een object met een code en een bericht, en het bericht zegt wat je moet repareren. Het aanmaken van een sessie kan het volgende teruggeven:
- 400
invalid_jsonofinvalid_request: de inhoud is geen JSON-object, of een veld heeft de validatie niet doorstaan, zoals eenredirect_urldie niet https is. - 400
channel_unavailable: het kanaal staat niet open voor dit account; het bericht somt de openstaande kanalen op. - 401 unauthorized: de API-sleutel ontbreekt of is ongeldig.
- 402
billing_required: het account heeft nog geen creditcard, en alles dat via het account is verbonden, wordt daarop gefactureerd. - 429
cap_reached: er staan al 50 sessies open; wacht tot er een is afgerond of verlopen. - 429
rate_limited: meer dan 100 sessies in dit uur; het bericht zegt hoelang je moet wachten.
Waar komt de klant daarna terecht?
Op je redirect_url, met het resultaat toegevoegd aan de querystring. Hetzelfde resultaat staat op de sessie, die je backend leest met GET /connect-sessions/:id:
- session: de sessie-id, cs_ gevolgd door willekeurige tekens.
- status: connected, of cancelled wanneer de klant op Annuleren en terugkeren kiest.
external_ref: je id voor de klant, als de sessie er een bevatte.connection_id: de id van het nieuwe nummer, voor /connections.channel_id: de id van het nieuwe socialaccount, voor /channels.
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…Welke statussen kan een sessie hebben?
Vijf. GET /connect-sessions/:id geeft de huidige status, met opened_at, finished_at en last_error, die aangeeft waarom de laatste poging is mislukt:
- created: aangemaakt door je backend, nog niet geopend.
- opened: de klant heeft de gehoste pagina geladen.
- connected: een nummer of socialaccount is verbonden en de id staat op de sessie.
- cancelled: de klant is weggegaan via Annuleren en terugkeren.
- expired: het uur is voorbij voordat de sessie was afgerond.
Hoe lang werkt een link?
Één uur vanaf het aanmaken. Daarna meldt de gehoste pagina aan de klant dat de link verlopen is, met een knop terug naar je redirect_url met status=cancelled, en de sessie staat op expired. Een account kan 50 open sessies hebben en er 100 per uur aanmaken, omdat Meta elke eerste onboarding meetelt tegen een limiet voor de hele app die alle accounts delen.
Wat doet external_ref?
Het koppelt elke verbinding aan je klant. De waarde die je stuurt wordt opgeslagen op het nummer of kanaal dat de sessie aanmaakt, toegevoegd aan de redirect en opgenomen in elke statusgebeurtenis erover, zodat GET /connections?external_ref=customer_4821 en GET /channels?external_ref=customer_4821 tonen wat die klant heeft verbonden. Een aanmelding via Facebook of LinkedIn kan meerdere pagina's tegelijk brengen: de redirect noemt de eerste, en het filter toont de rest. Gebruik een stabiele id uit je eigen database, geen e-mailadres dat kan veranderen.
Wat als de klant annuleert of een aanmelding mislukt?
Het hangt af van waar het gebeurde, en de sessie bewaart de geschiedenis:
- De popup van Meta mislukt of wordt gesloten: de klant drukt op dezelfde pagina opnieuw op Verbinden zolang de link open is.
- Een socialaccountaanmelding wordt geannuleerd of geweigerd: de klant keert terug naar de gehoste pagina met de reden en kan het opnieuw proberen tot de link verloopt.
- Het account is al via een ander easyCoexistence-account verbonden:
last_errorzegt dat, en de klant meldt zich aan met een ander account. - De klant kiest Annuleren en terugkeren: je
redirect_urlkrijgt status=cancelled en de sessie sluit, dus maak een nieuwe aan voor een nieuwe poging. - De link is verlopen: maak een nieuwe sessie aan.
Wat als een nummer verbindt zonder het token van de klant?
Meta voltooit Embedded Signup soms zonder het eigen bedrijfstoken van de klant af te geven. De gehoste pagina vraagt dan om nog één ronde, die enkele seconden duurt. Als de klant die overslaat, staat de sessie op connected met token_ready false en krijgt je URL voor gebeurtenissen connection.token_missing: het nummer ontvangt berichten, want de id's zijn geldig, maar kan niet verzenden tot een nieuwe connect-sessie het opnieuw verbindt en het token uitgeeft.
Wat als de webhook_url Meta's controle niet doorstaat?
Het nummer verbindt toch. Meta controleert een webhook_url met een GET-handshake, die je endpoint doorstaat door hub.challenge terug te geven wanneer hub.verify_token overeenkomt. Mislukt die, dan begint last_error op de sessie met webhook_url was not applied en geeft het de reden van Meta, en stelt PUT /connections/:id/webhook de bestemming in zodra het endpoint antwoordt. Wordt dat binnen 24 uur na het verbinden ingesteld, dan ontvangt het nog de eenmalige import van contacten en, als de klant daarmee heeft ingestemd, de chatgeschiedenis.
Wat ziet de klant?
Een pagina op easycoexistence.com met je naam uit partner_name, en geen account, e-mailadres of creditcard om in te vullen. Voor een WhatsApp-nummer toont die een korte checklist van geschiktheid, daarna de popup van Meta en een QR-code om te scannen met de WhatsApp Business-app. Voor een socialaccount toont die één knop, zoals Doorgaan met TikTok, die het eigen toestemmingsscherm van het netwerk in hetzelfde tabblad opent, zodat het ook op telefoons werkt.
Veelgemaakte fouten
- Alleen de querystring vertrouwen. Iedereen kan status=connected in een URL typen, dus bevestig met GET /connect-sessions/:id vanuit je backend voordat je de klant als verbonden markeert.
- De link in een iframe insluiten. Stuur de klant ernaartoe met een redirect of een nieuw tabblad, want zo zijn de gehoste pagina en de aanmeldingen die die opent bedoeld om te werken.
- Koppellinks vooraf maken. Elke link werkt een uur en elke open link telt mee voor de limiet van 50, dus maak de sessie aan wanneer de klant op het punt staat te verbinden.
- Een webhook_url langer dan 200 tekens sturen. Meta accepteert alternatieve callback-URL's tot 200 tekens, dus een langere wordt niet toegepast en het nummer verbindt zonder.
easyCoexistence koppelt de WhatsApp-nummers van je klanten en hun Instagram-, Facebook-, TikTok-, YouTube- en LinkedIn-accounts, en meer kanalen, aan je software via één gehoste link. Daarna geeft het je backend de inloggegevens, webhooks en ondertekende statusgebeurtenissen van elke verbinding. US$ 9 tot US$ 0.75 per verbinding per maand, dalend naarmate je meer verbindingen toevoegt, met de eerste 3 dagen gratis.
Veelgestelde vragen
Kan één koppellink twee keer gebruikt worden?
Nee. Een link eindigt met één nummer, of met één socialaccountaanmelding, die bij Facebook of LinkedIn meerdere pagina's kan opleveren. Daarna staat hij op connected, dus maak een nieuwe sessie aan voor de volgende verbinding.
Kan ik de link per e-mail of chat versturen?
Ja, zolang de klant hem binnen het uur opent. De sessie-id in de URL autoriseert de pagina, dus stuur elke link alleen naar de klant voor wie hij is gemaakt.
Werkt de gehoste pagina op telefoons?
Socialaccountaanmeldingen wel, omdat die in hetzelfde tabblad openen. Een WhatsApp-nummer koppel je het best vanaf een computer: op een telefoon opent de popup van Meta in een nieuw tabblad, en de telefoon zelf is nodig om de QR-code te scannen.
Hoe hoor ik dat een klant is verbonden zonder te pollen?
Stel een URL voor statusgebeurtenissen in op het dashboard onder Profiel, Developers. easyCoexistence stuurt dan connection.connected of channel.connected, ondertekend en met je external_ref, zodra de verbinding tot stand komt.
Lees verder
Koppel je eerste kanaal in twee minuten.
Geen platformbeoordelingen om op te wachten. Verbind WhatsApp, Instagram, TikTok of een ander kanaal, vraag je AI om te posten, te reageren of een rapport te maken, en zie het aan het werk.
- 3 dagen gratis
- Op elk moment opzegbaar
- Alleen officiële API's
- 24/7 bewaakt
Geverifieerd op