Vue d'ensemble de l'API Post - Ayrshare API Documentation

Le point de terminaison post vous permet de publier des publications sur les réseaux sociaux : Bluesky, Facebook, Google Business Profile, Instagram, LinkedIn, Pinterest, Reddit, Snapchat, Telegram, TikTok, X/Twitter et YouTube. De nombreuses options permettent de personnaliser votre publication, comme la planification, l’ajout de hashtags automatiques, la planification de publication automatique, et bien plus encore. Cette fonctionnalité est souvent utilisée par les agences lorsque plusieurs parties prenantes doivent approuver une publication avant sa diffusion. Commencez à publier avec le point de terminaison POST /post.

Workflow d’approbation

Si votre workflow de publication nécessite une approbation avant l’envoi d’une publication, définissez le champ requiresApproval sur true. Cela revient à mettre la publication en pause jusqu’à ce que le paramètre approved soit défini sur true.

Exemple de workflow d’approbation

La publication aura le statut « awaiting approval » (en attente d’approbation) jusqu’à ce que le paramètre approved soit défini sur true via le point de terminaison PATCH /post.

Publier avec des paramètres

Publiez votre publication à l’aide du point de terminaison /post avec le champ requiresApproval défini sur true. Vous pouvez également inclure des paramètres standards comme scheduleDate.

Le statut est « en attente d'approbation »

La publication sera au statut « awaiting approval » et sera retenue jusqu’à ce que l’approbation soit accordée.

Approuver la publication

Mettez à jour la publication avec l’opération PATCH /post en définissant le champ approved sur true. La publication sera alors envoyée à la date planifiée.

Utiliser les notes

Facultatif : définissez notes sur la publication à titre de référence, par exemple pour indiquer qui doit l’approuver.

Publish the Post with Approval

{
  "requiresApproval": true,
  "notes": "need approval by John Smith" // optional
}

Si scheduleDate est renseigné et que la date est passée, la publication sera diffusée immédiatement après l’approbation.

Vidéo du workflow d’approbation

Consultez la vidéo ci-dessous pour un exemple de workflow d’approbation.

Auto Hashtags

Ajoutez les hashtags les plus pertinents à votre publication. autoHashtag est un objet, ou un booléen — voir ci-dessous —, avec les paramètres suivants :

max : (facultatif) nombre entier de hashtags à ajouter, entre 1 et 10. 2 par défaut.
position : (facultatif) chaîne « auto » ou « end ». « auto » insère les hashtags dans la publication ou à la fin. « end » ajoute les hashtags uniquement à la fin.

Un plan payant est requis.

{
  "hashtags": {
    "max": 3, // optional: Integer range 1-10
    "position": "auto" // optional: String "auto" or "end"
  }
}

Si vous ne souhaitez envoyer aucune des options ci-dessus, transmettez la valeur booléenne true au lieu d’un objet.

{
  "autoHashtag": true
}

Auto Repost

Republie automatiquement votre contenu plusieurs fois à intervalles réguliers, créant un contenu evergreen qui reste frais et visible auprès de votre audience. Un plan payant est requis. Paramètres :

repeat : (obligatoire) nombre de fois où republier le contenu. Doit être compris entre 1 et 10.
days : (obligatoire) nombre de jours entre chaque republication. Minimum 2 jours.
startDate : (facultatif) date de début de la planification des republications, au format UTC ISO-8601. Si non spécifié, la première publication est diffusée immédiatement. Utilisez le paramètre startDate à la place du paramètre scheduleDate de premier niveau.

Auto Repost

{
  "repeat": 2, // min 2, max 10
  "days": 5, // min 2
  "startDate": "2021-07-08T12:30:00Z"
}

La réponse inclura toutes les republications planifiées à venir et un autoRepostId pour chacune.

Auto Repost Response

{
  "status": "scheduled",
  "scheduleDate": "2025-06-13T12:30:00.000Z",
  "id": "eIT96IYEodNuzU4oMmwG",
  "refId": "9abf1426d6ce9122ef11c72bd",
  "autoRepostId": "F5wdoaOAAGtDQVciExSxL",
  "post": "The most important things are the hardest to say - Stephen King"
}

