Obtenir un lien de connexion

Génère une URL de courte durée qui connecte une plateforme sociale à une marque. Vous ne manipulez jamais les identifiants OAuth de la plateforme : redirigez votre utilisateur final vers url, qui vous est renvoyé ; il remplit l’écran de consentement de la plateforme et choisit la Page, le tableau ou l’organisation sur lesquels publier, puis il est redirigé vers votre redirectUrl.

C’est la seule opération d’écriture de l’API Social dont le corps est à plat. Toutes les autres opérations d’écriture de l’API Social sont encapsulées dans un objet input ; celle-ci ne l’est pas. Envoyez channel, redirectUrl et, éventuellement, errorUrl et state au niveau racine.

Cas d’utilisation : connexion d’un canal en libre-service dans votre produit. Présentez les cinq plateformes à l’utilisateur et, lorsqu’il en choisit une, appelez cet endpoint avec le channel correspondant et un state qui identifie sa session. Redirigez-le vers url. Lorsqu’il revient sur votre redirectUrl avec status=success, interrogez périodiquement GET /social/brands/{brandId}/connections jusqu’à ce que le nouveau canal apparaisse, puis laissez-le rédiger sa première publication avec POST /social/posts.

Destination de retour de l’utilisateur

À la fin du parcours, l’utilisateur est redirigé vers votre redirectUrl (ou errorUrl), auquel sont ajoutés des paramètres de requête :

https://app.example.com/social/connected  ?status=success  &brandId=6f2c9a41-7b0e-4d55-9a2f-3c8e1d47b902  &platform=INSTAGRAM  &state=sess_9f2c1e64  &connectedAccountId=b81d5b3c-4a90-4f6a-9c11-71e0dd2fa4a7

Remarques.

• Le lien expire. expiresIn indique sa durée de validité en secondes. Il est à usage unique : générez-le au moment où l’utilisateur clique sur « connecter », jamais à l’avance, et ne le stockez jamais. Si l’utilisateur abandonne le parcours, appelez à nouveau cet endpoint pour obtenir une nouvelle URL.
• La connexion est créée de manière asynchrone. L’utilisateur revient sur votre redirectUrl un instant avant que l’enregistrement de la connexion existe ; une lecture de la liste des connexions effectuée immédiatement à son retour peut donc tout à fait ne pas la contenir. Interrogez périodiquement la liste des connexions pendant quelques secondes plutôt que de considérer la première lecture vide comme un échec.
• Instagram nécessite un compte Business ou Creator lié à une Page Facebook. Un compte Instagram personnel ne peut pas être connecté, et l’écran de consentement de la plateforme n’en proposera pas. Si vos utilisateurs rencontrent ce problème, demandez-leur de convertir leur compte dans l’application Instagram et de le lier à la Page qu’ils gèrent, puis générez à nouveau le lien.
• TWITTER désigne X. La valeur d’énumération est restée TWITTER pour assurer la rétrocompatibilité ; le produit est X. Les valeurs des plateformes sont des noms d’énumération en majuscules — l’envoi de "instagram" est rejeté.
• redirectUrl et errorUrl doivent être des URL https absolues. Une URL relative ou http est rejetée avec SY95049.
• Les connexions sont la ressource comptabilisée. Chaque lien puise dans un quota commun à l’ensemble du compte — 20 connexions avec Social Launch, 125 avec Social Growth, plus cinq pour chaque pack de connexions à 25 $/mois, jusqu’à un plafond de 250 en libre-service. Le nombre de marques est illimité ; c’est donc toujours cet appel, jamais la création d’une marque, qui épuise la capacité disponible. Lorsque le quota est entièrement utilisé, la demande de lien renvoie status: "failed" avec SY95042. Consultez Forfaits et options supplémentaires et obtenez votre capacité restante à partir de GET /social/limits.
• Il s’agit de l’équivalent, dans l’API Social, du lien de connexion Facebook au niveau d’un établissement, mais ce sont deux produits distincts et les connexions établies dans l’un ne sont pas visibles dans l’autre.

Opération d’écriture : non exécutée sur le compte réel. La requête et la réponse présentées sont construites à partir du schéma de l’API.