Référence sur l’API Attachment Upload

ATTENTION : les ID de pièces jointes expirent au bout de 90 jours. Une fois les ID arrivés à expiration, vous devrez réimporter votre contenu multimédia pour obtenir de nouveaux ID.

Si les pièces jointes réutilisables expirent au bout de 90 jours sans possibilité de renvoi, celles associées aux fils de discussion n’expirent jamais et restent visibles jusqu’à la suppression du message du fil. Selon le cas, vous pouvez combiner les étapes d’importation et d’envoi mentionnées ci-dessous afin d’éviter ce problème TTL.

L’API Attachment Upload permet d’importer des éléments qui peuvent être envoyés ultérieurement dans des messages. Ainsi, vous évitez d’importer plusieurs fois des fichiers couramment utilisés. L’API permet d’enregistrer des éléments à partir d’une URL ou d’un système de fichier local.

Vous pouvez également utiliser l’API Send pour réaliser simultanément l’envoi d’un message avec pièce jointe et l’enregistrement de la pièce jointe pour la réutiliser ultérieurement. Pour plus d’informations, reportez-vous à la section Importer et envoyer ci-dessous.

Importer une pièce jointe

Pour importer une pièce jointe, envoyez une requête POST au point de terminaison /Your-page-id/message_attachments avec message.attachment associée à type et payload. Pour pouvoir utiliser l’élément dans plusieurs messages, définissez payload.is_reusable sur true.

Exemple de requête d’importation à partir d’une URL

Le code a été mis en forme pour plus de lisibilité. Remplacez les valeurs en gras et en italique, telles que page_access_token, par vos propres valeurs.

curl -X POST "https://graph.facebook.com/v21.0/Your-page-id/message_attachments" \
     -H "Content-Type: application/json" \
     -d '{
           "access_token":"Your_page_access_token",
           "message":{
             "attachment":{
               "type":"image", 
               "payload":{
                 "url":"https://your-url.com/image.jpg",
                 "is_reusable": true
               }
             }
           }
         }'

Exemple de requête d’importation à partir d’un fichier

Le code a été mis en forme pour plus de lisibilité. Remplacez les valeurs en gras et en italique, telles que page_access_token, par vos propres valeurs.

curl -X POST -H "Content-Type: application/json" -d '{
   "message": {
     "attachment": {
       "type": "image"
     }
   },
   "filedata": "@/path-to-your-file/image.jpg",
   "type": "image/png"
  }' "https://graph.facebook.com/v21.0/{PAGE_ID}/message_attachments?access_token={PAGE_ACCESS_TOKEN}"

En cas de réussite votre application reçoit un objet JSON avec attachment_id défini sur l’ID de votre pièce jointe à utiliser dans vos messages.

{"attachment_id": "Your-attachment-ID"}

Envoyer un message avec un élément importé

Pour envoyer un message avec un élément que vous avez précédemment importé, avec message.attachment.payload.is_reusable défini sur true, envoyez une requête POST au point de terminaison /Your-page-id/messages avec recipient.id, et l’objet message.attachment associé à type et payload.attachment_id.

Exemple de requête d’importation à partir d’un fichier

Le code a été mis en forme pour plus de lisibilité. Remplacez les valeurs en gras et en italique, telles que page_access_token, par vos propres valeurs.

curl -X POST -H "Content-Type: application/json" -d '{
    "recipient": {
      "id": "{PSID}"
    },
    "message": {
      "attachment": {
        "type": "image",
        "payload": {
          "attachment_id": "Your-attachment-ID"
        }
      }
    }
  }' "https://graph.facebook.com/v21.0/{PAGE_ID}/messages?access_token={PAGE_ACCESS_TOKEN}"

En cas de réussite, votre application reçoit un objet JSON avec success défini sur true.

{"success": "true"}

Importer et envoyer

Vous pouvez importer du contenu multimédia et l’envoyer dans une même requête d’API.