Lors de la création d’une republication automatique, un ID autoRepostId est attribué pour suivre cette série de publications. Vous pouvez récupérer toutes les republications automatiques d’une publication avec l’appel History et l’autoRepostId. Si vous devez supprimer une republication, utilisez l’appel DELETE avec l’ID de la publication.

Important : lorsque vous utilisez la republication automatique, veillez à respecter les recommandations de fréquence de publication de chaque réseau social afin d’éviter toute restriction de compte.Remarque : la fonctionnalité autoRepost ne peut pas être utilisée conjointement avec scheduleDate. Si vous incluez les deux paramètres, scheduleDate prend la priorité et autoRepost est ignoré. Utilisez plutôt le paramètre startDate.

Premier commentaire

Ajoutez automatiquement un premier commentaire, avec un média, après la publication. Pour TikTok, le commentaire est différé jusqu’à ce que la vidéo ait fini d’être traitée (voir Délai de traitement du premier commentaire). Publier le premier commentaire sur votre propre publication peut aider à amorcer l’engagement et à donner le ton de la discussion qui suit.

{
  "firstComment": {
    "comment": "My first comment", // required
    "mediaUrls": ["https://..."] // Facebook, LinkedIn, and X/Twitter only
  }
}

Délai de traitement du premier commentaire

Pour la plupart des réseaux sociaux, la réponse de l’API est retardée car notre système doit (1) attendre que la publication d’origine soit entièrement diffusée, puis (2) ajouter le commentaire à cette publication. Ce processus séquentiel ajoute un délai d’environ 20 secondes. TikTok est géré différemment. TikTok traite les vidéos de manière asynchrone : l’id de la publication reste "pending" jusqu’à ce que le webhook post.publish.publicly_available de TikTok résolve l’ID réel de la vidéo (voir Traitement TikTok). La réponse /post renvoie donc immédiatement le premier commentaire TikTok avec status: "pending", et le commentaire est publié automatiquement une fois que TikTok a terminé le traitement et que le webhook Scheduled Action tikTokPublished est déclenché. TikTok ne garantit pas de délai de traitement, il n’y a donc pas de délai fixe. Remarque importante concernant TikTok : pour que les premiers commentaires fonctionnent correctement sur TikTok, le paramètre visibility de la publication doit être défini sur public. Une vidéo non publique ne reçoit jamais le webhook publicly_available, donc son premier commentaire ne peut pas être publié ; dans ce cas, Ayrshare renvoie une erreur de commentaire au lieu de le laisser en attente.

Publications idempotentes

L’idempotence est une fonctionnalité facultative qui garantit qu’une requête n’est exécutée qu’une seule fois, même si elle est envoyée plusieurs fois par erreur. Lorsque vous publiez du contenu via l’API, vous pouvez inclure un paramètre facultatif idempotencyKey dans le corps de la requête pour identifier l’opération de manière unique. Cela permet de réessayer la requête de publication en toute sécurité, sans risque de créer des publications en double. Pour utiliser l’idempotence, ajoutez le paramètre idempotencyKey dans le corps JSON de la requête POST /post :

Idempotency Key

{
  "idempotencyKey": "Unique Key"
}

La valeur de idempotencyKey doit être une chaîne unique par User Profile. Si une requête est effectuée avec la même idempotencyKey pour un User Profile donné, quel que soit l’état de la publication (success, error, pending ou supprimée), une erreur sera renvoyée indiquant qu’une clé en double a été trouvée.

L’API doit d’abord accepter et traiter la requête POST pour stocker la clé d’idempotence et vérifier les doublons. Cependant, si plusieurs requêtes POST avec la même idempotencyKey sont envoyées simultanément ou planifiées pour la même heure de publication, l’API peut ne pas détecter les clés en double. En effet, l’API traite ces requêtes concurrentes ou planifiées simultanément en parallèle, avant d’avoir eu la possibilité d’enregistrer la clé d’idempotence d’une requête individuelle. Par conséquent, il n’y a aucune garantie que les clés idempotentes en double soient détectées dans ces scénarios de soumission simultanée ou d’exécution simultanée de publications planifiées.

L’idempotence contribue à éviter la création accidentelle de publications en double lorsque vous relancez des requêtes ayant échoué ou gérez des problèmes réseau. Cependant, il est toujours recommandé de mettre en place une gestion appropriée des erreurs et des mécanismes de nouvelle tentative dans votre application afin de gérer les défaillances éventuelles avec élégance.

