Come permettere ai tuoi utenti di collegare WhatsApp, Instagram e TikTok alla tua app
Per permettere ai tuoi utenti di collegare account WhatsApp, Instagram e TikTok alla tua app, crea una sessione di connessione con la Partner API di easyCoexistence e invia l'utente al suo url ospitato. Lì collega un numero WhatsApp tramite Embedded Signup di Meta oppure accede a Instagram, Facebook, TikTok, YouTube, LinkedIn e altri canali, poi torna al tuo redirect_url con l'id della nuova connessione o del nuovo canale. I link restano validi un'ora.
Per quanto tempo funziona un link di connessione; dopo, la sessione risulta scaduta e serve un nuovo link.
Quante sessioni di connessione un account può tenere aperte insieme, accanto al limite di 100 nuove sessioni all'ora.
Una sessione viene creata, aperta, connessa, annullata o scaduta, come riporta GET /connect-sessions/:id.
La lunghezza massima dell'URL di callback alternativo che Meta accetta per instradare altrove i messaggi webhook di un numero WhatsApp.
Come funziona un link di connessione?
Funziona come una pagina di pagamento. Il tuo backend crea una sessione, la tua interfaccia invia il cliente al suo url, il cliente si connette su una pagina di easycoexistence.com e il browser torna al tuo redirect_url. Poi il tuo backend conferma il risultato e recupera le credenziali della nuova connessione, sempre con la tua chiave API.
Cosa va nella richiesta?
Un corpo JSON inviato con POST a https://easycoexistence.com/api/v1/connect-sessions, con la tua chiave API come token Bearer. È obbligatorio solo redirect_url:
redirect_url: un URL https a cui il cliente arriva al termine.- channel: whatsapp, il valore predefinito, oppure un social network aperto al tuo account, con il nome in minuscolo, come instagram, tiktok o youtube.
external_ref: il tuo id per questo cliente, fino a 200 caratteri.partner_name: il nome che mostra la pagina ospitata, fino a 80 caratteri; per impostazione predefinita il nome del tuo account.webhook_urlconwebhook_verify_token: solo per i numeri, e sempre insieme. Meta invia lì i messaggi del numero dal momento in cui si connette.
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"
}'Cosa torna indietro?
Una risposta 201 con la sessione. Invia il cliente all'url e conserva l'id, che inizia con cs_, per consultare la sessione in seguito. expires_at scade un'ora dopo la creazione, mentre connection_id o channel_id si compila quando il cliente si connette, a seconda del canale della sessione. GET /connect-sessions/:id restituisce la stessa struttura in qualsiasi momento.
{
"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"
}Quali errori può restituire la creazione di una sessione?
Ogni errore ha lo stesso corpo, un oggetto con un codice e un messaggio, e il messaggio indica cosa correggere. La creazione di una sessione può restituire:
- 400
invalid_jsonoinvalid_request: il corpo non è un oggetto JSON, oppure un campo non ha superato la validazione, come unredirect_urlche non è https. - 400
channel_unavailable: il canale non è aperto a questo account; il messaggio elenca quelli aperti. - 401 unauthorized: la chiave API manca o non è valida.
- 402
billing_required: l'account non ha ancora una carta registrata, e tutto ciò che vi è collegato viene addebitato su quell'account. - 429
cap_reached: sono già aperte 50 sessioni; attendi che alcune si concludano o scadano. - 429
rate_limited: più di 100 sessioni in questa ora; il messaggio indica quanto attendere.
Dove atterra il cliente dopo?
Sul tuo redirect_url, con l'esito aggiunto alla sua query string. Lo stesso esito è nella sessione, che il tuo backend legge con GET /connect-sessions/:id:
- session: l'id della sessione, cs_ seguito da caratteri casuali.
- status: connected, oppure cancelled se il cliente ha scelto Annulla e torna indietro.
external_ref: il tuo id per il cliente, quando la sessione ne includeva uno.connection_id: l'id del nuovo numero, per /connections.channel_id: l'id del nuovo account social, per /channels.
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…Quali stati può avere una sessione?
Cinque. GET /connect-sessions/:id riporta lo stato attuale, con opened_at, finished_at e last_error, che spiega perché l'ultimo tentativo è fallito:
- created: creata dal tuo backend, non ancora aperta.
- opened: il cliente ha caricato la pagina ospitata.
- connected: un numero o un account social si è collegato, e il suo id è nella sessione.
- cancelled: il cliente è uscito tramite Annulla e torna indietro.
- expired: l'ora è scaduta prima che la sessione si concludesse.
Quanto dura un link?
Un'ora dalla creazione. Dopo, la pagina ospitata informa il cliente che il link è scaduto, con un pulsante per tornare al tuo redirect_url con status=cancelled, e la sessione risulta scaduta. Un account può tenere aperte 50 sessioni e crearne 100 all'ora, perché Meta conta ogni configurazione iniziale rispetto a un limite valido per l'intera app, condiviso da tutti gli account.
A cosa serve external_ref?
Lega ogni connessione al tuo cliente. Il valore che invii viene salvato sul numero o sul canale che la sessione crea, aggiunto al reindirizzamento e incluso in ogni evento di stato che lo riguarda, così GET /connections?external_ref=customer_4821 e GET /channels?external_ref=customer_4821 elencano cosa ha collegato quel cliente. Un accesso con Facebook o LinkedIn può portare più pagine in una volta: il reindirizzamento ne indica la prima, e il filtro elenca le altre. Usa un id stabile del tuo database, non un'e-mail che potrebbe cambiare.
Cosa succede se il cliente annulla o l'accesso fallisce?
Dipende da dove è successo, e la sessione conserva il registro:
- Il popup di Meta fallisce o viene chiuso: il cliente preme di nuovo Connetti nella stessa pagina finché il link è aperto.
- Un accesso social viene annullato o rifiutato: il cliente torna alla pagina ospitata con il motivo e può riprovare finché il link non scade.
- L'account è già collegato tramite un altro account easyCoexistence:
last_errorlo segnala, e il cliente accede con un altro account. - Il cliente sceglie Annulla e torna indietro: il tuo
redirect_urlriceve status=cancelled e la sessione si chiude, quindi creane una nuova per riprovare. - Il link è scaduto: crea una nuova sessione.
Cosa succede se un numero si connette senza il token del cliente?
A volte Meta completa l'Embedded Signup senza emettere il token dell'azienda del cliente. La pagina ospitata chiede allora un altro passaggio, che richiede qualche secondo. Se il cliente lo salta, la sessione risulta connected con token_ready false e il tuo URL degli eventi riceve connection.token_missing: il numero riceve messaggi, perché i suoi id sono validi, ma non può inviarne finché una nuova sessione di connessione non lo ricollega ed emette il token.
Cosa succede se il webhook_url non supera il controllo di Meta?
Il numero si connette comunque. Meta verifica un webhook_url con una richiesta GET di verifica, che il tuo endpoint supera restituendo hub.challenge quando hub.verify_token corrisponde. Se fallisce, last_error della sessione inizia con webhook_url was not applied e riporta il motivo di Meta, e PUT /connections/:id/webhook imposta la destinazione una volta che l'endpoint risponde. Impostato entro 24 ore dalla connessione, riceve comunque l'importazione una tantum dei contatti e, se il cliente ha acconsentito a condividerla, la cronologia delle chat.
Cosa vede il cliente?
Una pagina di easycoexistence.com con il tuo nome preso da partner_name, senza account, e-mail o carta da compilare. Per un numero WhatsApp mostra un breve elenco di requisiti, poi il popup di Meta e un codice QR da scansionare con l'app WhatsApp Business. Per un account social mostra un solo pulsante, come Continua con TikTok, che apre la schermata di consenso del social nella stessa scheda, quindi funziona anche sui telefoni.
Errori comuni
- Fidarsi della sola query string. Chiunque può digitare status=connected in un URL, quindi conferma con GET /connect-sessions/:id dal tuo backend prima di segnare il cliente come connesso.
- Incorporare il link in un iframe. Invia il cliente con un reindirizzamento o una nuova scheda, che è come devono funzionare la pagina ospitata e gli accessi che apre.
- Creare i link in anticipo. Ognuno vale un'ora e ogni link aperto conta verso il limite di 50, quindi crea la sessione quando il cliente sta per connettersi.
- Inviare un webhook_url più lungo di 200 caratteri. Meta accetta URL di callback alternativi fino a 200 caratteri, quindi uno più lungo non viene applicato e il numero si connette senza.
easyCoexistence collega al tuo software i numeri WhatsApp dei tuoi clienti e i loro account Instagram, Facebook, TikTok, YouTube e LinkedIn, e altri canali, tramite un unico link ospitato, poi fornisce al tuo backend le credenziali di ogni connessione, i webhook e gli eventi di stato firmati. Da US$ 9 a US$ 0,75 per connessione al mese, scendendo man mano che aggiungi connessioni, con i primi 3 giorni di prova gratuita.
Domande frequenti
Un link di connessione può essere usato due volte?
No. Un link si chiude con un numero, oppure con un accesso social, che su Facebook o LinkedIn può portare più pagine. Dopo, risulta connected, quindi crea una nuova sessione per la connessione successiva.
Posso inviare il link via e-mail o chat?
Sì, purché il cliente lo apra entro l'ora. L'id di sessione nell'URL è ciò che autorizza la pagina, quindi invia ogni link solo al cliente per cui è stato creato.
La pagina ospitata funziona sui telefoni?
Gli accessi social sì, perché si aprono nella stessa scheda. Un numero WhatsApp si collega meglio da computer: su telefono il popup di Meta si apre in una nuova scheda, e serve proprio il telefono per scansionare il codice QR.
Come faccio a sapere che un cliente si è connesso senza fare polling?
Imposta un URL per gli eventi di stato nella dashboard, sotto Profilo, Sviluppatori. easyCoexistence invia poi connection.connected o channel.connected, firmati e con il tuo external_ref, non appena la connessione è stabilita.
Continua a leggere
Collega il tuo primo canale in due minuti.
Nessuna revisione delle piattaforme da aspettare. Collega WhatsApp, Instagram, TikTok o un altro canale, poi chiedi alla tua AI di pubblicare, rispondere o fare un report, e guardala al lavoro.
- 3 giorni gratis
- Disdici quando vuoi
- Solo API ufficiali
- Monitorato 24/7
Verificato il