Se connecterCommencer l’essai gratuit
easyCoexistence API officielles

Comment permettre à vos utilisateurs de connecter WhatsApp, Instagram et TikTok à votre application

Pour permettre à vos utilisateurs de connecter des comptes WhatsApp, Instagram et TikTok à votre application, créez une session de connexion avec l'API Partner d'easyCoexistence et envoyez l'utilisateur vers son url hébergée. Là, il connecte un numéro WhatsApp via Embedded Signup de Meta, ou se connecte à Instagram, Facebook, TikTok, YouTube, LinkedIn et d'autres canaux, puis revient vers votre redirect_url avec l'identifiant de la nouvelle connexion ou du nouveau canal. Les liens sont valables une heure.

1 hour

Durée de validité d'un lien de connexion : après ce délai, la session passe au statut expired et il faut en créer une nouvelle.

50 open

Nombre de sessions de connexion ouvertes simultanément pour un même compte, à côté d'une limite de 100 nouvelles sessions par heure.

5 statuses

Une session peut être créée, ouverte, connectée, annulée ou expirée, comme l'indique GET /connect-sessions/:id.

200 characters

La plus longue URL de rappel alternative que Meta accepte pour router ailleurs les webhooks de messages d'un numéro WhatsApp.

Comment fonctionne un lien de connexion ?

Comme une page de paiement. Votre backend crée une session, votre interface envoie le client vers son url, le client se connecte sur une page de easycoexistence.com, et le navigateur revient vers votre redirect_url. Votre backend confirme ensuite le résultat et récupère les identifiants de la nouvelle connexion, le tout avec votre clé d'API.

1CreatePOST /connect-sessions from your backend
2SendA redirect or a new tab to the session's url
3ConnectMeta's Embedded Signup, or the network's own sign-in
4ReturnYour redirect_url, with the session, status and new id
5ConfirmGET /connect-sessions/:id, then the credentials

Que contient la requête ?

Un corps JSON envoyé en POST à https://easycoexistence.com/api/v1/connect-sessions, avec votre clé d'API en token Bearer. Seul redirect_url est obligatoire :

  • redirect_url : une URL https où le client arrive ensuite.
  • channel : whatsapp, la valeur par défaut, ou un réseau social ouvert à votre compte, par son nom en minuscules, comme instagram, tiktok ou youtube.
  • external_ref : votre propre identifiant pour ce client, jusqu'à 200 caractères.
  • partner_name : le nom affiché sur la page hébergée, jusqu'à 80 caractères ; par défaut, le nom de votre compte.
  • webhook_url avec webhook_verify_token : pour les numéros uniquement, et toujours ensemble. Meta y envoie les messages du numéro dès sa connexion.
Create a session for a WhatsApp number
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"
  }'

Quelle est la réponse ?

Un 201 avec la session. Envoyez le client vers url, et conservez id, qui commence par cs_, pour retrouver la session plus tard. expires_at correspond à une heure après la création, et connection_id ou channel_id se remplit dès que le client se connecte, selon le canal de la session. GET /connect-sessions/:id renvoie la même structure à tout moment.

201 Created
{
  "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"
}

Quelles erreurs la création d'une session peut-elle renvoyer ?

Chaque erreur a le même corps, un objet avec un code et un message, et le message indique quoi corriger. La création d'une session peut renvoyer :

  • 400 invalid_json ou invalid_request : le corps n'est pas un objet JSON, ou un champ n'a pas passé la validation, par exemple un redirect_url qui n'est pas en https.
  • 400 channel_unavailable : le canal n'est pas ouvert à ce compte ; le message liste ceux qui le sont.
  • 401 unauthorized : la clé d'API est absente ou invalide.
  • 402 billing_required : le compte n'a pas encore de carte, et tout ce qui est connecté via lui est facturé sur ce compte.
  • 429 cap_reached : 50 sessions sont déjà ouvertes ; attendez que certaines se terminent ou expirent.
  • 429 rate_limited : plus de 100 sessions cette heure-ci ; le message indique combien de temps attendre.