Exigences relatives aux images et vidéos

La publication d’images et de vidéos comporte des exigences différentes selon chaque réseau, mais pas d’inquiétude : notre système vérifie votre publication avant l’envoi, et vous recevrez une réponse d’erreur si quelque chose ne va pas. Consultez le lien ci-dessous pour connaître les détails sur les recommandations en matière d’images et de vidéos.

Recommandations pour les images et vidéos

URL valide

Assurez-vous que vos URL de médias sont valides et permettent un accès direct au média. Un premier test consiste à ouvrir l’URL dans un navigateur. Si l’image ne se charge pas ou ne peut pas être téléchargée dans un navigateur, elle échouera probablement. Par exemple, une URL DropBox qui ouvre l’application web DropBox ne fonctionnera pas.

Si vous disposez d’une URL de partage Google Drive ou d’une URL de partage Dropbox, vous pouvez simplement utiliser l’URL dans le paramètre mediaUrls lors de la publication d’une publication ou d’un commentaire. Ayrshare convertira automatiquement l’URL de partage en un lien de téléchargement direct.

Nous vérifions l’URL du média en effectuant une requête HEAD. Assurez-vous que l’hébergeur ne bloque pas la requête HEAD, sans quoi la publication échouera avec une erreur 403. Par exemple, voici une requête HEAD vers l’URL d’un média :

Fetch HEAD Request

const run = async () => {
  const url = "https://img.ayrshare.com/012/gb.jpg";
  return await fetch(url, {
    method: "HEAD"
  })
    .then((res) => {
      if (res.ok) {
        return console.log("Success:", res.status, res.statusText);
      } else {
        return console.error("Error:", res.status, res.statusText, res);
      }
    })
    .catch((error) => {
      return console.error("Error Catch:", error);
    });
};

run();

Protection automatisée des médias

Ayrshare intègre une protection des médias intégrée capable de détecter et de résoudre certains problèmes de diffusion de médias lors de la publication. Lorsqu’une publication réussit mais qu’un problème de contenu a été détecté et résolu, chaque entrée concernée dans postIds[] inclut un objet facultatif contentIssues afin que vous puissiez identifier et corriger le problème sous-jacent :

{
    "postIds": [
        {
            "status": "success",
            "platform": "instagram",
            "id": "17878176260289172",
            "postUrl": "https://www.instagram.com/p/CP1dI9Hp_WO/",
            "contentIssues": {
                "originMediaHostFailed": true,
                "details": ["Media URL could not be retrieved by the social network. Successfully posted using Ayrshare automated media protection."]
            }
        }
    ]
}

Si vous voyez originMediaHostFailed dans vos réponses, vérifiez la configuration de l’hébergement de vos médias. Consultez Meta Media Crawler Blocked pour connaître les causes et solutions les plus courantes.

Espaces et caractères spéciaux

Nous vous recommandons d’éviter les éléments suivants dans vos URL de médias :

Les espaces dans l’URL.
Les espaces encodés dans l’URL.
Les caractères spéciaux dans l’URL, même s’ils sont encodés, tels que les accents « é ».

Par exemple :

https://img.ayrshare.com/012/test .webp

Cette URL échoue à cause de l’espace test .webp. Nous déconseillons également l’utilisation d’espaces encodés dans l’URL, tels que %20 — cela peut également causer des problèmes avec certains réseaux sociaux. Et cette image Unsplash :

https://unsplash.com/photos/a-house-in-the-middle-of-a-field-with-trees-in-the-background-znbmh2-cIj0

Cette image Unsplash échoue parce qu’elle n’accède pas directement à l’image, mais affiche une application web.

Assainir les noms de fichiers et les URL

Vous pouvez assainir vos noms de fichiers à l’aide d’une expression régulière telle que /[^a-z0-9\/\.]/gi.

const sanitizeFileName = (url) => url.replace(/[^a-z0-9\/\.]/gi, "_");
sanitizeFileName("tést .webp"); // t_st_.webp

ou assainir une URL