ATTENTION : Dans ce cas, ne définissez pas is_public=true dans la charge utile. Les pièces jointes des fils de discussion de l’utilisateur·ice sont toujours privées.

Exemple de requête d’importation à partir d’une URL

Le code a été mis en forme pour plus de lisibilité. Remplacez les valeurs en gras et en italique, telles que page_access_token, par vos propres valeurs.

curl -X POST -H "Content-Type: application/json" -d '{
   "recipient": {
     "id": "{PSID}"
   },
   "message": {
     "attachment": {
       "type": "image",
       "payload": {
         "url": "https://your-url.com/image.jpg"
       }
     }
   }
  }' "https://graph.facebook.com/v21.0/{PAGE_ID}/messages?access_token={PAGE_ACCESS_TOKEN}"

En cas de réussite, votre application reçoit un objet JSON avec success défini sur true.

{"success": "true"}

Propriétés

Pour joindre des éléments à partir d’une URL, vous devez préciser les propriétés suivantes dans le corps de la demande en tant qu’objet JSON. Quand la source de l’élément est un fichier, envoyez les propriétés sous forme de données de formulaire.

`message`

Description of the message to be sent.

Property	Type	Description
`message.attachment`	Object	An object describing attachments to the message.

`message.attachment`

Propriété	Type	Description
`type`	Chaîne	Type de la pièce jointe. Valeurs possibles : image Video audio file
`payload`	Objet	Objet `payload` qui décrit la pièce jointe.

`message.attachment.payload`

Propriété Type Description

Propriété	Type	Description
`url`	Chaîne	*Facultatif.* URL du fichier à importer. Taille maximale : 8 Mo pour les fichiers image, 25 Mo pour les autres types de fichiers (après encodage). Délai d’expiration appliqué : 75 s pour les vidéos, 10 s pour tous les autres types de fichiers.
`is_reusable`	Booléen	**Facultatif, false par défaut.Ne définissez pas cette propriété sur `true` si vous importez et envoyez votre contenu multimédia dans un même appel d’API. Définissez-la sur true uniquement** lorsque vous importez et envoyez votre contenu dans des étapes distinctes. Les ID de pièces jointes expirent au bout de 90 jours. Après ce délai, réimportez votre contenu multimédia pour obtenir de nouveaux ID de pièces jointes. Si les pièces jointes réutilisables expirent au bout de 90 jours sans possibilité de renvoi, celles associées aux fils de discussion n’expirent jamais et restent visibles jusqu’à la suppression du message du fil.

url

Chaîne

Facultatif. URL du fichier à importer. Taille maximale : 8 Mo pour les fichiers image, 25 Mo pour les autres types de fichiers (après encodage). Délai d’expiration appliqué : 75 s pour les vidéos, 10 s pour tous les autres types de fichiers.

is_reusable

Booléen

Facultatif, false par défaut.Ne définissez pas cette propriété sur true si vous importez et envoyez votre contenu multimédia dans un même appel d’API.

Définissez-la sur true uniquement lorsque vous importez et envoyez votre contenu dans des étapes distinctes. Les ID de pièces jointes expirent au bout de 90 jours. Après ce délai, réimportez votre contenu multimédia pour obtenir de nouveaux ID de pièces jointes.

Codes d’erreur

Code d’erreur	Sous-code	Message
100	2018074	ID non valide ou vous n’êtes pas propriétaire de la pièce jointe.
100	2018008	Impossible de récupérer le fichier à partir de l’URL. Vérifiez que l’URL, le certificat SSL associé et la taille du fichier sont valides, et que le serveur répond dans les temps afin d’éviter toute expiration.
100	2018294	Expiration du délai d’importation de la vidéo ou vidéo corrompue. Remarque : au-delà de 75 secondes, la demande du fichier vidéo expirera
100	2018047	Échec du téléchargement de la pièce jointe. Cette erreur survient souvent quand le type de contenu multimédia indiqué ne correspond pas au type de fichier récupéré à partir de l’URL