Où le client arrive-t-il ensuite ?

Sur votre redirect_url, avec le résultat ajouté à sa chaîne de requête. Le même résultat figure sur la session, que votre backend lit avec GET /connect-sessions/:id :

  • session : l'identifiant de la session, cs_ suivi de caractères aléatoires.
  • status : connected, ou cancelled lorsque le client a choisi « Cancel and go back ».
  • external_ref : votre identifiant pour le client, lorsque la session en portait un.
  • connection_id : l'identifiant du nouveau numéro, pour /connections.
  • channel_id : l'identifiant du nouveau compte social, pour /channels.
A number connected
https://app.example.com/connect/return?session=cs_…&status=connected&external_ref=customer_4821&connection_id=…

Quels statuts une session peut-elle avoir ?

Cinq. GET /connect-sessions/:id renvoie le statut actuel, avec opened_at, finished_at et last_error, qui indique pourquoi la dernière tentative a échoué :

  • created : créée par votre backend, pas encore ouverte.
  • opened : le client a chargé la page hébergée.
  • connected : un numéro ou un compte social s'est connecté, et son identifiant figure dans la session.
  • cancelled : le client a quitté la page via « Cancel and go back ».
  • expired : l'heure s'est écoulée avant la fin de la session.

Combien de temps un lien reste-t-il valable ?

Une heure après sa création. Ensuite, la page hébergée indique au client que le lien a expiré, avec un bouton de retour vers votre redirect_url marqué status=cancelled, et la session passe à expired. Un compte peut garder 50 sessions ouvertes et en créer 100 par heure, car Meta compte chaque première inscription contre une limite à l'échelle de l'application, partagée par tous les comptes.

À quoi sert external_ref ?

Il relie chaque connexion à votre client. La valeur envoyée est stockée sur le numéro ou le canal créé par la session, ajoutée à la redirection et incluse dans chaque événement de statut le concernant. Ainsi, GET /connections?external_ref=customer_4821 et GET /channels?external_ref=customer_4821 listent ce que ce client a connecté. Une connexion Facebook ou LinkedIn peut ramener plusieurs Pages d'un coup : la redirection nomme la première, et le filtre liste les autres. Utilisez un identifiant stable de votre propre base de données, et non un e-mail qui peut changer.

Que se passe-t-il si le client annule ou si la connexion échoue ?

Cela dépend de l'étape, et la session garde la trace :

  • La popup de Meta échoue ou est fermée : le client appuie à nouveau sur « Connect » sur la même page tant que le lien est ouvert.
  • Une connexion sociale est annulée ou refusée : le client revient sur la page hébergée avec la raison et peut réessayer jusqu'à l'expiration du lien.
  • Le compte est déjà connecté via un autre compte easyCoexistence : last_error le signale, et le client se connecte avec un autre compte.
  • Le client choisit « Cancel and go back » : votre redirect_url reçoit status=cancelled et la session se ferme, donc créez-en une nouvelle pour une autre tentative.
  • Le lien a expiré : créez une nouvelle session.

Que se passe-t-il si un numéro se connecte sans le token du client ?

Meta termine parfois Embedded Signup sans émettre le token de l'entreprise propre au client. La page hébergée demande alors une passe supplémentaire, qui prend quelques secondes. Si le client l'ignore, la session passe à connected avec token_ready à false, et votre URL d'événements reçoit connection.token_missing : le numéro reçoit les messages, puisque ses identifiants sont valides, mais ne peut pas envoyer tant qu'une nouvelle session de connexion ne le reconnecte pas et n'émet le token.

Que se passe-t-il si le webhook_url échoue au contrôle de Meta ?