const sanitizeUrl = (url) => {
  const [protocol, rest] = url.split("://");
  const [domain, ...path] = rest.split("/");
  const sanitizedPath = path.join("/").replace(/[^a-z0-9\/\.]/gi, "_");
  return `${protocol}://${domain}/${sanitizedPath}`;
};

// Output: https://img.ayrshare.com/012/t_st_.webp
sanitizeUrl("https://img.ayrshare.com/012/tést .webp");

Informations complémentaires

Si vous auto-hébergez, assurez-vous que l’URL est accessible depuis l’extérieur et ne nécessite pas d’autorisations spéciales.
Voyez ci-dessous comment gérer les vidéos avec des extensions inconnues, souvent des URL signées comme AWS S3.
Si vous utilisez une URL signée, comme S3, nous recommandons de définir l’expiration de l’URL à au moins 7 jours. Cela permet à notre équipe de vous assister pour toute question sur la publication.
Vérifiez l’existence de l’URL du média avec nos outils de vérification de média.

Vitesse de téléchargement

Assurez-vous que votre hébergement de médias dispose d’une connexion rapide, notamment en vitesse de téléchargement. Vous pouvez tester les performances de votre hébergement sur pingdom. Nous recommandons au moins une note B.

Extension vidéo

Si votre URL ne se termine pas par une extension vidéo connue telle que mp4, vous pouvez utiliser le champ isVideo: true dans la publication pour spécifier que le mediaUrl est une vidéo. Ayrshare tentera de déterminer le type de fichier, par exemple MOV. Cependant, nous recommandons de terminer explicitement votre fichier vidéo par une extension connue telle que mp4, car cela offre un taux de réussite plus élevé auprès des réseaux sociaux.

Image ou vidéo uniquement

Quelques réseaux sociaux prennent en charge l’envoi de médias sans texte de publication. Si vous ne souhaitez pas inclure de texte, envoyez une chaîne vide : post: "" Les réseaux sociaux suivants prennent en charge les publications sans texte : Facebook, Instagram, LinkedIn, Threads, TikTok et X/Twitter.

Tester les images et vidéos

Envisagez d’utiliser générer du texte aléatoire et une image ou vidéo aléatoire pour accélérer vos tests. Arrêtez d’essayer de trouver quelque chose de différent pour chacune de vos publications de test !

Sauts de ligne

Si vous souhaitez insérer des sauts de ligne (nouvelles lignes) dans une publication, utilisez le saut de ligne invisible \u2063\n. Par exemple, This is a new\u2063\nline.Nous recommandons également d’essayer dans Postman pour voir comment le nouveau saut de ligne est traduit dans votre langage. Par exemple, PHP n’utilise souvent qu’un \n.Certains réseaux sociaux ne prennent actuellement pas en charge les sauts de ligne dans le texte de la publication.

Publications et médias multi-plateformes

Cette fonctionnalité vous permet de personnaliser le contenu et les médias de votre publication pour différents réseaux sociaux au sein d’un seul appel API. Vous pouvez spécifier du texte et/ou des images uniques pour chaque plateforme en utilisant des objets pour les champs post et mediaUrls.

Utilisez une structure d’objet pour les champs post et/ou mediaUrls.
Spécifiez le contenu propre à chaque plateforme en utilisant les noms des plateformes comme clés.
Incluez une clé default pour le contenu à utiliser sur les plateformes qui ne sont pas explicitement spécifiées.

{
  "post": {
    "instagram": "Great IG pic!",
    "facebook": "Great FB pic!",
    "default": "Great default pic!"
  },
  "platforms": ["instagram", "facebook", "linkedin"],
  "mediaUrls": {
    "instagram": "https://img.ayrshare.com/012/gb.jpg",
    "linkedin": "https://img.ayrshare.com/012/gb.jpg",
    "default": "https://img.ayrshare.com/012/gb.jpg"
  }
}

Dans l’exemple ci-dessus :

Instagram utilisera son texte et son URL d’image spécifiques.
Facebook utilisera son texte spécifique et l’URL d’image par défaut.
LinkedIn utilisera le texte par défaut et son URL d’image spécifique.

Si vous devez publier plusieurs images sur différentes plateformes, créez des publications distinctes pour chaque plateforme au lieu d’utiliser cette structure multi-plateformes.

Profile Keys

