Näin annat käyttäjiesi yhdistää WhatsApp-, Instagram- ja TikTok-tilit sovellukseesi
Jotta käyttäjäsi voivat yhdistää WhatsApp-, Instagram- ja TikTok-tilit sovellukseesi, luo easyCoexistencen Partner API:lla yhteysistunto ja ohjaa käyttäjä sen hostattuun URL-osoitteeseen. Siellä hän yhdistää WhatsApp-numeron Metan Embedded Signupin kautta tai kirjautuu Instagramiin, Facebookiin, TikTokiin, YouTubeen, LinkedIniin ja muihin kanaviin. Sen jälkeen hänet palautetaan redirect_url-osoitteeseesi uuden yhteyden tai kanavan tunnuksen kanssa. Linkit ovat voimassa tunnin.
Kuinka kauan yhdistämislinkki toimii. Sen jälkeen istunnon tila on vanhentunut ja tarvitaan uusi.
Kuinka monta yhteysistuntoa tili voi pitää auki samaan aikaan, ja raja: 100 uutta istuntoa tunnissa.
Istunto luodaan, avataan, yhdistetään, peruutetaan tai vanhenee, kuten GET /connect-sessions/:id ilmoittaa.
Pisin vaihtoehtoinen callback-URL, jonka Meta hyväksyy ohjaamaan WhatsApp-numeron viestien webhookit muualle.
Miten yhdistämislinkki toimii?
Toimii kuin maksusivu. Backendisi luo istunnon, käyttöliittymäsi lähettää asiakkaan sen URL-osoitteeseen, asiakas yhdistää tilinsä easycoexistence.com-sivulla ja selain palaa redirect_url-osoitteeseesi. Sen jälkeen backendisi vahvistaa tuloksen ja hakee uuden yhteyden tunnukset, kaikki API-avaimellasi.
Mitä pyyntöön kuuluu?
JSON-runko lähetetään POST-pyyntönä osoitteeseen https://easycoexistence.com/api/v1/connect-sessions, ja API-avain välitetään Bearer-tokenina. Pakollinen on vain redirect_url:
redirect_url: https-URL, johon asiakas päätyy jälkeenpäin.- channel: whatsapp (oletus) tai tilillesi avoinna oleva sosiaalinen verkosto pienillä kirjaimilla kirjoitettuna, esimerkiksi instagram, tiktok tai youtube.
external_ref: oma tunnisteesi tälle asiakkaalle, enintään 200 merkkiä.partner_name: nimi, jonka hostattu sivu näyttää, enintään 80 merkkiä; oletuksena tilisi nimi.webhook_urljawebhook_verify_token: vain numeroille, ja aina yhdessä. Meta toimittaa numeron viestit sinne heti yhdistämisestä lähtien.
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"
}'Mitä palautuu?
201-vastaus istunnon tiedoilla. Lähetä asiakas URL-osoitteeseen ja säilytä id, joka alkaa cs_, jotta voit hakea istunnon myöhemmin. expires_at on luomisesta tunnin päässä, ja connection_id tai channel_id täyttyy, kun asiakas yhdistää, riippuen istunnon kanavasta. GET /connect-sessions/:id palauttaa saman rakenteen milloin tahansa.
{
"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"
}Mitkä virheet istunnon luominen voi palauttaa?
Jokaisella virheellä on sama runko: objekti, jossa on code ja message. Viesti kertoo, mitä on korjattava. Istunnon luominen voi palauttaa:
- 400
invalid_jsontaiinvalid_request: runko ei ole JSON-objekti, tai kenttä ei läpäise validointia, esimerkiksiredirect_url, joka ei ole https. - 400
channel_unavailable: kanava ei ole avoinna tälle tilille; viesti luettelee avoimet kanavat. - 401 unauthorized: API-avain puuttuu tai on virheellinen.
- 402
billing_required: tilillä ei ole vielä korttia, ja kaikki sen kautta yhdistetty laskutetaan siihen. - 429
cap_reached: 50 istuntoa on jo auki; odota, että osa valmistuu tai vanhenee. - 429
rate_limited: yli 100 istuntoa tämän tunnin aikana; viesti kertoo, kuinka kauan on odotettava.
Minne asiakas päätyy myöhemmin?
redirect_url-osoitteeseesi, ja tulos on lisätty sen kyselymerkkijonoon. Sama tulos on istunnossa, jonka backendisi lukee kutsulla GET /connect-sessions/:id:
- session: istunnon tunnus, cs_ ja sen jälkeen satunnaiset merkit.
- status: connected, tai cancelled, kun asiakas valitsi ”Peruuta ja palaa takaisin”.
external_ref: tunnisteesi asiakkaalle, jos istunto sisälsi sen.connection_id: uuden numeron tunnus, käytettäväksi kohteessa /connections.channel_id: uuden sosiaalisen tilin tunnus, käytettäväksi kohteessa /channels.
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…Mitä tilaa istunnolla voi olla?
Viisi. GET /connect-sessions/:id kertoo nykyisen tilan kenttineen opened_at, finished_at ja last_error. last_error kertoo, miksi viimeisin yritys epäonnistui:
- created: backendisi luoma, ei vielä avattu.
- opened: asiakas on ladannut hostatun sivun.
- connected: numero tai sometili on yhdistetty, ja sen tunnus on istunnossa.
- cancelled: asiakas poistui valitsemalla ”Peruuta ja palaa takaisin”.
- expired: tunti loppui ennen kuin istunto valmistui.
Kuinka kauan linkki toimii?
Tunnin luomisesta. Sen jälkeen hostattu sivu kertoo asiakkaalle, että linkki on vanhentunut, ja tarjoaa painikkeen, joka palauttaa redirect_url-osoitteeseesi tilalla status=cancelled. Istunnon tila on vanhentunut. Tilillä voi olla 50 avointa istuntoa ja luoda 100 tunnissa, koska Meta laskee jokaisen ensimmäisen kerran tehtävän käyttöönoton kaikille tileille yhteiseen sovelluskohtaiseen rajaan.
Mitä external_ref tekee?
Se liittää jokaisen yhteyden asiakkaaseesi. Lähettämäsi arvo tallennetaan numeroon tai kanavaan, jonka istunto luo, lisätään uudelleenohjaukseen ja sisällytetään jokaiseen sitä koskevaan tilatapahtumaan. Näin GET /connections?external_ref=customer_4821 ja GET /channels?external_ref=customer_4821 listaavat, mitä asiakas on yhdistänyt. Facebook-kirjautuminen tai LinkedIn-kirjautuminen voi tuoda kerralla useita sivuja: uudelleenohjaus nimeää ensimmäisen, suodatin listaa loput. Käytä pysyvää tunnistetta omasta tietokannastasi, älä sähköpostiosoitetta, joka voi muuttua.
Mitä tapahtuu, jos asiakas peruuttaa tai kirjautuminen epäonnistuu?
Se riippuu siitä, missä kohtaa se tapahtui, ja istunto säilyttää tiedon:
- Metan ponnahdusikkuna epäonnistuu tai suljetaan: asiakas painaa samalla sivulla uudelleen ”Connect”-painiketta, kun linkki on yhä auki.
- Somekirjautuminen peruutetaan tai hylätään: asiakas palaa hostatulle sivulle syyn kanssa ja voi yrittää uudelleen, kunnes linkki vanhenee.
- Tili on jo yhdistetty toisen easyCoexistence-tilin kautta:
last_errorkertoo sen, ja asiakas kirjautuu toisella tilillä. - Asiakas valitsee ”Peruuta ja palaa takaisin”:
redirect_url-osoitteeseesi tulee status=cancelled, ja istunto sulkeutuu, joten luo uusi istunto, jos haluat yrittää uudelleen. - Linkki vanhentui: luo uusi istunto.
Mitä tapahtuu, jos numero yhdistyy ilman asiakkaan tunnusta?
Meta päättää joskus Embedded Signupin ilman, että asiakkaan oma yritystoken on myönnetty. Hostattu sivu pyytää silloin yhden kierroksen lisää, mikä kestää muutaman sekunnin. Jos asiakas ohittaa sen, istunnon tila on connected ja token_ready on false, ja tapahtumien URL-osoitteeseesi tulee connection.token_missing. Numero vastaanottaa viestejä, koska sen tunnukset ovat voimassa, mutta ei voi lähettää ennen kuin uusi yhteysistunto yhdistää sen uudelleen ja myöntää tokenin.
Mitä tapahtuu, jos webhook_url ei läpäise Metan tarkistusta?
Numero yhdistyy silti. Meta tarkistaa webhook_url-osoitteen GET-kättelyllä, jonka endpointisi läpäisee kaikumalla hub.challenge-arvon, kun hub.verify_token täsmää. Jos tarkistus epäonnistuu, istunnon last_error alkaa tekstillä webhook_url was not applied ja kertoo Metan syyn. PUT /connections/:id/webhook asettaa kohteen, kun endpoint vastaa. Jos se asetetaan 24 tunnin sisällä yhdistämisestä, se saa silti kertaluonteisen kontaktien tuonnin ja, jos asiakas on suostunut jakamaan sen, keskusteluhistorian.
Mitä asiakas näkee?
Sivun easycoexistence.comissa, jolla näkyy partner_name-kenttään syötetty nimesi, eikä tiliä, sähköpostia tai korttia tarvitse täyttää. WhatsApp-numeron kohdalla sivulla on lyhyt kelpoisuuslista, sen jälkeen Metan ponnahdusikkuna ja QR-koodi, joka skannataan WhatsApp Business -sovelluksella. Sometilin kohdalla sivulla on yksi painike, esimerkiksi Jatka TikTokilla, joka avaa verkoston oman suostumusnäkymän samassa välilehdessä, joten se toimii myös puhelimilla.
Yleiset virheet
- Luottaa pelkkään kyselymerkkijonoon. Kuka tahansa voi kirjoittaa URL-osoitteeseen status=connected, joten vahvista backendistäsi kutsulla GET /connect-sessions/:id ennen kuin merkitset asiakkaan yhdistetyksi.
- Linkin upottaminen iframeen. Lähetä asiakas sinne uudelleenohjauksella tai uuteen välilehteen, sillä hostattu sivu ja sen avaamat kirjautumiset on tarkoitettu toimimaan niin.
- Linkkien tekeminen etukäteen. Jokainen toimii tunnin, ja jokainen avoin laskee 50 rajaan, joten luo istunto juuri silloin, kun asiakas on yhdistämässä.
- Liian pitkän webhook_url-osoitteen lähettäminen (yli 200 merkkiä). Meta hyväksyy vaihtoehtoiset callback-URL-osoitteet enintään 200 merkin pituisina, joten pidempää ei oteta käyttöön ja numero yhdistyy ilman sitä.
easyCoexistence yhdistää asiakkaidesi WhatsApp-numerot sekä heidän Instagram-, Facebook-, TikTok-, YouTube- ja LinkedIn-tilinsä ja muut kanavat ohjelmistoosi yhden hostatun linkin kautta. Sen jälkeen backendisi saa kunkin yhteyden tunnukset, webhookit ja allekirjoitetut tilatapahtumat. US$ 9:stä US$ 0,75:een yhteydeltä kuukaudessa, ja hinta laskee lisättäessä yhteyksiä. Ensimmäiset 3 päivää ovat ilmaista kokeilua.
Usein kysytyt kysymykset
Voiko yhden yhdistämislinkin käyttää kahdesti?
Ei. Linkki päättyy yhteen numeroon tai yhteen somekirjautumiseen, joka Facebookissa tai LinkedInissä voi tuoda useita sivuja. Sen jälkeen sen tila on connected, joten luo uusi istunto seuraavaa yhteyttä varten.
Voinko lähettää linkin sähköpostilla tai chatissa?
Kyllä, kunhan asiakas avaa sen tunnin sisällä. URL-osoitteen istuntotunnus on se, mikä valtuuttaa sivun, joten lähetä kukin linkki vain sille asiakkaalle, jolle se tehtiin.
Toimiiko hostattu sivu puhelimilla?
Somekirjautumiset toimivat, koska ne avautuvat samassa välilehdessä. WhatsApp-numero yhdistetään parhaiten tietokoneelta: puhelimella Metan ponnahdusikkuna avautuu uudeksi välilehdeksi, ja QR-koodin skannaamiseen tarvitaan silti puhelin.
Miten kuulen, että asiakas on yhdistänyt ilman kyselyä?
Aseta tilatapahtumien URL-osoite hallintapaneelissa kohdassa Profile, Developers. easyCoexistence lähettää sen jälkeen connection.connected- tai channel.connected-tapahtuman, allekirjoitettuna ja external_ref-tunnisteesi kanssa, heti kun yhteys on tehty.
Lue lisää
Yhdistä ensimmäinen kanavasi kahdessa minuutissa.
Ei alustojen tarkastuksia odotettavana. Yhdistä WhatsApp, Instagram, TikTok tai jokin muu kanava, pyydä sitten tekoälyäsi julkaisemaan, vastaamaan tai raportoimaan ja seuraa, kun se hoitaa homman.
- 3 päivää ilmaiseksi
- Peruuta milloin tahansa
- Vain viralliset API:t
- Valvottu 24/7
Vahvistettu