Le numéro se connecte quand même. Meta vérifie un webhook_url par une poignée de main GET, que votre endpoint valide en renvoyant hub.challenge lorsque hub.verify_token correspond. En cas d'échec, last_error de la session commence par webhook_url was not applied et donne la raison de Meta, et PUT /connections/:id/webhook définit la destination une fois que l'endpoint répond. Défini dans les 24 heures suivant la connexion, il reçoit encore l'import unique des contacts et, si le client a accepté de le partager, l'historique des discussions.

Que voit le client ?

Une page sur easycoexistence.com avec votre nom tiré de partner_name, sans compte, e-mail ni carte à remplir. Pour un numéro WhatsApp, elle affiche une courte liste de contrôle d'éligibilité, puis la popup de Meta et un QR code à scanner avec l'application WhatsApp Business. Pour un compte social, elle affiche un seul bouton, par exemple « Continue with TikTok », qui ouvre l'écran de consentement du réseau dans le même onglet, donc cela fonctionne aussi sur téléphone.

Erreurs courantes

  • Faire confiance à la chaîne de requête seule. N'importe qui peut taper status=connected dans une URL ; confirmez donc avec GET /connect-sessions/:id depuis votre backend avant de marquer le client comme connecté.
  • Intégrer le lien dans une iframe. Envoyez le client vers lui par une redirection ou un nouvel onglet, c'est ainsi que la page hébergée et les connexions qu'elle ouvre sont conçues pour fonctionner.
  • Créer des liens à l'avance. Chaque lien est valable une heure et chaque session ouverte compte dans la limite de 50 ; créez donc la session au moment où le client va se connecter.
  • Envoyer un webhook_url de plus de 200 caractères. Meta accepte des URL de rappel alternatives de 200 caractères au maximum ; une URL plus longue n'est pas appliquée et le numéro se connecte sans elle.
Faire cela avec EasyCoexistence

easyCoexistence connecte les numéros WhatsApp de vos clients ainsi que leurs comptes Instagram, Facebook, TikTok, YouTube et LinkedIn, et d'autres canaux encore, à votre logiciel grâce à un seul lien hébergé, puis transmet à votre backend les identifiants de chaque connexion, ses webhooks et des événements de statut signés. De US$ 9 à US$ 0,75 par connexion et par mois, en baisse à mesure que vous ajoutez des connexions, avec un essai gratuit de 3 jours.

Questions fréquemment posées

Un même lien de connexion peut-il servir deux fois ?

Non. Un lien se termine avec un numéro, ou avec une seule connexion sociale, qui sur Facebook ou LinkedIn peut ramener plusieurs Pages. Ensuite, il passe à connected : créez une nouvelle session pour la connexion suivante.

Puis-je envoyer le lien par e-mail ou par chat ?

Oui, tant que le client l'ouvre dans l'heure. L'identifiant de session dans l'URL est ce qui autorise la page : n'envoyez donc chaque lien qu'au client pour lequel il a été créé.

La page hébergée fonctionne-t-elle sur téléphone ?

Les connexions sociales oui, puisqu'elles s'ouvrent dans le même onglet. Un numéro WhatsApp se connecte mieux depuis un ordinateur : sur téléphone, la popup de Meta s'ouvre dans un nouvel onglet, et le téléphone lui-même est nécessaire pour scanner le QR code.

Comment savoir qu'un client s'est connecté sans interroger l'API ?

Définissez une URL d'événements de statut dans le tableau de bord, sous Profile, Developers. easyCoexistence y envoie ensuite connection.connected ou channel.connected, signés et portant votre external_ref, dès que la connexion est établie.

Poursuivre la lecture

Connectez votre premier canal en deux minutes.

Aucune validation de plateforme à attendre. Connectez WhatsApp, Instagram, TikTok ou un autre canal, puis demandez à votre IA de publier, de répondre ou de faire un rapport, et regardez-la travailler.

  • 3 jours gratuits
  • Résiliable à tout moment
  • API officielles uniquement
  • Supervisé 24/7

Vérifié le