Publiez pour le compte d’un utilisateur en fournissant les Profile Keys des utilisateurs comme paramètre de corps et les données supplémentaires dans la réponse. Business Plan ou Enterprise Plan requis.

Profiles

Publications en texte enrichi

Vous pouvez ajouter du texte enrichi comme « 𝓗𝓮𝓵𝓵𝓸, how about a little 𝗯𝗼𝗹𝗱 𝘁𝗲𝘅𝘁 and 𝘪𝘵𝘢𝘭𝘪𝘤𝘴 𝘵𝘦𝘹𝘵 and an x₂ ? ». Vous pouvez utiliser le texte enrichi sur des réseaux tels que Twitter, Facebook, LinkedIn, Telegram et Instagram. Si vous publiez sur Reddit, utilisez le formatage Markdown propre à Reddit. Des éléments HTML sont utilisés pour spécifier le type de texte enrichi, qui est converti en unicode. Par exemple :

{
    "post": "<var>Hello</var>, how about a little <b>bold text</b> and <i>italics text</i> and an x<sub>2</sub>?"
    "platforms": ["twitter"]
}

Éléments HTML

HTML	Exemple
<b>Nice One!</b>	Nice One!
<strong>Hello, world!</strong>	Hello, world!
<em>World</em>	World
normal <i>italics <b>bold italics</b></i>	normal italics bold italics
`<b>Hello</b>, world!`	`Hello, world!`
`<b>Hello</b>, world!`	`Hello``, world!`
<samp>123</samp>	𝟷𝟸𝟹
<var>Hello</var>	𝓗𝓮𝓵𝓵𝓸
x<sub>2</sub>	x₂
x<sup>2</sup>	x²

Codes CSS

Code	Exemple	Résultat
\u00B0	It’s 25\u00B0C today!	It’s 25°C today!
\u2063\n	This is a new\u2063\nline.	This is a new line.

Planifier des publications

Créer des publications planifiées

Vous pouvez planifier des publications futures en spécifiant le paramètre scheduleDate avec la date et l’heure au format Zulu/UTC. L’heure Zulu, également appelée temps universel coordonné (UTC), est la norme mondiale pour l’heure. Par exemple, utilisez le format YYYY-MM-DDThh:mm:ssZ et envoyez 2026-07-08T12:30:00Z. Consultez utctime pour plus d’exemples.

{
  "post": "Hello, world!",
  "mediaUrls": ["https://img.ayrshare.com/012/gb.jpg"],
  "platforms": ["facebook", "instagram"],
  "scheduleDate": "2023-07-08T12:30:00Z"
}

Consultez https://www.utctime.net/ pour savoir comment convertir votre heure locale en heure Zulu/UTC. Si la date et l’heure planifiées sont dans le passé, la publication sera envoyée immédiatement.

Si un mediaUrl est inclus avec une publication planifiée, le média doit être disponible au moment de la publication planifiée. Par exemple, si la publication est planifiée pour le 5 mars 2026, le média doit être disponible le 5 mars 2026.

Gestion des erreurs pour les publications planifiées vs immédiatesIl existe une différence importante dans la gestion des erreurs de validation entre les publications immédiates et planifiées :

Publications immédiates
- Lorsque vous publiez immédiatement (sans scheduleDate), si une plateforme échoue aux contrôles de validation, les autres plateformes continueront à être traitées. Par exemple, si une publication dépasse la limite de caractères de Twitter mais est valide pour Facebook et Instagram, la publication échouera sur Twitter mais sera néanmoins diffusée sur Facebook et Instagram.
Publications planifiées
- Lorsque vous planifiez des publications pour une diffusion future (avec scheduleDate), toutes les plateformes doivent passer les contrôles de validation initiaux avant que la publication ne soit planifiée. Si une plateforme échoue à ces contrôles de pré-validation, l’ensemble de l’opération de planification est rejeté et une erreur est renvoyée immédiatement.
- Cependant, certaines erreurs propres à une plateforme peuvent ne pas être détectées avant l’heure de publication réelle. Dans ces cas, la publication planifiée tentera d’être diffusée sur toutes les plateformes, et les échecs individuels par plateforme seront signalés dans les résultats finaux sans affecter les autres plateformes.

Vérifier le statut d’une publication planifiée

Vous pouvez vérifier le statut d’une publication planifiée de plusieurs manières :

Configurez le Webhook Scheduled Action pour recevoir automatiquement le statut de la publication planifiée. Disponible pour le Business Plan, c’est la méthode recommandée.
Récupérez le statut d’une publication planifiée avec l’appel GET et l’ID de la publication.
Vérifiez le statut dans le tableau de bord Ayrshare. Basculez d’abord vers le User Profile sous lequel la publication a été publiée, puis rendez-vous sur la page « Posts » et effectuez une recherche à l’aide de l’Ayrshare Post ID.

Mettre en pause des publications planifiées

Vous pouvez mettre en pause des publications planifiées qui n’ont pas encore été diffusées. Mettre une publication planifiée en pause l’empêche d’être diffusée jusqu’à sa reprise. Utilisez l’appel PATCH pour mettre en pause ou reprendre la publication planifiée. Notez que si une publication est reprise et que scheduleDate est dans le passé, la publication sera diffusée immédiatement. Envisagez de mettre à jour scheduleDate avant de reprendre la publication.

Raccourcir les liens

Les liens d’une publication peuvent être raccourcis à l’aide du raccourcisseur de liens d’Ayrshare. Vous pouvez activer le raccourcissement automatique des liens avec le paramètre shortenLinks lors de l’envoi d’une publication. Max Pack requis.

{
  "post": "Hello, world with a link https://www.ayrshare.com",
  "platforms": ["linkedin"],
  "shortenLinks": true
}

Images Unsplash

Les champs suivants sont disponibles pour le paramètre unsplash du corps :

Image aléatoire : random renvoie une image Unsplash aléatoire.
Image basée sur une recherche : valeur String contenant un terme de recherche ; par ex. money sélectionnera une image aléatoire liée à l’argent.
IDs d’images : valeur Array d’IDs ; par ex. [“HubtZZb2fCM”] correspondant à l’image https://unsplash.com/photos/HubtZZb2fCM

{
  "post": "Hello, world!",
  "platforms": ["instagram"],
  "unsplash": "random",
  "unsplash": "search term", // unsplash: "money"
  "unsplash": ["unsplash image ID"] // unsplash: ["HubtZZb2fCM"]
}

Si vous copiez une URL Unsplash pour la publier dans mediaUrls, veillez à copier l’adresse de l’image et pas uniquement l’URL. Consultez cet exemple pour plus d’informations.

​Workflow d’approbation

​Exemple de workflow d’approbation

​Vidéo du workflow d’approbation

​Auto Hashtags

​Auto Repost

​Premier commentaire

​Délai de traitement du premier commentaire

​Publications idempotentes

​Exigences relatives aux images et vidéos

Recommandations pour les images et vidéos

​URL valide

​Protection automatisée des médias

​Espaces et caractères spéciaux

​Assainir les noms de fichiers et les URL

​Informations complémentaires

​Vitesse de téléchargement

​Extension vidéo

​Image ou vidéo uniquement

​Tester les images et vidéos

​Sauts de ligne

​Publications et médias multi-plateformes

​Profile Keys

Profiles

​Publications en texte enrichi

​Éléments HTML

​Codes CSS

​Planifier des publications

​Créer des publications planifiées

​Vérifier le statut d’une publication planifiée

​Mettre en pause des publications planifiées

​Raccourcir les liens

​Images Unsplash

Workflow d’approbation

Exemple de workflow d’approbation

Vidéo du workflow d’approbation

Auto Hashtags

Auto Repost

Premier commentaire

Délai de traitement du premier commentaire

Publications idempotentes

Exigences relatives aux images et vidéos

URL valide

Protection automatisée des médias

Espaces et caractères spéciaux

Assainir les noms de fichiers et les URL

Informations complémentaires

Vitesse de téléchargement

Extension vidéo

Image ou vidéo uniquement

Tester les images et vidéos

Sauts de ligne

Publications et médias multi-plateformes

Profile Keys

Publications en texte enrichi

Éléments HTML

Codes CSS

Planifier des publications

Créer des publications planifiées

Vérifier le statut d’une publication planifiée

Mettre en pause des publications planifiées

Raccourcir les liens

Images Unsplash