Creatività

​

Panoramica

I creative sono qualsiasi entità che può essere promossa in una campagna. I Post possono includere testo, immagini, GIF, video o card. Le card possono includere immagini o video.

I creative basati su immagini, GIF o video vengono caricati utilizzando POST media/upload — un endpoint di upload semplice che supporta solo le immagini — oppure gli endpoint POST media/upload (chunked). Questi possono essere aggiunti a

card:

• POST accounts/:account_id/cards Tweet:
• POST accounts/:account_id/tweets - Per aggiungere card ai Tweet, utilizzare il parametro card_uri. Tweet programmati:
• POST accounts/:account_id/scheduled_tweets

Per ulteriori dettagli sulle card, consultare la pagina Cards. La pagina Promoted Video fornisce dettagli sull’associazione dei video con card o Tweet.

​

Schede

La X Ads API supporta diversi tipi di schede utilizzabili nei Tweet, che possono poi essere promosse nelle campagne. Nota: una volta pubblicato un Tweet, i dettagli della scheda diventano pubblici. Ciò può includere informazioni sull’utente proprietario della scheda.

​

Immagine

Le seguenti specifiche si applicano alle risorse utilizzate nelle Cards. Le immagini devono essere di 3 MB o meno e avere una larghezza di almeno 800 px. Inoltre, supportiamo i seguenti rapporti di aspetto larghezza:altezza.

• Sito web: 1:1 e 1,91:1
• Image App Download: 1:1 e 1,91:1
• Sondaggio: 1,91:1
• Conversazione con immagine: 1,91:1
• Messaggio diretto con immagine: 1,91:1

Supportiamo i seguenti formati immagine: .bmp, .jpeg e .png.

​

Video

Le seguenti specifiche video si applicano alle risorse utilizzate nelle Cards. Supportiamo i seguenti rapporti larghezza:altezza.

• Video Website: 16:9 e 1:1
• Video App Download: 16:9 e 1:1
• Sondaggio: 16:9
• Video Conversation: 16:9
• Video Direct Message: 16:9

​

Video promozionato

Questo documento offre una breve panoramica del processo per caricare e promuovere i video tramite la X Ads API.

La X Ads API supporta i video promozionati nei Tweet e nelle seguenti card:

• Video Website
• Video App Download
• Video Conversation

Per prima cosa, carica il video utilizzando l’endpoint POST media/upload (chunked). Utilizzando il media_id, associa il video a un account pubblicitario con l’endpoint POST accounts/:account_id/videos. L’id del video, talvolta indicato come media_key, verrà utilizzato nelle richieste successive. Si tratta di una stringa che inizia con un intero, è seguita da un carattere di sottolineatura e termina con un valore long. Ad esempio: 13_875943225764098048.

​

Video promossi nei Tweet

Per creare un Tweet, usa l’endpoint POST accounts/:account_id/tweet insieme all’id del video. In questo passaggio puoi anche fornire un titolo del video, una descrizione e una call to action (CTA). Questi valori sono visibili agli utenti.

​

Video promossi nelle Card

Le Video App Download e le Video Conversation Card supportano l’aggiunta di immagini poster. Carica un’immagine da utilizzare in queste Card tramite l’endpoint POST media/upload.

Crea la Card utilizzando uno dei seguenti endpoint:

• POST accounts/:account_id/cards/video_website
• POST accounts/:account_id/cards/video_app_download
• POST accounts/:account_id/cards/video_conversation

utilizzando l’id del video e, facoltativamente, il media_id dell’immagine (per l’immagine poster).

Infine, crea il Tweet utilizzando l’endpoint POST accounts/:account_id/tweet. Le Card vengono allegate ai Tweet tramite il parametro card_uri.

​

Informazioni generali

Per indicazioni dettagliate sul caricamento dei video tramite l’API, consulta la Video Upload Guide.

I video possono anche essere promossi come asset pre-roll. Consulta la Video Views Pre-roll Objective Guide per una spiegazione dettagliata.

• (Dal 2015-10-22) Quando carichi video da utilizzare in contenuti promossi, il parametro media_category deve essere impostato sul valore amplify_video per tutte le richieste del comando INIT all’endpoint POST media/upload (chunked). L’uso di questo nuovo parametro garantisce che il video venga pre-elaborato in modo asincrono e preparato per l’uso nei contenuti promossi. Il comando STATUS può essere utilizzato per verificare il completamento dell’elaborazione asincrona dopo il caricamento del video.
• La durata massima attualmente consentita per i video promossi è di 10 minuti con una dimensione del file pari o inferiore a 500 MB.
• I video caricati devono essere in formato mp4 o mov.
• I video caricati in genere vengono elaborati rapidamente, ma i tempi di elaborazione possono variare in base alla durata e alla dimensione del file.
• Le immagini poster caricate devono essere in formato png o jpg. Non sono previsti requisiti per rapporto d’aspetto o dimensioni, ma l’immagine poster verrà adattata al lettore video.

​

Guide

​

Tweet programmati

​

Introduzione

I Tweet programmati consentono a un inserzionista o a un utente di creare un Tweet da pubblicare in una data futura. Oltre a creare e gestire questi Tweet, l’API consente di associare tali Tweet a una line item, per promuoverli una volta che il Tweet è online. In questo modo gli inserzionisti possono preparare Tweet nativi e pianificare in anticipo le creatività di campagna in vista di iniziative chiave. Ad esempio, predisporre una creatività del Tweet da pubblicare immediatamente al momento dell’annuncio di un nuovo prodotto.

Il set completo di funzionalità fornite dagli endpoint dell’API dei Tweet programmati è elencato di seguito:

• Creare, modificare e visualizzare nuovi Tweet programmati
• Associare un Tweet programmato a una line item
• Eseguire query e gestire i Tweet programmati esistenti
• Una volta che un Tweet programmato è online, recuperare l’id del Tweet live

​

Endpoint API

L’intero set di endpoint relativi alla funzionalità descritta sopra è riportato di seguito:

​

Gestione dei Tweet programmati

• GET accounts/:account_id/scheduled_tweets (recupera l’elenco di tutti i Tweet programmati)
• GET accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (recupera un Tweet programmato specifico tramite il suo id)
• POST accounts/:account_id/scheduled_tweets (crea un nuovo Tweet programmato)
• PUT accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (modifica un Tweet programmato esistente)
• DELETE accounts/:account_id/scheduled_tweets/:scheduled_tweet_id (elimina un Tweet programmato tramite il suo id)
• GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id (mostra l’anteprima di un Tweet programmato esistente)

​

Tweet promossi programmati

• GET accounts/:account_id/scheduled_promoted_tweets (recupera l’elenco di tutti i Tweet promossi programmati)
• GET accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id (recupera un Tweet promosso programmato in base al suo id)
• POST accounts/:account_id/scheduled_promoted_tweets (crea un nuovo Tweet promosso programmato)
• DELETE accounts/:account_id/scheduled_promoted_tweets/:scheduled_promoted_tweet_id (elimina un Tweet promosso programmato esistente in base al suo id)

​

Visualizzazione dei Tweet programmati

• GET accounts/:account_id/scheduled_tweets/preview/:scheduled_tweet_id (visualizza un Tweet programmato esistente)

Poiché i Tweet programmati sono entità distinte rispetto ai Tweet “live”, su ogni creazione o modifica vengono eseguiti due diversi set di convalida. Il primo set di regole di convalida viene eseguito durante la fase di creazione del Tweet programmato, in particolare:

​

Creazione di Tweet programmati:

• Verificare che l’utente autenticato abbia i permessi per creare Tweet organici per un determinato @handle. I privilegi di creazione per i Tweet “Promoted-Only” richiedono che l’utente autenticato sia un utente dell’account con autorizzazioni del Tweet composer.
• Verificare che non ci siano più di 30 Tweet pianificati per la creazione entro una finestra di 15 minuti rispetto all’orario scheduled_at. Un messaggio di errore SCHEDULED_TWEET_LIMIT_EXCEEDED indica che sono stati pianificati troppi Tweet nello stesso intervallo futuro di 15 minuti. Gli inserzionisti dovranno rimuovere un Tweet pianificato esistente oppure anticipare o posticipare l’orario scheduled_at.

​

Il Tweet programmato viene pubblicato:

• Queste regole di convalida vengono eseguite all’ora indicata in scheduled_at e sono identiche a quelle applicate alla normale creazione di un Tweet nell’API. Ad esempio, un Tweet programmato non verrà pubblicato e scheduled_status verrà impostato su FAILED se il Tweet programmato contiene sia un’immagine sia una GIF

​

Flusso di lavoro

Crea un nuovo Tweet programmato

È possibile creare un nuovo Tweet programmato utilizzando l’endpoint POST accounts/:account_id/scheduled_tweets. Questo endpoint richiede i seguenti parametri obbligatori: scheduled_at (l’ora di pubblicazione) e il text del Tweet, se nel Tweet non sono incluse entità multimediali. Inoltre, offre alcune opzioni aggiuntive che consentono di creare un Tweet programmato per conto di un altro @handle tramite il parametro as_user_id, nonché la possibilità di aggiungere una card (card_uri) e contenuti multimediali (media_ids). Nota: un Tweet può contenere solo entità dello stesso tipo, cioè Video, GIF o Immagine. Il parametro nullcast determina se il Tweet è “Solo promozione” oppure no. Tutti i nuovi Tweet programmati sono “Solo promozione” (nullcast=true) per impostazione predefinita. Se nullcast=false, viene creato un Tweet programmato organico.

Una volta creato correttamente un Tweet programmato, la risposta conterrà un campo id, che si riferisce all’identificatore univoco del Tweet programmato stesso. Oltre a questo campo, viene restituito anche tweet_id. Questo campo inizialmente è null; quando il Tweet viene pubblicato, viene valorizzato con l’ID del Tweet “live”.

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_tweets" -d 'scheduled_at=2017-12-24T23:59:00Z&text=Buone Feste!'

Verrà creato il seguente Tweet programmato:

{
  "request": {
    "params": {
      "text": "Buone Feste!",
      "scheduled_at": "2017-12-24T23:59:00Z"
    }
  },
  "data": {
    "completed_at": null,
    "id_str": "917507899668099072",
    "text": "Buone Feste!",
    "user_id": "3271358660",
    "scheduled_status": "SCHEDULED",
    "id": 917507899668099100,
    "nullcast": true,
    "created_at": "2017-10-09T21:51:44Z",
    "scheduled_at": "2017-12-24T23:59:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T21:51:44Z",
    "tweet_id": null,
    "media_keys": []
  }
}

Una volta che questo Tweet programmato sarà pubblicato, il campo tweet_id verrà compilato con l’ID del Tweet “live”.

Visualizzare un Tweet programmato

L’endpoint GET accounts/:account_id/tweet_previews può quindi essere utilizzato con l’id del Tweet programmato dal passaggio precedente per generare un’anteprima del Tweet. La risposta dell’API conterrà un URL di iframe pronto all’uso per il rendering di un’anteprima del Tweet programmato. I CSS e le immagini pertinenti saranno erogati direttamente da X.

twurl -H ads-api.x.com -X GET "/6/accounts/18ce54bgxky/tweet_previews?tweet_type=SCHEDULED&tweet_ids=917507899668099072

{
  "request": {
    "params": {
      "tweet_type": "SCHEDULED",
      "tweet_ids": [
        "917507899668099072"
      ],
      "account_id": "18ce54bgxky"
    }
  },
  "data": [
    {
      "tweet_id": "1126633863155871744",
      "preview": "<iframe class='tweet-preview' src='https://ton.smf1.x.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAK1WTW%2FjNhD9Kyyv9dqSZdmOgALJbhJsCyxaIDkUWBUEJY0lNhSpklRSN%2FV%2F71CyZbm297S%2BWJxPzpt5I71T9wbgaELeaW6AOygYxyN9rlryhW9JcEPmUbKIkuiG%2FBjgj8yD8IZOqChoEobz5TKK1ssojOP1KlwtFl7BrDMY4oIW%2FTatlMzB3z7JZ940W%2FJZS1Hwrf0Btc60Kve3oMmGSwsTWgjbSL7tXJjhqgSafA0mYfzHhIJywgmwNHmnFbeV4yU%2Bf0WN3daZlvtDa8Gw2htrdRCZXrlDU92aHIPStA2CKOekMrD5KaWVc02SztIZps%2Bh0rIAg27TXNcpJQYk2ii90VLqt7R3ht%2B4cQoMeVClUIAPd03Th01nvDfx0ClmoJFYk0aouGst82gqROaKskf03KCr7LLvXnXN02K3QTHFaziovYdH0seL5qswitfLZTBq6FGIRfSe9Lm1FTfkY%2BX%2FFcpPAlNRC7eufdFSY1%2BxASh84oo8YitzYXM9IZ%2FuaNcQ1HjMbQc61l0VXDmYlsJVbTYVGq0KwPCi2cf5tQFFnjR2zyDU6YycwX%2Fr3oRzvfKpwTaSZ8NfQUoU%2FUsetanxAV79VElhHbm1oIrSiILcvvgquqSN0Q7y8Uz2TQdjWa5bhZP8IUShEeh8IvIxkVB7SY%2FyKctaIL%2B0kgQrMp8n0SKJ10eWxZ4t%2FBXHUzg4idu6nOnNxsIQ1Yka2D9aDc0sQTNQPJP%2B2sgqvPUrGLERozL68ToNLRELvBj4VuZaOSOy1mmsdAi2dxaWOeyhlRzVl6TYozMnhHIjJLCM5y%2BlwaweHOn96afg%2FuHhnl60ETUvgR1HpJsQntkptrcuO0bOOhuLg1NBPfyH6Swrpw2W9O24rBu8kwH8DuEdns9Kv1hLc5rsxBaTLcN1HIdhHIVRuFov5wtMXH748vO2%2BP0jUzjFXE7%2FbMa3%2BFZl3z1ZxhWyjv2fwlfy9NaY6LhO0lm4WC3WcRSvlqO4UqiXYT7C%2B7vwcT7SWlFAxg3LtMHNfH2ODnZ4kIPVPRo9jnN1r5eDNup%2BIy2y5GxuDrQqYMNb6dje9or44HOyQYTnWs%2FXXoD7%2Ba8WrGO4hwZuK%2B2Qt%2F32tAPhB%2B4xt238qjVQtpIbuuvIP6wbjfAIhStncO3eZ0f9keMHmYHuo%2BCwFoJ%2BDfktdEF0JPfebbxgct30b%2BdhY%2B51u%2FGm2U2IR7rW%2FbJU%2FdcBfpEchHjwoO52%2FwENmVvErwgAAA%3D%3D'>"
    }
  ]
}

Una vista di esempio del Tweet programmato appena creato è mostrata sopra

Associare un Tweet programmato a una voce di riga

Sebbene i Tweet programmati possano essere utilizzati per creare Tweet organici, consentiamo anche ai partner di creare un Tweet “solo promozionato” (nullcast=true), ciascuno dei quali può essere associato a una voce di riga. Per agevolare questo, mettiamo a disposizione anche l’endpoint POST accounts/:account_id/scheduled_promoted_tweets. Questo endpoint consente di associare un solo Tweet programmato promozionato a una voce di riga in una singola chiamata API. Per associare più Tweet programmati alla stessa voce di riga, sono necessarie più chiamate API.

Si noti che non è possibile modificare un Tweet programmato promozionato esistente.

twurl -H 'ads-api.x.com' -X POST "/6/accounts/:account_id/scheduled_promoted_tweets" -d 'line_item_id=a44qc&scheduled_tweet_id=917507899668099072'

{
  "data": {
    "line_item_id": "a44qc",
    "id": "26576",
    "created_at": "2017-10-09T22:24:16Z",
    "updated_at": "2017-10-09T22:24:16Z",
    "scheduled_tweet_id": "917507899668099072",
    "tweet_id": null,
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "a44qc",
      "scheduled_tweet_id": 917507899668099100,
      "account_id": "aaaaa"
    }
  }
}

Questo endpoint crea esclusivamente un’associazione tra uno specifico Scheduled Tweet e una line item. Una volta che le date di flight della campagna/line item sono attuali, la line item avvierà automaticamente l’erogazione del corrispondente Tweet “live”. In questa fase verifichiamo che lo Scheduled Tweet sia nello stato SCHEDULED e che sia valido per l’obiettivo specificato, ma non vengono eseguite altre validazioni. Eventuali ulteriori regole di validazione applicabili alla line item e allo Scheduled Tweet vengono eseguite quando il Tweet diventa “live”.

Per evitare problemi con l’erogazione della campagna, si consiglia di impostare lo Scheduled Tweet con scheduled_at a un orario precedente alle date di flight della campagna/line item.

Ad esempio, se lo Scheduled Tweet è impostato per andare live dopo la data di inizio della campagna (e vi è un singolo Tweet associato a una singola line item), la campagna sarà ACTIVE; tuttavia, poiché lo Scheduled Tweet non è ancora live, non saranno disponibili creatività da erogare.

Gestione degli Scheduled Tweet

I seguenti endpoint consentono ai consumatori dell’API di gestire tutti i propri Scheduled Tweet e Scheduled Promoted Tweet. Queste API possono essere utilizzate per restituire un elenco di tutti gli Scheduled Tweet, eventualmente filtrato per stato, nonché per eseguire il lookup di uno specifico Scheduled Tweet tramite il suo id.

​

Cosa succede quando un Tweet pianificato viene pubblicato?

Quando un determinato Tweet pianificato sta per essere pubblicato, ovvero all’orario scheduled_at, vengono apportati i seguenti aggiornamenti:

• Il Tweet “live” viene creato; tuttavia, potrebbe esserci una latenza fino a 1 secondo
• Il tweet_id viene aggiunto alle seguenti entità:
• Tweet pianificato
• Tweet pianificato promosso
• Viene creata una nuova entità Tweet promosso

​

Best Practices

Le seguenti best practice sono consigliate quando si creano o si promuovono Tweet programmati:

• Assicurarsi che il Tweet sia valido al momento della creazione del Tweet programmato (ad esempio, un Tweet può includere solo un’Immagine, un Video o una GIF e non una combinazione dei tre)
• Assicurarsi che le date del flight della campagna (ovvero start_time ed end_time) siano allineate con il tempo scheduled_at del Tweet programmato
• Evitare di programmare Tweet con una data oltre un anno nel futuro (365 giorni)
• L’anteprima dei Tweet non è attualmente supportata per i Tweet programmati (ossia la possibilità di visualizzare l’anteprima dei Tweet programmati prima della creazione)

​

Libreria dei media

​

Introduzione

Gli endpoint della Media Library consentono di gestire immagini, GIF e video per gli account X Ads. Le risorse multimediali presenti nella libreria possono essere utilizzate nei Tweet e per creare card. Possono inoltre essere riutilizzate in più creatives, eliminando la necessità di caricare la stessa risorsa più volte.

​

Endpoint API

• POST media/upload o POST media/upload (chunked) (caricare contenuti multimediali)
• POST accounts/:account_id/media_library (aggiungere contenuti multimediali alla Libreria multimediale)

​

Aggiunta alla libreria

L’aggiunta di contenuti multimediali alla libreria è un processo in due passaggi. Per prima cosa, carica l’asset utilizzando l’endpoint POST media/upload oppure il set di endpoint POST media/upload (chunked). Consulta la guida Chunked media upload per i dettagli sul nostro processo di upload multi‑parte.

twurl -X POST -H upload.x.com "/1.1/media/upload.json?additional_owners=756201191646691328" --file latte.jpeg --file-field "media"

{
   "media_id":966947208837742592,
   "media_id_string":"966947208837742592",
   "size":74194,
   "expires_after_secs":86400,
   "image":{
      "image_type":"image/jpeg",
      "w":800,
      "h":418
   }
}

Successivamente, usando l’id del media, aggiungi il media alla libreria dell’account pubblicitario tramite l’endpoint POST accounts/:account_id/media_library.

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library?file_name=latte.jpeg&media_category=TWEET_IMAGE&media_key=966947208837742592&name=Latte"

{
   "request":{
      "params":{
         "name":"Latte",
         "file_name":"latte.jpeg",
         "media_category":"TWEET_IMAGE",
         "account_id":"18ce54d4x5t",
         "media_key":966947208837742592
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

Nota: Pubblicare immagini, GIF o video subito dopo il caricamento aggiunge anche i contenuti multimediali alla libreria.

​

Parametri della richiesta

Tutte le richieste POST alla Media Library richiedono un identificatore del contenuto multimediale. Questo valore viene restituito durante la fase di caricamento. Quando si utilizza il media_id, come nell’esempio sopra, è necessario specificare anche una media_category. I possibili valori di categoria sono quattro: AMPLIFY_VIDEO, TWEET_GIF, TWEET_IMAGE e TWEET_VIDEO.

In modo facoltativo, è possibile impostare i valori name e file_name per gli oggetti nella Media Library. Questi attributi aiutano gli utenti a distinguere tra varianti dei contenuti multimediali nella libreria.

Per i video, è inoltre possibile impostare un titolo e una descrizione. Tali valori devono essere passati come parametri della richiesta video_title e video_description con l’endpoint POST accounts/:account_id/tweet. Nel Tweet, questo testo appare sotto il video.

​

Attributi

La Media Library introduce formalmente il concetto di media_key. Si tratta dell’identificatore univoco per gli oggetti nella libreria. Le media_key sono stringhe nel seguente formato: 13_875943225764098048. Sono pienamente supportate in tutti i nostri endpoint delle card.

Inoltre, la risposta della Media Library include il media_id, rappresentato come stringa. È incluso per le risorse che al momento non accettano una media_key: Tweets, Anteprima Tweet e Tweet programmati. Stiamo lavorando per supportare le media_key ovunque.

L’attributo aspect_ratio viene restituito per GIF e video. Può essere utilizzato per filtrare i media da usare nelle card che accettano solo determinati rapporti d’aspetto.

*Questi endpoint supportano il parametro video_id, che è una media_key.

​

Utilizzo

In questa sezione, la seguente immagine verrà usata in un Tweet e per creare una website card.

twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/media_library/3_966947208837742592"

{
   "request":{
      "params":{
         "account_id":"18ce54d4x5t",
         "media_key":"3_966947208837742592"
      }
   },
   "data":{
      "tweeted":false,
      "name":"Latte",
      "file_name":"latte.jpeg",
      "media_url":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
      "media_category":"TWEET_IMAGE",
      "media_key":"3_966947208837742592",
      "created_at":"2018-02-23T08:05:54Z",
      "media_status":"TRANSCODE_COMPLETED",
      "media_key":"966947208837742592",
      "media_type":"IMAGE",
      "updated_at":"2018-02-23T08:06:17Z",
      "deleted":false
   }
}

Tweet

Possiamo creare il Tweet facendo riferimento alle immagini tramite media_keys.

twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet?text=coffee&media_keys=966947208837742592&as_user_id=756201191646691328&trim_user=true"

{
   "data":{
      "created_at":"Fri Feb 23 08:20:05 +0000 2018",
      "id":966950781302665218,
      "id_str":"966950781302665218",
      "text":"caffè https://t.co/T772Hx5GNT",
      "truncated":false,
      "entities":{
         "hashtags":[

         ],
         "symbols":[

         ],
         "user_mentions":[

         ],
         "urls":[

         ],
         "media":[
            {
               "id":966947208837742592,
               "id_str":"966947208837742592",
               "indices":[
                  7,
                  30
               ],
               "media_url":"http://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "media_url_https":"https://pbs.twimg.com/media/DWtJXQNUQAAdPZj.jpg",
               "url":"https://t.co/T772Hx5GNT",
               "display_url":"pic.x.com/T772Hx5GNT",
               "expanded_url":"https://x.com/apimctestface/status/966950781302665218/photo/1",
               "type":"photo",
               "sizes":{
                  "thumb":{
                     "w":150,
                     "h":150,
                     "resize":"crop"
                  },
                  "large":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "medium":{
                     "w":800,
                     "h":418,
                     "resize":"fit"
                  },
                  "small":{
                     "w":680,
                     "h":355,
                     "resize":"fit"
                  }
               }
            }
         ]
      },
      "source":"App di Test Interno X Ads API",
      "in_reply_to_status_id":null,
      "in_reply_to_status_id_str":null,
      "in_reply_to_user_id":null,
      "in_reply_to_user_id_str":null,
      "in_reply_to_screen_name":null,
      "user":{
         "id":756201191646691328,
         "id_str":"756201191646691328"
      },
      "geo":null,
      "coordinates":null,
      "place":null,
      "contributors":[
         2417045708
      ],
      "retweet_count":0,
      "favorite_count":0,
      "favorited":false,
      "retweeted":false,
      "possibly_sensitive":false,
      "scopes":{
         "followers":false
      },
      "lang":"en"
   },
   "request":{
      "params":{
         "as_user_id":756201191646691328,
         "text":"caffè",
         "account_id":"18ce54d4x5t",
         "media_keys":[
            966947208837742592
         ],
         "trim_user":true
      }
   }
}

Scheda sito web

Tutti i nostri endpoint per le schede supportano le media key. Creeremo la scheda sito web facendo riferimento alla media_key dell’immagine.

twurl -X POST -H ads-api.x.com "/11/accounts/18ce54d4x5t/cards"

{
  "name": "components create cards",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

Associamo quindi questa card a un Tweet utilizzando il relativo card_uri.

​

Identificazione delle schede

​

Introduzione

Le Card sono formati pubblicitari personalizzabili che utilizzano contenuti multimediali e possono essere associate a un sito web, a un’App o a inviti all’azione per favorire specifiche interazioni degli utenti, come l’avvio di un Messaggio Diretto. Possono essere aggiunte a Tweet, Tweet programmati o Tweet in bozza.

Le Card possono essere richiamate negli oggetti Tweet in due modi: tramite la card_uri della card o tramite la sua preview_url. Di seguito sono riportati esempi di valori per ciascuna.

card_uri	preview_url
card://1043282691834048513	https://cards.x.com/cards/18ce54d4x5t/68w3s

Nota: A partire dalla versione 3 della X Ads API, nella risposta delle card per le card appena create viene generata e restituita solo la card_uri.

Nota: A partire dalla versione 5 della X Ads API, la preview_url nella risposta delle card non viene più restituita.

Il tipo di riferimento nella risposta dell’oggetto Tweet dipende dal modo in cui il Tweet è stato creato. In altre parole, se il Tweet è stato creato utilizzando il parametro di richiesta card_uri, nella risposta verrà visualizzato il valore dell’URI della card. Se invece la preview_url è stata inclusa come parte del testo del Tweet, nella risposta verrà visualizzato l’URL di anteprima.

​

Identificazione dei Tweet con card_uri

Per i Tweet creati utilizzando il valore URI della card, individua il riferimento alla card nell’attributo di risposta card_uri. L’esempio di risposta seguente utilizza l’endpoint GET accounts/:account_id/tweets.

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweets?trim_user=true&tweet_type=PUBLISHED&tweet_ids=1043551275923591168"
{
  "request": {
    "params": {
      "tweet_ids": [
        "1043551275923591168"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "source": "App di Test Interno X Ads API",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        15
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1043551275923591168",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 1043551275923591168,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Sat Sep 22 17:23:07 +0000 2018",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "card_uri": "card://1043282691834048513",
      "full_text": "Tracciamento di una card",
      "lang": "en",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1043551275923591168"
    }
  ]
}

Se si utilizza la Standard API, usare include_card_uri=true nella richiesta.

Indipendentemente dall’endpoint utilizzato, l’attributo di risposta card_uri verrà restituito solo se il Tweet è stato creato utilizzando un URI della card.

Per gli oggetti Tweet programmati e in bozza, la risposta includerà sempre l’attributo di risposta card_uri.

​

Identificare i Tweet con preview_url

Per i Tweet creati includendo l’URL di anteprima nel testo del Tweet, l’URL si trova in entities[“urls”][i][“expanded_url”] (il campo text contiene un URL t.co abbreviato), dove i è un indice dell’array (un Tweet può contenere più URL).

Per gli oggetti Tweet programmati e in bozza, l’URL di anteprima sarà sempre presente nel campo text.

​

Recupero delle card

Per ottenere informazioni aggiuntive su una specifica card, mettiamo a disposizione due endpoint: GET accounts/:account_id/cards/all e GET accounts/:account_id/cards/all/:card_id. Il primo consente di recuperare una card tramite card_uri e il secondo tramite l’id della card. L’id della card si trova alla fine di preview_url. Nell’esempio sopra, l’id è 68w3s.

​

Identificazione dei media

​

Introduzione

I contenuti multimediali—immagini, GIF e video—possono essere aggiunti ai Tweet e alle card. Inoltre, i video possono essere utilizzati come asset pre-roll e le immagini possono essere promosse sulla X Audience Platform. Questa sezione descrive come individuare i riferimenti ai contenuti multimediali all’interno di queste entità.

Esistono due tipi di identificatori dei contenuti multimediali: ID e chiavi. Di seguito sono riportati valori di esempio per ciascuno.

ID del contenuto multimediale	Chiave del contenuto multimediale
1029825579531807971	13_1029825579531807971

La chiave del contenuto multimediale corrisponde all’ID con l’aggiunta di un prefisso numerico e di un carattere di underscore.

​

Immagini

La tabella seguente mostra i tipi di identificatori attualmente disponibili nella risposta di ciascuna risorsa relativa alle immagini, nonché i corrispondenti nomi degli attributi.

Resource	Identifier	Attribute(s)
Image cards	None
Tweet	Both	entities["media"]["id_str"] entities["media"]["media_key"]
Scheduled Tweet	Both	media_ids and media_keys
Draft Tweet	Both	media_ids and media_keys
Account Media	None
Media Library	Both	media_id and media_key

Le Image cards e le immagini di Account Media non includono alcun riferimento a identificatori multimediali. I Tweet includono solo gli ID multimediali. I Tweet programmati e i Tweet in bozza includono sia l’ID multimediale sia la chiave multimediale. Anche la Media Library restituisce entrambi.

Per i Tweet, i campi id e id_str nell’oggetto all’interno dell’array entities[“media”] corrispondono all’ID multimediale. Nei casi in cui un Tweet includa più immagini, i riferimenti a ciascuna entità multimediale si trovano solo in extended_entities[“media”].

Oltre ai riferimenti agli identificatori, è spesso importante avere accesso all’URL dell’immagine.

Resource	Attribute(s)	Format
Image cards	image	.jpg
Tweet*	entities["media"][0]["media_url"] or extended_entities["media"][i]["media_url"]	.jpg
Scheduled Tweet	None
Draft Tweet	None
Account Media	media_url	.jpg
Media Library	media_url	.jpg

• La posizione dell’URL dipende dal fatto che il Tweet contenga una singola immagine o più immagini.

Tutte le Image cards includono un attributo di risposta image che contiene l’URL dell’immagine su X. (Per le image app download cards, il nome è wide_app_image.)

Per i Tweet, la posizione dell’URL multimediale dipende sia dal tipo di media sia dall’endpoint utilizzato. Per i Tweet con una singola immagine, l’URL si trova in entities[“media”][0][“media_url”]. Questo vale sia per la X Ads API sia per la Standard API. Quando i Tweet contengono più immagini, tuttavia, gli URL si trovano solo in extended_entities[“media”][i][“media_url”]. Questo è disponibile solo nella Standard API.

​

Video

La seguente tabella mostra i tipi di identificatore attualmente disponibili nella risposta di ciascuna risorsa relativa ai video, nonché i relativi nomi di attributo.

Risorsa	Identificatore	Attributo/i
Schede video	Può essere entrambi	video_content_id
Schede sondaggio video	Nessuno
Tweet	Entrambi	entities["media"]["id_str"] entities["media"]["media_key"]
Tweet pianificato	Entrambi	media_ids and media_keys
Bozza di Tweet	Entrambi	media_ids and media_keys
Media dell’account	Media key	video_id
Libreria multimediale	Entrambi	media_id and media_key

Sebbene le schede video (ad eccezione delle schede sondaggio con video) includano un attributo di risposta video_content_id, si riscontra un’incoerenza nel tipo di valore restituito. In alcuni casi è un ID multimediale; in altri una media key.

Di seguito sono riportate informazioni su come accedere all’URL del video.

Risorsa	Attributo/i	Formato
Schede video	video_url and video_hls_url	.vmap .m3u8
Tweet con video	extended_entities["media"][i]["video_info"]["variants"][j]["url"]	.mp4
Tweet pianificato	Nessuno
Bozza di Tweet	Nessuno
Media dell’account	Nessuno
Libreria multimediale	media_url	.mp4

Le schede video includono gli attributi di risposta video_url e video_hls_url, con URL .vmap e .m3u8 rispettivamente.

​

Libreria multimediale

A volte è necessario recuperare informazioni aggiuntive su una risorsa multimediale. Un caso d’uso, per le schede video, è ottenere l’URL MP4 invece di quello VMAP. Queste informazioni sono disponibili nella Libreria multimediale. Per dettagli sulle informazioni disponibili, consulta la nostra Guida alla Libreria multimediale. La maggior parte delle risorse appartenenti all’utente FULL promuovibile dell’account pubblicitario è presente nella libreria. Esistono tuttavia alcune eccezioni.

Recupero dei media

Come indicato sopra, le schede immagine non contengono riferimenti né a media ID né a media key. Di conseguenza, non è possibile recuperarne le risorse tramite la Libreria multimediale. Questo vale anche per le immagini di Account Media.

Le schede video richiedono che la risorsa video faccia parte della Libreria multimediale (o della risorsa Videos precedente) prima della creazione. Di conseguenza, queste risorse saranno sempre recuperabili nella Libreria multimediale. Questo vale anche per le risorse PREROLL di Account Media.

Infine, i media nei Tweet sono sempre garantiti nella Libreria multimediale.

La tabella seguente riepiloga quali risorse sono recuperabili nella Libreria multimediale, tenendo conto del fatto che la risposta della risorsa includa o meno un identificatore da utilizzare per la ricerca.

Risorsa	Nella Libreria multimediale
Schede immagine	No
Schede video	Sì*
Tweet (qualsiasi media)**	Sì
Tweet programmati	Sì
Bozze di Tweet	Sì
Immagini di Account Media	No
Video di Account Media (PREROLL)	Sì

• Per le schede in cui video_content_id è una media key. Quando il valore è un media ID, la risorsa esiste comunque nella Libreria multimediale, ma per recuperarla è necessario aggiungere un prefisso numerico e un carattere di sottolineatura. ** I Tweet restituiscono solo media ID. Sebbene la risorsa sia garantita nella Libreria multimediale, per recuperarla è necessario aggiungere un prefisso numerico e un carattere di sottolineatura.

Interazioni con Account Media

Ci sono due casi in cui le risorse multimediali aggiunte alla libreria vengono automaticamente aggiunte alla risorsa Account Media.

• Quando una risorsa AMPLIFY_VIDEO viene aggiunta alla Libreria multimediale, viene automaticamente aggiunta come risorsa di Account Media con tipo creativo PREROLL.
• Quando immagini con dimensioni specifiche (vedi “Creative Types” nella nostra pagina delle enumerazioni) vengono aggiunte alla Libreria multimediale, vengono automaticamente aggiunte come risorse di Account Media. Il tipo creativo (ad es. INTERSTITIAL) dipende dalle dimensioni dell’immagine.

​

Tweet

​

Introduzione

L’X Ads API supporta tre tipi di Tweet: pubblicati, programmati e bozze.

​

Tweet nullcast

I Tweet possono essere nullcast (anche detti “Solo promossi”) oppure organici. I Tweet nullcast, una volta pubblicati, non compaiono nella timeline pubblica dell’utente, pur essendo pubblici. I Tweet organici, invece, vengono mostrati ai follower dell’utente e compaiono nella sua timeline pubblica.

Creazione di Tweet

Ognuno dei tre endpoint di creazione dei Tweet supporta un parametro booleano nullcast che consente all’utente dell’API di creare Tweet nullcast oppure organici. I Tweet nullcast possono essere creati dall’utente o da chiunque disponga dell’autorizzazione a creare Tweet per conto dell’utente. I Tweet organici possono essere creati solo dal full promotable user.

Aggiornamento dei Tweet

È possibile aggiornare la proprietà nullcast per i Tweet programmati e le bozze. Per i Tweet programmati, si possono apportare modifiche fino al momento scheduled_at del Tweet. Le bozze di Tweet possono essere modificate a tempo indeterminato. Una volta pubblicati, tuttavia, non è possibile cambiare un Tweet da nullcast a organico o viceversa.

​

Promuovere i Tweet

Solo i Tweet pubblicati e quelli programmati possono essere promossi. Possono essere nullcast o organici; non ci sono restrizioni. Un inserzionista può promuovere i propri Tweet o quelli di un altro utente, purché abbia ottenuto l’autorizzazione a farlo. (Vedi: Promoting another user’s Tweets per ulteriori informazioni.)

È possibile promuovere più Tweet all’interno di una singola campagna. Allo stesso modo, un singolo Tweet può essere promosso in una o più campagne.

Per promuovere i Tweet pubblicati, usa l’endpoint POST accounts/:account_id/promoted_tweets. Questo associa i Tweet pubblicati a un elemento di riga (line item). Per promuovere i Tweet programmati, usa l’endpoint POST accounts/:account_id/scheduled_promoted_tweets.

​

ID dei Tweet

Gli ID dei Tweet pubblicati, programmati e in bozza sono numerici: si tratta di interi non segnati a 64 bit. Ad esempio, l’ID del seguente Tweet pubblicato è 1166476031668015104.

Quando i Tweet pubblicati o programmati vengono promossi, viene creata una corrispondente entità di Tweet promossa. Queste entità hanno propri ID, alfanumerici, rappresentati come valori codificati in base 36. Ad esempio, promuovere il Tweet pubblicato sopra—cioè associarlo alla voce di riga 6c62d—restituisce la seguente risposta dell’API.

$ twurl -X POST -H ads-api.x.com "/9/accounts/18ce54d4x5t/promoted_tweets?line_item_id=6c62d&tweet_ids=1166476031668015104"
{
  "request": {
    "params": {
      "tweet_ids": [
        1166476031668015104
      ],
      "line_item_id": "6c62d",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "line_item_id": "6c62d",
      "id": "3qwlq6",
      "entity_status": "ACTIVE",
      "created_at": "2019-09-12T21:39:10Z",
      "updated_at": "2019-09-12T21:39:10Z",
      "approval_status": "ACCEPTED",
      "tweet_id": "1166476031668015104",
      "deleted": false
    }
  ],
  "total_count": 1
}

Oltre al Tweet ID e al line item ID, che sono stati passati nella richiesta di creazione, la risposta include un campo id con il valore 3qw1q6, che è il promoted Tweet ID.

​

Carousel

​

Introduzione

La X Ads API supporta la creazione e il recupero di caroselli video e di immagini. Il carosello è un tipo di card che può contenere da 2 a 6 asset multimediali. La card carosello può indirizzare l’utente a un sito web o invitarlo a installare un’app mobile. Per ulteriori informazioni sui caroselli, sui loro vantaggi, sulle best practice e sulle FAQ, consulta la pagina Carousel Ads on X.

Un carosello, come qualsiasi altro tipo di card, può essere utilizzato nei Tweet e tali Tweet possono poi essere promossi. Il flusso di lavoro è lo stesso a cui sei già abituato:

1. Carica i contenuti multimediali
2. Crea la card
3. Crea il Tweet
4. Promuovi il Tweet

L’unica differenza riguarda la modalità di creazione della card. Mentre altre richieste di creazione di card accettano parametri query, le richieste di creazione di card carosello accettano solo corpi POST in formato JSON.

​

Endpoint

La X Ads API consente di creare e recuperare caroselli.

Per creare un carosello, di qualsiasi tipo, usa l’endpoint POST accounts/:account_id/cards. Per recuperare i caroselli, usa l’endpoint GET accounts/:account_id/cards.

​

Corpo POST JSON

I caroselli vengono creati utilizzando due componenti. Il primo specifica le risorse multimediali che verranno utilizzate. Il secondo specifica le informazioni sul sito web o sull’App.

Nello specifico, una scheda carosello viene creata utilizzando i seguenti componenti, nell’ordine:

• Un componente SWIPEABLE_MEDIA, che accetta un array di media key
• Uno dei seguenti:
• Un componente DETAILS per specificare le informazioni del sito web
• Un componente BUTTON per specificare le informazioni dell’App

Il componente SWIPEABLE_MEDIA deve includere un array media_keys in cui è possibile specificare da 2 a 6 immagini o video. L’ordine in cui vengono passate le media key determina l’ordine in cui verranno renderizzati.

{
  "type": "SWIPEABLE_MEDIA",
  "media_keys": [
    "13_1089771253848666112",
    "13_1191948012077092867"
  ]
}

Come promemoria, puoi ottenere le chiavi multimediali effettuando una richiesta all’endpoint GET accounts/:account_id/media_library.

La composizione del secondo oggetto componente dipende dal fatto che tu voglia indirizzare l’utente a un sito web o invitarlo a installare un’app. La tabella seguente riassume le due opzioni. (Nota: tutte le chiavi elencate sono obbligatorie.)

	Sito web	App
Specificare il tipo di componente	"type": "DETAILS"	"type": "BUTTON"
Titolo/Etichetta	"title": "X"	"label": { "type": "ENUM", "value": "INSTALL" }
Destinazione	"destination": { "type": "WEBSITE", "url": "https://www.x.com" }	"destination": { "type": "APP", ... }

Mettendo tutto insieme, di seguito è riportato un esempio di corpo JSON POST per un carosello per sito web.

{
  "name": "carousel del sito web",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "DETAILS",
      "title": "X"
      "destination": {
        "type": "WEBSITE",
        "url": "https://www.x.com"
      }
    }
  ]
}

Gli oggetti di destinazione App all’interno dei componenti BUTTON richiedono un codice paese e almeno un identificatore dell’app. Possono facoltativamente includere deep link. Per una descrizione di questi fields, consulta la documentazione di riferimento.

Mettendo tutto insieme, di seguito è riportato un esempio di body POST JSON per un carosello di app.

{
  "name": "carosello di app",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "13_1089771253848666112",
        "13_1191948012077092867"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALLA",
      },
      "destination": {
        "type": "APP",
        "country_code": "US"
        "googleplay_app_id": "com.twitter.android",
        "iphone_app_id": "333903271"
      }
    }
  ]
}

​

Esempio

Questa sezione illustra come creare una card carousel video per siti web e come utilizzarla in un Tweet. Come indicato sopra, il flusso di lavoro è quello consueto: caricare i contenuti multimediali, creare la card, creare il Tweet. L’unica differenza riguarda la modalità di creazione della card.

Media

Per iniziare, carica nuovi asset multimediali oppure utilizza quelli esistenti. Per informazioni dettagliate su come caricare nuovi asset multimediali e aggiungerli alla Libreria multimediale, consulta la nostra Guida alla Libreria multimediale.

Una volta che i tuoi asset multimediali sono nella Libreria multimediale, recuperali utilizzando l’endpoint GET accounts/:account_id/media_library. Usa il parametro di richiesta media_type per limitare i risultati a uno specifico tipo di contenuto multimediale.

$ twurl -H ads-api.x.com "/10/accounts/18ce54d4x5t/media_library?media_type=VIDEO"

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_type": "VIDEO"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "tweeted": true,
      "duration": 5283,
      "name": "Alba",
      "file_name": "sunrise.mp4",
      "description": null,
      "media_url": "https://video.twimg.com/amplify_video/1089771253848666112/vid/1280x720/tyL-pUBP7GgkS9bl.mp4?tag=9",
      "poster_media_key": "3_1089771253848666112",
      "media_key": "13_1089771253848666112",
      "created_at": "2019-01-28T06:24:48Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1089771253848666112/img/WOYvToSRZFXUSDzd.jpg",
      "title": null,
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2019-08-23T19:05:33Z",
      "deleted": false
    },
    {
      "tweeted": true,
      "duration": 15248,
      "name": "Neve",
      "file_name": "snow.mp4",
      "description": "Due, tre, e poi quattro",
      "media_url": "https://video.twimg.com/amplify_video/1191948012077092867/vid/1280x720/2cOvadcctqqea6Hx.mp4?tag=13",
      "poster_media_key": "3_1191948012077092867",
      "media_key": "13_1191948012077092867",
      "created_at": "2019-11-06T05:18:46Z",
      "media_status": "TRANSCODE_COMPLETED",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/1191948012077092867/img/IUbhTRd62SEeIVTf.jpg",
      "title": "Uno"
      "media_type": "VIDEO",
      "aspect_ratio": "16:9",
      "updated_at": "2020-03-27T22:23:18Z",
      "deleted": false
    }
  ]
}

Creazione del carosello

Usa l’endpoint POST accounts/:account_id/cards per creare il carosello. Usa le media key della richiesta precedente. Ricorda che l’ordine in cui fornisci le media key determina l’ordine in cui verranno visualizzate.

$ twurl -A "Content-Type: application/json" -X POST -H ads-api.x.com "/10/accounts/18ce54d4x5t/cards" -d '{"name":"carousel del sito web","components":[{"type": "SWIPEABLE_MEDIA","media_keys":["13_1089771253848666112","13_1191948012077092867"]},{"type": "DETAILS","title": "X","destination":{"type":"WEBSITE", "url":"https://www.x.com"}}]}'

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "carosello del sito web",
    "components": [
      {
        "type": "SWIPEABLE_MEDIA",
        "media_keys": [
          "13_1089771253848666112",
          "13_1191948012077092867"
        ]
      },
      {
        "type": "DETAILS",
        "title": "X",
        "destination": {
          "type": "WEBSITE",
          "url": "https://www.x.com/",
          "tco_url": "https://t.co/dyTMHWKWZb"
        }
      }
    ],
    "id": "ars7m",
    "created_at": "2020-11-11T07:51:47Z",
    "card_uri": "card://1326432421105995776",
    "updated_at": "2020-11-11T07:51:47Z",
    "deleted": false,
    "card_type": "UNIFIED"
  }
}

Nota che, come per altre card, la risposta della carousel card include un card_uri, che verrà utilizzato per creare un Tweet.

Tweet

Usa l’endpoint POST accounts/:account_id/tweet per creare il tuo Tweet. Usa il card_uri dalla richiesta precedente. (Risposta troncata per leggibilità.)

$ twurl -H ads-api.x.com "/9/accounts/18ce54d4x5t/tweet_previews?tweet_type=PUBLISHED&tweet_ids=1326434098324385792"

{
  "data": {
    "created_at": "Wed Nov 11 07:58:27 +0000 2020",
    "id": 1326434098324385792,
    "id_str": "1326434098324385792",
    "text": "Swipe",
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "X Ads API Internal Test App",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691300,
      "id_str": "756201191646691328",
      ...
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": [
      2417045708
    ],
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "possibly_sensitive": false,
    "scopes": {
      "followers": false
    },
    "lang": "en",
  },
  "request": {
    "params": {
      "text": "Swipe"
      "as_user_id": 756201191646691300,
      "card_uri": "card://1326432421105995776",
      "account_id": "18ce54d4x5t"
    }
  }
}

Anteprime dei Tweet

Utilizza l’endpoint GET accounts/:account_id/tweet_previews per visualizzare il tuo Tweet.

​

tagging dei metadata creativi

​

Introduzione

Questa guida è rivolta a partner creativi, agenzie e sviluppatori creativi per applicare tag agli asset utilizzati nelle campagne su X, così da comprendere meglio il valore e le prestazioni dei singoli asset.

Nota: Gli asset multimediali devono essere taggati esclusivamente dal partner o dallo sviluppatore che li ha creati. Se chi utilizza l’asset multimediale non ne è il creatore, non implementare la marcatura dei metadata.

Il Creative Metadata Tagging consente di attribuire correttamente immagini e video creati dai Creative Partner, indipendentemente da dove l’asset venga caricato su X o da chi lo stia caricando. Per creare il collegamento tra l’asset creativo e il creative partner, viene utilizzato lo standard XMP.

​

Tagging degli asset creativi

La tabella seguente mostra i tipi di identificatori attualmente disponibili nella risposta di ciascuna risorsa relativa alle immagini, nonché i nomi degli attributi corrispondenti. Per etichettare gli asset creativi è necessario uno strumento di tagging. Si consiglia ExifTool, una libreria Perl multipiattaforma con un’applicazione da riga di comando per leggere, scrivere e modificare le informazioni di metadati. Consulta tutti i formati di file supportati.

Segui le istruzioni per installare ExifTool fornite. Sono inoltre disponibili pacchetti software offerti da Homebrew per semplificare ulteriormente l’installazione, fornendo il comando di installazione di exiftool per macOS e Linux. Verifica che lo strumento sia installato correttamente inserendo exiftool -ver nella riga di comando per visualizzare il numero di versione dello strumento. Scopri di più sui parametri dei comandi di ExifTool nella documentazione di ExifTool.

I partner creativi possono assegnare tag di metadati agli asset creativi, nuovi o esistenti, impostando il proprio X app_id nel tag XMP contributor e il tag date. Gli asset creativi rispetteranno le limitazioni di dimensione esistenti durante il caricamento dei media.

Nota: L’uso da parte di X del tag XMP contributor garantisce che i metadati acquisiscano valori esclusivamente per le campagne su X.

exiftool -contributor="<YOUR APP ID>" -creative_file.jpg

exiftool -date="<date>" -creative_file.jpg

L’app_id è disponibile nel developer portal alla voce Projects & Apps. Esempio: 16489123

Il seguente esempio aggiunge app_id come tag contributor e date come tag date per un’immagine:

app_id:858382169

data:2022-03-13

creative_file: eiffel_tower.jpg

exiftool -contributor=858382169 eiffel_tower.jpg

   1 file immagine aggiornati

exiftool -date=2022-03-13 eiffel_tower.jpg

  1 file immagine aggiornati

Verifica che l’immagine sia stata correttamente etichettata:

exiftool -xmp:all -G1 <filename>

Esempio:

exiftool -xmp:all -G1 eiffel_tower.jpg

[XMP]        Toolkit XMP            : Image::ExifTool 12.30

[XMP]        Autore            : 858382169

[XMP]        Data                   : 2022:03:13

​

Domande?

Se desideri verificare che il tagging e l’attribuzione siano stati eseguiti correttamente, invia risorse di esempio già taggate a [e-mail], così che un rappresentante di X possa esaminarle.

​

Riferimenti API

​

Media account

Apri in Postman

​

GET accounts/:account_id/account_media

Recupera i dettagli di alcuni o di tutti i contenuti multimediali dell’account associati all’account corrente.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/account_media

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
account_media_ids opzionale	Limita la risposta ai soli media dell’account desiderati specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Tipo: string Esempio: 3wpx
count opzionale	Specifica il numero di record da tentare di recuperare per ogni singola richiesta. Tipo: int Predefinito: 200 Min, Max: 1, 1000
creative_types opzionale	Limita la risposta ai soli media dell’account che corrispondono ai tipi creativi specificati. È possibile indicare più di un tipo creativo separando con virgole i valori dell’enum. Tipo: enum Valori possibili: BANNER, BANNER_TABLET, INTERSTITIAL, INTERSTITIAL_LANDSCAPE, INTERSTITIAL_LANDSCAPE_TABLET, INTERSTITIAL_TABLET, MEDIUM_RECTANGLE, PREROLL, VAST_PREROLL
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedere Pagination per maggiori informazioni. Tipo: string Esempio: 8x7v00oow
sort_by opzionale	Ordina per attributo supportato in ordine crescente o decrescente. Vedere Sorting per maggiori informazioni. Tipo: string Esempio: created_at-asc
with_deleted opzionale	Include i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false
with_total_count opzionale	Include l’attributo di risposta total_count. Nota: questo parametro e cursor sono mutuamente esclusivi. Nota: le richieste che includono total_count hanno limiti di velocità inferiori, attualmente pari a 200 ogni 15 minuti. Tipo: boolean Predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media?account_media_ids=3wpx

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_media_ids": [
        "3wpx"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_id": "13_771791717175468032",
      "media_url": null,
      "creative_type": "PREROLL",
      "id": "3wpx",
      "created_at": "2016-09-02T19:27:52Z",
      "updated_at": "2016-09-02T19:27:52Z",
      "deleted": false
    }
  ]
}

Recupera un oggetto multimediale specifico dell’account associato all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Ads, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
account_media_id obbligatorio	Un riferimento ai media dell’account utilizzati nella richiesta. Tipo: string Esempio: 2pnfd
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Tipo: boolean Valore predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_media_id": "2pnfd",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-07-28T01:44:41Z",
    "deleted": false
  }
}

Elimina l’oggetto multimediale dell’account specificato che appartiene all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/account_media/:account_media_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
account_media_id obbligatorio	Un riferimento ai contenuti multimediali dell’account con cui operi nella richiesta. Type: string Example: 2pnfd

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/account_media/2pnfd

​

Esempio di risposta

{
  "data": {
    "video_id": null,
    "media_url": "https://pbs.twimg.com/ad_img/890749735862026242/Up07zMym?format=jpg&name=orig",
    "creative_type": "INTERSTITIAL_LANDSCAPE_TABLET",
    "id": "2pnfd",
    "created_at": "2017-07-28T01:44:41Z",
    "updated_at": "2017-08-25T17:16:26Z",
    "deleted": true
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "account_media_id": "2pnfd"
    }
  }
}

​

Schede

Apri in Postman

Nota: Per associare una scheda a un Tweet, usa il parametro card_uri con uno degli endpoint POST accounts/:account_id/tweet, POST statuses/update, POST accounts/:account_id/scheduled_tweets o POST accounts/:account_id/draft_tweets.

Recupera i dettagli di alcune o tutte le schede associate all’account corrente.

Nota: Questo restituisce solo le schede create tramite l’endpoint POST accounts/:account_id/cards. Le schede create tramite altri endpoint non vengono restituite.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
card_types opzionale	Limita la risposta ai soli tipi di card desiderati specificando un elenco di valori enum separati da virgole. Tipo: enum Valori possibili: IMAGE_APP, IMAGE_CAROUSEL_APP, IMAGE_CAROUSEL_WEBSITE, IMAGE_MULTI_DEST_CAROUSEL_WEBSITE, IMAGE_WEBSITE, MIXED_MEDIA_MULTI_DEST_CAROUSEL_WEBSITE, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_APP, MIXED_MEDIA_SINGLE_DEST_CAROUSEL_WEBSITE, VIDEO_APP, VIDEO_CAROUSEL_APP, VIDEO_CAROUSEL_WEBSITE, VIDEO_MULTI_DEST_CAROUSEL_WEBSITE, VIDEO_WEBSITE
card_id opzionale	Limita la risposta alle sole card desiderate specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID di card. Tipo: string Esempio: 1044294149527166979,1044301099031658496
card_uris opzionale	Limita la risposta alle sole card desiderate specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 valori URI di card. Tipo: string Esempio: card://1044294149527166979,card://1044301099031658496
count opzionale	Specifica il numero di record da tentare di recuperare per ciascuna richiesta. Tipo: int Predefinito: 100 Min, Max: 1, 200
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per ulteriori informazioni. Tipo: string Esempio: 8x7v00oow
include_legacy_cards opzionale	Includi nella risposta le card legacy per siti web e app. Le card legacy sono quelle il cui URL della risorsa ha il seguente formato: accounts/:account_id/cards/:card_type. Consulta questo post del forum degli sviluppatori per ulteriori dettagli. Tipo: boolean Predefinito: false Valori possibili: true, false
q opzionale	Query facoltativa per limitare le card in base a name. Omettere questo parametro per recuperarle tutte. Lunghezza massima: 80 caratteri. Nota: esegue un confronto di prefisso senza distinzione tra maiuscole e minuscole. Tipo: string Esempio: dtc
sort_by opzionale	Ordina per attributo supportato, in ordine crescente o decrescente. Vedi Sorting per ulteriori informazioni. Tipo: string Esempio: created_at-asc
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards?count=1

​

Esempio di risposta

{
  "request": {
    "params": {
      "count": 1,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": "8wzvldqtc",
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN",
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

Recupera i dettagli di una singola scheda associata all’account corrente.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Ads, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_id obbligatorio	id delle card. Type: string Example: 1044294149527166979
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "OPEN",
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-28T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

POST accounts/:account_id/cards

Crea una nuova card associata all’account specificato.

Le richieste di creazione delle card accettano solo body POST in JSON. Il Content-Type deve essere impostato su application/json.

Consulta la nostra Guida ai Caroselli per un esempio di utilizzo dettagliato.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards

​

Parametri

Il body JSON della richiesta POST deve includere il name della card e un array di components. I componenti sono rappresentati come oggetti e descrivono gli attributi della card visibili agli inserzionisti.

Il seguente esempio mostra la struttura generale del payload (ma contiene informazioni di esempio non operative).

{
  "name": "un nome",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "valore"
    }
  ]
}

Ulteriori informazioni sui componenti di seguito.

Name	Description
account_id required	L’identificatore dell’account sfruttato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
name required	Il nome della card. Lunghezza massima: 80 caratteri. Type: string Example: component based card
components sometimes required	Descrive i componenti da utilizzare per creare la card. Ulteriori informazioni di seguito. Non può essere specificato insieme a slides. Nota: l’ordine dei componenti è importante. Type: array of objects
slides sometimes required	Usa questo array di array per creare Multi-Destination Carousels. Descrive ciascuna card come un raggruppamento di componenti. Ogni slide dovrebbe essere una rappresentazione completa di una card. Non può essere specificato insieme a components. Nota: l’ordine di ciascuna slide è importante. Type: array of array

​

Componenti

Ogni componente deve includere un campo type che determina lo schema dell’oggetto. La X Ads API supporta i seguenti tipi di componenti, raggruppati in componenti basati su contenuti multimediali e su descrizione.

• Media:
• MEDIA: singolo video o immagine
• SWIPEABLE_MEDIA: da 2 a 6 video o immagini
• Descrizione:
• DETAILS
• BUTTON

Ogni componente ha un insieme di campi obbligatori (oltre alla chiave type). Questi sono elencati nella tabella seguente.

type del componente	Campo	Tipo di valore
MEDIA	media_key	string
SWIPEABLE_MEDIA	media_keys	array of strings
DETAILS	title destination	string object
BUTTON	label destination	object object

Di seguito è riportato un esempio di un componente BUTTON nel contesto dell’array components (omettendo intenzionalmente la chiave name). (I puntini di sospensione indicano i punti in cui andrebbero specificate ulteriori informazioni.)

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        ...
      },
      "destination": {
        ...
      }
    }
  ]
}

L’ordine in cui vengono specificati i componenti ne determina l’ordine di rendering dall’alto verso il basso. Le card devono essere create utilizzando un componente basato su contenuti multimediali e, in aggiunta, un componente DETAILS oppure BUTTON. I componenti basati sulla descrizione vengono renderizzati sotto i contenuti multimediali e hanno destinazioni associate, ovvero URL o app per dispositivi mobili.

Etichetta

Le etichette definiscono il testo visualizzato sui pulsanti e, pertanto, si applicano solo al componente BUTTON. Gli oggetti etichetta hanno due chiavi obbligatorie: type e value. Il type deve essere impostato su ENUM e il value può essere uno tra: BOOK, CONNECT, INSTALL, OPEN, ORDER, PLAY o SHOP.

Sulla base dell’esempio precedente, il seguente mostra l’oggetto label all’interno del componente BUTTON.

{
  "components": [
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALL"
      },
      "destination": {
        ...
      }
    }
  ]
}

Destinazione

Le destinazioni sono le mete verso cui gli inserzionisti intendono indirizzare gli utenti. Sono sempre richieste all’interno dei componenti DETAILS o BUTTON. Esistono due tipi di destinazione: WEBSITE o APP.

Nota: Le destinazioni di tipo website possono essere usate solo con i componenti DETAILS e le destinazioni di tipo app solo con i componenti BUTTON.

Destinazione Website

Nome	Descrizione
type obbligatorio	Il tipo di destinazione, che ne determina lo schema. Tipo: enum Valori possibili: WEBSITE
url obbligatorio	L’URL del sito web a cui reindirizzare l’utente. Tipo: string Esempio: https://devcommunity.x.com/c/advertiser-api

Destinazione App

Nome	Descrizione
type obbligatorio	Il tipo di destinazione, che ne determina lo schema. Tipo: enum Valori possibili: APP
country_code obbligatorio	Il codice a due lettere ISO 3166-1 alpha-2 del paese in cui l’App è in vendita. Tipo: string Esempio: US
googleplay_app_id talvolta obbligatorio	Il nome del pacchetto dell’app su Google Play. Nota: È richiesto almeno uno dei seguenti: ios_app_store_identifier o googleplay_app_id. Tipo: string Esempio: com.twitter.android
ios_app_store_identifier talvolta obbligatorio	L’identificatore sull’App Store iOS. Nota: È richiesto almeno uno dei seguenti: ios_app_store_identifier o googleplay_app_id. Tipo: string Esempio: 333903271
googleplay_deep_link opzionale	Un deep link nell’app Android che stai promuovendo. Nota: Può essere utilizzato solo se è stato fornito un googleplay_app_id. Tipo: string
ios_deep_link opzionale	Un deep link nell’app iOS che stai promuovendo. Nota: Può essere utilizzato solo se è stato fornito un ios_app_store_identifier. Tipo: string

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards

{
  "name": "creazione componenti schede",
  "components": [
    {
      "type": "MEDIA",
      "media_key": "3_1323490622599176192"
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "INSTALLA"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android"
      }
    }
  ]
}

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "crea componenti schede"
    "components": [
      {
        "type": "MEDIA",
        "media_key": "3_1323490622599176192"
      },
      {
        "type": "BUTTON"
        "label": {
          "type": "ENUM",
          "value": "INSTALL"
        },
        "destination": {
          "type": "APP",
          "country_code": "US"
          "googleplay_app_id": "com.twitter.android"
        }
      }
    ],
    "created_at": "2020-11-11T05:42:25Z",
    "card_uri": "card://1326399865065238531",
    "id": "1321554298900107264",
    "updated_at": "2020-11-11T05:42:25Z",
    "deleted": false
    "card_type": "IMAGE_APP"
  }
}

Aggiorna l’elemento specificato associato all’account corrente.

Le richieste di modifica delle Card accettano solo corpi POST in formato JSON. Il Content-Type deve essere impostato su application/json.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/1321554298900107264

​

Parametri

Il body JSON della richiesta POST deve includere i parametri da aggiornare. La richiesta sostituirà ogni campo con i parametri specificati nel payload. I componenti sono rappresentati come oggetti e descrivono gli attributi della card visibili all’inserzionista.

Il seguente esempio mostra la struttura generale del payload (ma contiene informazioni non operative).

{
  "name": "un nome",
  "components": [
    {
      "type": "TYPE_ENUM",
      "key": "valore"
    }
  ]
}

Informazioni aggiuntive su componenti e slide in POST accounts/:account_id/cards.

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
name opzionale	Il nome della card. Lunghezza massima: 80 caratteri. Tipo: string Esempio: component based card
components opzionale	Descrive i componenti da usare per aggiornare la card. Ulteriori informazioni di seguito. Non può essere specificato insieme a slides. Nota: l’ordine dei componenti è importante. Tipo: array di oggetti
slides opzionale	Usa questo array di array per aggiornare i Multi-Destination Carousel. Descrive ciascuna card come un raggruppamento di componenti. Ogni slide dovrebbe essere una rappresentazione completa di una card. Non può essere specificato insieme a components. Nota: l’ordine di ciascuna slide è importante. Tipo: array di array

​

Esempio di richiesta

Questo esempio aggiorna il nome e rimuove una delle media_keys dal campo components dell’esempio precedente.

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

{
  "name": "nome modificato",
  "components": [
    {
      "type": "SWIPEABLE_MEDIA",
      "media_keys": [
        "3_1075096386931052545"
      ]
    },
    {
      "type": "BUTTON",
      "label": {
        "type": "ENUM",
        "value": "APRI"
      },
      "destination": {
        "type": "APP",
        "country_code": "US",
        "googleplay_app_id": "com.twitter.android",
        "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
      }
    }
  ]
}

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "nome modificato",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "APRIRE"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": false,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

Elimina la card specificata appartenente all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Ads, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: stringa Esempio: 18ce54d4x5t
card_id obbligatorio	L’id della card da eliminare. Tipo: stringa Esempio: 1044294149527166979

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/1321554298900107264

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_id": "1321554298900107264"
    }
  },
  "data": [
    {
      "name": "deep link",
      "components": [
        {
          "type": "SWIPEABLE_MEDIA",
          "media_keys": [
            "3_1073727809120419840",
            "3_1075096386931052545"
          ]
        },
        {
          "type": "BUTTON",
          "label": {
            "type": "ENUM",
            "value": "APRI"
          },
          "destination": {
            "type": "APP",
            "country_code": "US",
            "googleplay_app_id": "com.twitter.android",
            "googleplay_deep_link": "twitter://user?screen_name=apimctestface"
          }
        }
      ],
      "created_at": "2020-10-28T20:47:52Z",
      "card_uri": "card://1321554298900107264",
      "id": "1321554298900107264",
      "updated_at": "2020-10-29T20:47:52Z",
      "deleted": true,
      "card_type": "IMAGE_CAROUSEL_APP"
    }
  ]
}

​

Recupero delle Card

Apri in Postman

Recupera più Card, identificate dal rispettivo card_uri, associate all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/all

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account con leva. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
card_uris obbligatorio	Limita la risposta alle sole card desiderate specificando un elenco di identificatori separati da virgola. È possibile fornire fino a 200 valori di URI di card. Tipo: string Esempio: card://1044294149527166979,card://1044301099031658496
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all?card_uris=card://1044294149527166979,card://1044301099031658496

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_uris": [
        "card://1044294149527166979",
        "card://1044301099031658496"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "name": "X App",
      "googleplay_app_id": "com.twitter.android",
      "image_display_height": "836",
      "country_code": "US",
      "id": "692xn",
      "wide_app_image": "https://pbs.twimg.com/media/Dc263l9VwAAAeEH.jpg",
      "created_at": "2018-09-24T18:35:01Z",
      "image_display_width": "1600",
      "card_uri": "card://1044294149527166979",
      "updated_at": "2018-09-24T18:35:01Z",
      "app_cta": "INSTALLA",
      "deleted": false,
      "card_type": "IMAGE_APP_DOWNLOAD"
    },
    {
      "video_poster_height": "9",
      "name": "Piattaforma per sviluppatori",
      "website_shortened_url": "https://t.co/zadeUSVD18",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/991374284135137280.vmap",
      "content_duration_seconds": "24",
      "video_owner_id": "756201191646691328",
      "video_content_id": "13_991374284135137280",
      "website_display_url": "developer.x.com",
      "id": "6933h",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/991374284135137280/pl/sQrBsE9mFvNep9Cx.m3u8?tag=2",
      "website_dest_url": "https://developer.x.com",
      "created_at": "2018-09-24T19:02:38Z",
      "card_uri": "card://1044301099031658496",
      "title": "Piattaforma per sviluppatori",
      "website_url": "https://developer.x.com",
      "updated_at": "2018-09-24T19:02:38Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/991374284135137280/img/YbbGQHvWRjoFgrLz.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_WEBSITE"
    }
  ]
}

Recupera una specifica scheda, tramite card_id, associata all’account corrente.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/all/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_id obbligatorio	Un riferimento alla card utilizzata nella richiesta. Type: string Example: 508pf
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/all/508pf

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_id": "508pf",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "scheda video per sito web",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/867520357225418752.vmap",
    "content_duration_seconds": "21",
    "video_owner_id": "756201191646691328",
    "video_content_id": "13_867520357225418752",
    "website_display_url": "developer.x.com",
    "id": "508pf",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/867520357225418752/pl/TPHeH5ZlHFCa2TeJ.m3u8",
    "website_dest_url": "https://developer.x.com/en/docs/ads/creatives/api-reference/video-website#post-accounts-account-id-cards-video-website",
    "created_at": "2017-11-10T09:00:35Z",
    "card_uri": "card://928910245920829440",
    "title": "VWC",
    "website_url": "https://t.co/F81hp59pUF"
    "updated_at": "2018-01-05T05:43:31Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/867520357225418752/img/E3pnXM0sCKnRsFih.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_WEBSITE"
  }
}

​

Bozze di Tweet

Apri in Postman

​

GET accounts/:account_id/draft_tweets

Recupera i dettagli di alcuni o di tutti i Draft Tweet associati all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
count opzionale	Specifica il numero di record da recuperare per ciascuna richiesta. Tipo: int Predefinito: 100 Min, Max: 1, 200
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per ulteriori informazioni. Tipo: string Esempio: c-jh1g0ryb
user_id opzionale	Specifica l’utente per cui recuperare i Draft Tweet. Se non impostato, il valore predefinito è l’utente promuovibile FULL sull’account. Tipo: string Esempio: 756201191646691328

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?count=1

​

Esempio di risposta

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name" null,
      "text": "ciao, mondo",
      "user_id": "756201191646691328",
      "id": "994791681219231744",
      "nullcast": true,
      "created_at": "2018-05-11T04:09:53Z",
      "card_uri": null,
      "updated_at": "2018-05-11T04:09:53Z",
      "media_keys": []
    }
  ],
  "next_cursor": "c-jh1g0ryb"
}

Recupera una specifica bozza di Tweet associata all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account con leva. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: stringa Esempio: 18ce54d4x5t
draft_tweet_id obbligatorio	Riferimento al Draft Tweet con cui si opera nella richiesta. Tipo: stringa Esempio: 994788364334325760

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994788364334325760

​

Risposta di esempio

{
  "request": {
    "params": {
      "draft_tweet_id": "994788364334325760"
    }
  },
  "data": {
    "name": null,
    "#TwitterDev",
    "user_id": "756201191646691328",
    "id": "994788364334325760",
    "nullcast": true,
    "created_at": "2018-05-11T03:56:42Z",
    "card_uri": "card://958225772740714496",
    "updated_at": "2018-05-11T03:56:42Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets

Crea un Tweet in bozza per l’utente completamente promuovibile dell’account (impostazione predefinita) oppure per l’utente specificato nel parametro as_user_id.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/draft_tweets

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Esempio: 18ce54d4x5t
as_user_id obbligatorio	L’id utente dell’inserzionista per conto del quale pubblichi il Tweet. L’inserzionista deve concedere al tuo handle (o ai tuoi handle) l’accesso al suo account pubblicitario tramite ads.x.com. Questa autorizzazione consente di chiamare l’API utilizzando i token OAuth del tuo handle anziché quelli dell’inserzionista. Type: string Esempio: 756201191646691328
text talvolta obbligatorio	Il testo dell’aggiornamento di stato. Obbligatorio se non vengono specificati media_keys. Type: string Esempio: Just setting up my X.
card_uri opzionale	Associa una card al Tweet utilizzando il valore card_uri restituito da qualsiasi risposta delle card, se disponibile. Type: string Esempio: card://960880280705392541
media_keys opzionale	Associa media al Tweet specificando un elenco di identificatori separati da virgole. Includi fino a 4 immagini, 1 GIF animata o 1 video. Nota: l’asset multimediale deve trovarsi nella Media Library dell’account. Type: string Esempio: 13_1153584529292270722
nullcast opzionale	Se creare un Tweet nullcast (o “solo Promoted”). Type: boolean Predefinito: true Valori possibili: true, false
name opzionale	Il nome del Draft Tweet. Lunghezza massima: 80 caratteri. Type: string Esempio: Tweet with name

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets?as_user_id=756201191646691328&text=Just setting up my X.

​

Esempio di risposta

{
  "request": {
    "params": {
      "text": "Sto impostando il mio X.",
      "as_user_id": "756201191646691328"
    }
  },
  "data": {
    "name": null,
    "text": "Sto impostando il mio X.",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:14:13Z",
    "media_keys": []
  }
}

Aggiorna il Draft Tweet specificato dell’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
draft_tweet_id obbligatorio	Un riferimento al Draft Tweet con cui stai operando nella richiesta. Type: string Example: 994747471329873920
card_uri opzionale	Associa una card al Tweet usando il valore card_uri da qualsiasi risposta delle card, se disponibile. Nota: Per annullare l’impostazione (rimuovere), specifica il parametro senza valore. Type: string Example: card://970582057284129151
media_keys opzionale	Associa contenuti multimediali al Tweet specificando un elenco di identificatori separati da virgole. Puoi includere fino a 4 immagini, 1 GIF animata o 1 video. Nota: La risorsa multimediale deve trovarsi nella Media Library dell’account. Nota: Per annullare l’impostazione (rimuovere), specifica il parametro senza valore. Type: string Example: 13_1153584529292270722
nullcast opzionale	Se creare un Tweet in nullcast (o “solo promozione”). Type: boolean Possible values: true, false
text opzionale	Il testo dell’aggiornamento di stato. Type: string Example: just setting up my twttr
name opzionale	Il nome del Draft Tweet. Lunghezza massima: 80 caratteri. Type: string Example: Tweet with name

​

Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994747471329873920?text=just setting up my twttr

​

Esempio di risposta

{
  "request": {
    "params": {
      "draft_tweet_id": 994747471329873920,
      "text": "sto solo impostando il mio twttr"
    }
  },
  "data": {
    "name": null,
    "text": "sto solo impostando il mio twttr",
    "user_id": "756201191646691328",
    "id": "994747471329873920",
    "nullcast": true,
    "created_at": "2018-05-11T01:14:13Z",
    "card_uri": null,
    "updated_at": "2018-05-11T01:16:59Z",
    "media_keys": []
  }
}

Elimina in modo permanente il Draft Tweet specificato appartenente all’account corrente.

Nota: Consigliamo vivamente di eliminare le bozze dopo che un Tweet o un Scheduled Tweet è stato creato utilizzando i relativi metadata.

Nota: Si tratta di un’eliminazione definitiva. Di conseguenza, non è possibile recuperare i Draft Tweet eliminati.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/:draft_tweet_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account con leva. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
draft_tweet_id obbligatorio	Un riferimento al Draft Tweet con cui operi nella richiesta. Type: string Example: 994787835663155200

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/994787835663155200

​

Esempio di risposta

{
  "request": {
    "params": {
      "draft_tweet_id": "994787835663155200"
    }
  },
  "data": {
    "name": null,
    "text": "ciao, mondo",
    "user_id": "756201191646691328",
    "id": "994787835663155200",
    "nullcast": true,
    "status": "DELETED",
    "created_at": "2018-05-11T03:54:36Z",
    "card_uri": null,
    "updated_at": "2018-05-11T04:07:31Z",
    "media_keys": []
  }
}

​

POST accounts/:account_id/draft_tweets/preview/:draft_tweet_id

Visualizza l’anteprima di un Tweet in bozza su un dispositivo mobile.

Una richiesta riuscita invia una notifica a ogni dispositivo su cui l’utente autenticato ha effettuato l’accesso. Facendo clic sulla notifica si apre una timeline che consente all’utente di vedere e interagire con il Tweet in bozza, permettendo di testare la riproduzione automatica, il volume, la modalità a schermo intero, l’ancoraggio della video website card e altri comportamenti.

Nota: Le anteprime sul dispositivo sono visibili solo all’utente che riceve la notifica.

Nota: Le notifiche vengono inviate solo alle app ufficiali di X.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/draft_tweets/preview/:draft_tweet_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account oggetto di utilizzo. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API per gli inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
draft_tweet_id obbligatorio	Un riferimento al Draft Tweet utilizzato nella richiesta. Type: string Example: 996132315829948416

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/draft_tweets/preview/996132315829948416

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "draft_tweet_id": "996132315829948416"
    }
  },
  "message": "Controlla le notifiche di @apimctestface nell'app X per visualizzare l'anteprima del tuo Tweet."
}

​

Card conversazionale con immagine

Apri in Postman

Nota: per associare una card a un Tweet, usa il parametro card_uri con uno degli endpoint POST accounts/:account_id/tweet, POST statuses/update o POST accounts/:account_id/scheduled_tweets.

​

GET accounts/:account_id/cards/image_conversation

Recupera i dettagli di alcune o tutte le schede di conversazione con immagini associate all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account leveraged. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
card_ids opzionale	Limita la risposta alle sole image conversation cards desiderate specificando un elenco di identificatori separati da virgole. Possono essere forniti fino a 200 ID. Tipo: string Esempio: 59woh
count opzionale	Specifica il numero di record da recuperare per ciascuna richiesta. Tipo: int Predefinito: 200 Min, Max: 1, 1000
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per maggiori informazioni. Tipo: string Esempio: 8x7v00oow
q opzionale	Una query opzionale per filtrare le cards in base a name. Omesso questo parametro, verranno recuperate tutte. Lunghezza massima: 80 caratteri. Nota: Esegue un confronto sul prefisso senza distinzione tra maiuscole e minuscole. Tipo: string Esempio: night
sort_by opzionale	Ordina per l’attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Tipo: string Esempio: created_at-asc
with_deleted opzionale	Includi nella richiesta anche i risultati eliminati. Tipo: boolean Predefinito: false Valori possibili: true, false
with_total_count opzionale	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor si escludono a vicenda. Nota: Le richieste che includono total_count avranno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Tipo: boolean Predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?card_ids=59woh

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_ids": [
        "59woh"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "card conversazione immagine",
      "first_cta": "#moon",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "grazie",
      "id": "59woh",
      "first_cta_tweet": "stelle",
      "media_key": "3_957113581522141184",
      "created_at": "2018-01-27T04:58:42Z",
      "image_display_width": "1280",
      "card_uri": "card://923498485702009837",
      "title": "Luna piena"
      "updated_at": "2018-01-27T04:58:42Z",
      "deleted": false,
      "card_type": "IMAGE_CONVERSATION"
    }
  ]
}

Recupera una scheda conversazione immagine specifica associata all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account leveraged. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Ads, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_id obbligatorio	Riferimento alla image conversation card a cui si riferisce la richiesta. Type: string Example: 59woh
with_deleted opzionale	Includi anche i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_type": "image_conversation",
      "card_id": "59woh",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "scheda conversazione immagine",
    "first_cta": "#luna",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "grazie",
    "id": "59woh",
    "first_cta_tweet": "stelle",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Luna piena"
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  }
}

​

POST accounts/:account_id/cards/image_conversation

Crea una nuova card di conversazione con immagine associata all’account specificato.

Consulta Caricamento dei media per informazioni utili sul caricamento di immagini sui nostri endpoint.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
first_cta obbligatorio	L’hashtag di Call-To-Action (CTA) per la prima opzione. Lunghezza massima: 20 caratteri (escludendo il #). Type: string Example: #ShareNow
first_cta_tweet obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la prima CTA. Type: string Example: I Heart @AdsAPI
media_key obbligatorio	La chiave multimediale per un’immagine da utilizzare in questa card. Nota: l’immagine deve essere nella Media Library dell’account. Nota: è richiesta una larghezza minima dell’immagine di 800 px e un rapporto larghezza:altezza di 1,91:1. Type: string Example: 3_1151345051104991073
name obbligatorio	Il nome della card. Type: string Example: image conversation card
thank_you_text obbligatorio	Il testo da visualizzare dopo il clic sulla CTA. Lunghezza massima: 23 caratteri. Type: string Example: Thank you
second_cta a volte obbligatorio	L’hashtag di Call-To-Action (CTA) per la seconda opzione. Lunghezza massima: 20 caratteri (escludendo il #). Type: string Nota: obbligatorio se title non è impostato. Example: #ShareAgain
second_cta_tweet a volte obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la seconda CTA. Nota: obbligatorio se second_cta è impostato. Type: string Example: I Heart @AdsAPI Again
title a volte obbligatorio	Il titolo della card, visualizzato sotto l’immagine e sopra le CTA. Lunghezza massima: 23 caratteri. Type: string Nota: obbligatorio se second_cta non è impostato. Example: Start a conversation
third_cta opzionale	L’hashtag di Call-To-Action (CTA) per la terza opzione. Lunghezza massima: 20 caratteri (escludendo il #). Type: string Example: #ShareMore
third_cta_tweet a volte obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la terza CTA. Type: string Nota: obbligatorio se third_cta è impostato. Example: I Heart @TwitterDev
fourth_cta opzionale	L’hashtag di Call-To-Action (CTA) per la quarta opzione. Lunghezza massima: 20 caratteri (escludendo il #). Type: string Example: #ShareExtra
fourth_cta_tweet a volte obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la quarta CTA. Type: string Nota: obbligatorio se fourth_cta è impostato. Example: I Heart @TwitterDev Again
unlocked_image_media_key opzionale	Un media_key di un’immagine che verrà utilizzata nello scenario di sblocco immediato. Campo di sola scrittura. Nella risposta, l’API fornirà un URL di X per questa immagine. Nota: l’immagine deve essere nella libreria multimediale dell’account. Nota: è richiesta una larghezza minima dell’immagine di 800 px e un rapporto larghezza:altezza di 5:2. Type: string Example: 3_883112887618682880
thank_you_url opzionale	L’URL da visualizzare insieme al testo di ringraziamento. Type: string Example: https://example.com/thankyou

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation?media_key=3_957113581522141184&name=image conversation card&first_cta=#moon&first_cta_tweet=stars&thank_you_text=thanks&title=Full moon

​

Esempio di risposta

{
  "data": {
    "name": "scheda conversazione con immagine",
    "first_cta": "#luna",
    "image_display_height": "670",
    "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
    "thank_you_text": "grazie",
    "id": "59woh",
    "first_cta_tweet": "stelle",
    "media_key": "3_957113581522141184",
    "created_at": "2018-01-27T04:58:42Z",
    "image_display_width": "1280",
    "card_uri": "card://923498485702009837",
    "title": "Luna piena",
    "updated_at": "2018-01-27T04:58:42Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "name": "scheda conversazione con immagine",
      "first_cta": "#luna",
      "image_display_height": "670",
      "media_url": "https://pbs.twimg.com/media/DUhZuzxUQAAWZqr.jpg",
      "thank_you_text": "grazie",
      "media_key": "3_957113581522141184",
      "account_id": "18ce54d4x5t",
      "first_cta_tweet": "stelle",
      "image_display_width": "1280",
      "title": "Luna piena"
      "card_type": "IMAGE_CONVERSATION"
    }
  }
}

Aggiorna la scheda conversazione immagine specificata appartenente all’account corrente.

Vedi Caricamento dei media per informazioni utili sul caricamento di immagini verso i nostri endpoint.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parametri

Name	Description
account_id required	L’identificatore dell’account a leva. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertising, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_id required	Un riferimento alla image conversation card utilizzata nella richiesta. Type: string Example: 4i0qg
first_cta optional	L’hashtag della Call-To-Action (CTA) per la prima opzione. Lunghezza massima: 20 caratteri (escluso il #). Type: string Example: #ShareNow
first_cta_tweet optional	Il testo del Tweet da utilizzare quando si fa clic sulla prima CTA. Type: string Example: I Heart @AdsAPI
second_cta optional	L’hashtag della Call-To-Action (CTA) per la seconda opzione. Lunghezza massima: 20 caratteri (escluso il #). Type: string Nota: Obbligatorio se title non è impostato. Example: #ShareAgain
second_cta_tweet optional	Il testo del Tweet da utilizzare quando si fa clic sulla seconda CTA. Nota: Obbligatorio se second_cta è impostato. Type: string Example: I Heart @AdsAPI Again
third_cta optional	L’hashtag della Call-To-Action (CTA) per la terza opzione. Lunghezza massima: 20 caratteri (escluso il #). Type: string Example: #ShareMore
third_cta_tweet optional	Il testo del Tweet da utilizzare quando si fa clic sulla terza CTA. Type: string Nota: Obbligatorio se third_cta è impostato. Example: I Heart @TwitterDev
fourth_cta optional	L’hashtag della Call-To-Action (CTA) per la quarta opzione. Lunghezza massima: 20 caratteri (escluso il #). Type: string Example: #ShareExtra
fourth_cta_tweet optional	Il testo del Tweet da utilizzare quando si fa clic sulla quarta CTA. Type: string Nota: Obbligatorio se fourth_cta è impostato. Example: I Heart @TwitterDev Again
media_key optional	La media key per un’immagine da utilizzare in questa card. Nota: L’immagine deve trovarsi nella Media Library dell’account. Nota: È richiesta una larghezza minima dell’immagine di 800 px e un rapporto larghezza:altezza di 1,91:1. Type: string Example: 3_1151345051104991073
name optional	Il nome della card. Type: string Example: moon card
thank_you_text optional	Il testo da visualizzare dopo il clic sulla CTA. Lunghezza massima: 23 caratteri. Type: string Example: Thank you
thank_you_url optional	L’URL da visualizzare insieme al testo di ringraziamento. Type: string Example: https://example.com/thankyou
title optional	Il titolo della card, visualizzato sotto l’immagine e sopra le CTA. Lunghezza massima: 23 caratteri. Type: string Nota: Obbligatorio se second_cta non è impostato. Example: Start a conversation
unlocked_image_media_key optional	Un media_key di un’immagine che verrà utilizzata nello scenario di instant unlock. Questo è un campo di sola scrittura. Nella risposta, l’API fornirà un URL di X per questa immagine. Nota: L’immagine deve trovarsi nella Media Library dell’account. Nota: È richiesta una larghezza minima dell’immagine di 800 px e un rapporto larghezza:altezza di 5:2. Type: string Example: 3_883112887618682880

​

Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/59woh?name=moon card

​

Esempio di risposta

{
  "data": {
    "name": "moon card",
    "id": "59woh",
    "created_at": "2018-01-27T04:58:42Z",
    "card_uri": "card://923498485702009837",
    "updated_at": "2018-01-29T21:04:39Z",
    "deleted": false,
    "card_type": "IMAGE_CONVERSATION",
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "IMAGE_CONVERSATION",
      "card_id": "59woh",
      "name": "moon card"
    }
  }
}

Elimina in modo permanente la scheda conversazione immagine specificata appartenente all’account corrente.

Nota: Si tratta di un’eliminazione definitiva. Di conseguenza, non è possibile recuperare le schede eliminate.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/image_conversation/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account leveraged. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, tranne GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
card_id obbligatorio	Un riferimento alla image conversation card utilizzata nella richiesta. Tipo: string Esempio: 4i0qe

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/image_conversation/4i0qe

​

Esempio di risposta

{
  "data": {
    "name": "scheda conversazione con immagine",
    "id": "4i0qe",
    "created_at": "2017-07-07T00:03:01Z",
    "updated_at": "2017-08-23T13:26:23Z",
    "deleted": true,
    "card_type": "IMAGE_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0qe",
      "card_type": "image_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Libreria media

Apri in Postman

​

GET accounts/:account_id/media_library

Recupera i dettagli di alcuni o di tutti gli oggetti della libreria multimediale associati all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/media_library

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account con leva. È presente nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
count opzionale	Specifica il numero di record da recuperare per ogni singola richiesta. Tipo: int Predefinito: 20 Min, Max: 1, 50
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedi Pagination per ulteriori informazioni. Tipo: string Esempio: c-1
media_type opzionale	Limita la risposta al tipo di contenuto multimediale desiderato. Tipo: enum Valori possibili: GIF, IMAGE, VIDEO
q opzionale	Parametro query facoltativo per limitare la risorsa in base ai campi name, title, file_name e description. Nota: esegue il matching dei termini senza distinzione tra maiuscole e minuscole. Tipo: string Lunghezza min, max: 1, 255

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?count=1

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "count": 1
    }
  },
  "data": [
    {
      "tweeted": true,
      "name": null,
      "file_name": "coffee https://t.co/4tcPU9XUon",
      "media_url": "https://pbs.twimg.com/media/DJvnJf_UEAAXnzC.jpg",
      "media_category": "TWEET_IMAGE",
      "media_key": "3_908573900237180928",
      "created_at": "2017-09-15T06:11:12Z",
      "media_status": "TRANSCODE_COMPLETED",
      "media_type": "IMAGE",
      "updated_at": "2017-11-16T06:00:01Z",
      "deleted": false
    }
  ],
  "next_cursor": "c-1"
}

Recupera uno specifico oggetto della libreria multimediale associato all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste all’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
media_key obbligatorio	Un riferimento all’oggetto nella libreria multimediale con cui operi nella richiesta. Tipo: string Esempio: 13_909110614026444802

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/13_909110614026444802

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "13_909110614026444802"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 39973,
    "name": null,
    "file_name": "buildings https://t.co/xFdzrHM5QG",
    "description": null,
    "media_url": "https://video.twimg.com/amplify_video/909110614026444802/vid/1280x720/mfahmfkKVjjk1nGm.mp4",
    "media_category": "AMPLIFY_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/909110614026444802/img/QZUNoaiCia0UFNrw.jpg",
    "poster_media_key": "3_909110614026444802",
    "media_key": "13_909110614026444802",
    "created_at": "2017-09-16T17:43:55Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "edifici",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-09-27T13:04:00Z",
    "deleted": false
  }
}

Associa un oggetto multimediale all’account corrente. Per ulteriori dettagli, consulta la nostra guida alla Media Library.

Nota: quando aggiungi un video con la categoria multimediale AMPLIFY_VIDEO alla Media Library, è automaticamente disponibile come asset PREROLL di account_media.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/media_library

​

Parametri

Nome	Descrizione
account_id required	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
media_key required	Il media_key del contenuto caricato. Un media_key viene restituito nella risposta a POST media/upload quando è specificato un media_category. Type: string Example: 3_931236738554519552
description optional	La descrizione che appare sotto il video quando viene pubblicato come Tweet. Lunghezza massima: 200 caratteri. Per impostazione predefinita non viene visualizzata nel Tweet. Per mostrare la description del video, usa il parametro video_description con l’endpoint POST accounts/:account_id/tweet. Nota: può essere utilizzata solo con i video. Type: string Example: This is the description under the video.
file_name optional	Il nome file per l’oggetto della libreria multimediale. Lunghezza massima: 255. Il nome file è visibile nei dettagli dei contenuti multimediali di ogni asset nell’interfaccia Media Library su ads.x.com. Sarà vuoto quando file_name non è impostato. Type: string Example: coffee.jpeg
name optional	Il nome per l’oggetto della libreria multimediale. Lunghezza massima: 100. Questa è l’etichetta mostrata sotto ogni asset multimediale nell’interfaccia Media Library su ads.x.com. L’etichetta sarà “Untitled” quando name non è impostato. Type: string Example: Latte
poster_media_key optional	Specifica un’immagine di poster per il video usando il media_key di un’immagine caricata. Se non specificato, verrà usato il primo fotogramma. Nota: può essere utilizzata solo con i video. Type: string Example: 3_890599134483242005
title optional	Il titolo (headline) che appare sotto il video quando viene pubblicato come Tweet. Lunghezza massima: 70 caratteri. Per impostazione predefinita non viene visualizzato nel Tweet. Per mostrare il title del video, usa il parametro video_title con l’endpoint POST accounts/:account_id/tweet. Nota: può essere utilizzata solo con i video. Type: string Example: Video title

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library?media_key=3_931236738554519552

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "3_931236738554519552"
    }
  },
  "data": {
    "tweeted": false,
    "name": null,
    "file_name": null,
    "media_url": "https://pbs.twimg.com/media/DOxq4TtV4AAlvh_.jpg",
    "media_category": "TWEET_IMAGE",
    "media_key": "3_931236738554519552",
    "created_at": "2017-11-16T19:05:14Z",
    "media_status": "TRANSCODE_COMPLETED",
    "media_type": "IMAGE",
    "updated_at": "2017-11-16T19:05:23Z",
    "deleted": false
  }
}

Aggiorna l’oggetto specificato della libreria multimediale appartenente all’account corrente.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste alla Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
media_key obbligatorio	Un riferimento all’oggetto della libreria multimediale con cui operi nella richiesta. Tipo: string Esempio: 16_844800354743074820
description opzionale	La descrizione che appare sotto il video quando viene pubblicato come Tweet. Lunghezza massima: 200 caratteri. Per impostazione predefinita non viene visualizzata nel Tweet. Per mostrare la description del video, usa il parametro video_description con l’endpoint POST accounts/:account_id/tweet. Nota: può essere utilizzata solo con i video. Tipo: string Esempio: This is the description under the video.
file_name opzionale	Il nome file per l’oggetto della libreria multimediale. Lunghezza massima: 255. Il nome file è visibile nei dettagli dei media di ogni asset nell’interfaccia Media Library su ads.x.com. Questo campo sarà vuoto se file_name non è impostato. Tipo: string Esempio: coffee.jpeg
name opzionale	Il nome per l’oggetto della libreria multimediale. Lunghezza massima: 100. Questa è l’etichetta sotto ogni asset multimediale nell’interfaccia Media Library su ads.x.com. L’etichetta sarà “Untitled” se name non è impostato. Tipo: string Esempio: Latte
poster_media_key opzionale	Specifica un’immagine poster per il video usando la media_key di un’immagine caricata. Nota: può essere utilizzata solo con i video. Tipo: string Esempio: 3_885003359340375465
title opzionale	Il titolo (headline) che appare sotto il video quando viene pubblicato come Tweet. Lunghezza massima: 70 caratteri. Per impostazione predefinita non viene visualizzato nel Tweet. Per mostrare il title del video, usa il parametro video_title con l’endpoint POST accounts/:account_id/tweet. Nota: può essere utilizzata solo con i video. Tipo: string Esempio: Video title

​

Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/16_844800354743074820?title=cat GIF&description=in space

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "16_844800354743074820",
      "title": "GIF di gatto",
      "description": "nello spazio"
    }
  },
  "data": {
    "tweeted": true,
    "duration": null,
    "name": null,
    "file_name": null,
    "description": "nello spazio",
    "media_url": "https://video.twimg.com/tweet_video/C7lVclqVwAQqTCZ.mp4",
    "media_category": "TWEET_GIF",
    "poster_media_url": "https://pbs.twimg.com/tweet_video_thumb/C7lVclqVwAQqTCZ.jpg",
    "poster_media_key": "3_844800354743074820",
    "media_key": "16_844800354743074820",
    "created_at": "2017-10-20T09:51:54Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "GIF di gatto",
    "media_type": "GIF",
    "aspect_ratio": "125:79",
    "updated_at": "2017-10-23T06:37:56Z",
    "deleted": false
  }
}

Elimina l’oggetto della libreria multimediale specificato appartenente all’account corrente.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/media_library/:media_key

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account a leva. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Ads, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
media_key obbligatorio	Un riferimento all’oggetto della libreria multimediale con cui operi nella richiesta. Type: string Example: 7_860318603387600896

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/media_library/7_860318603387600896

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "media_key": "7_860318603387600896"
    }
  },
  "data": {
    "tweeted": true,
    "duration": 14330,
    "name": "mountains-on-ads.x.com",
    "file_name": "mountains.mp4",
    "description": "",
    "media_url": "https://video.twimg.com/ext_tw_video/860318603387600896/pu/vid/1280x720/xI3DbvWKxdvICsFW.mp4",
    "media_category": "TWEET_VIDEO",
    "poster_media_url": "https://pbs.twimg.com/media/C_B3bTRVYAAFBFt.jpg",
    "poster_media_key": "3_860318839740915712",
    "media_key": "7_860318603387600896",
    "created_at": "2017-05-05T02:21:53Z",
    "media_status": "TRANSCODE_COMPLETED",
    "title": "caricato su ads.x.com",
    "media_type": "VIDEO",
    "aspect_ratio": "16:9",
    "updated_at": "2017-05-05T02:26:58Z",
    "deleted": true
  }
}

​

Schede del sondaggio

Apri in Postman

​

GET accounts/:account_id/cards/poll

Recupera i dettagli di alcune o tutte le poll card associate all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Ads API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_ids opzionale	Limita la risposta alle sole poll card desiderate specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Type: string Example: 57i77
count opzionale	Specifica il numero di record da recuperare per ciascuna richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor opzionale	Specifica un cursore per ottenere la pagina successiva di risultati. Vedi Pagination per maggiori informazioni. Type: string Example: 8x7v00oow
q opzionale	Una query facoltativa per filtrare le card per name. Ommetti questo parametro per recuperarle tutte. Lunghezza massima: 80 caratteri. Nota: Esegue un confronto sul prefisso senza distinzione tra maiuscole e minuscole. Type: string Example: night
sort_by opzionale	Ordina per attributo supportato in ordine crescente o decrescente. Vedi Sorting per maggiori informazioni. Type: string Example: created_at-asc
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possibili valori: true, false
with_total_count opzionale	Includi l’attributo di risposta total_count. Nota: Questo parametro e cursor sono mutuamente esclusivi. Nota: Le richieste che includono total_count hanno limiti di velocità inferiori, attualmente pari a 200 per 15 minuti. Type: boolean Default: false Possibili valori: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?card_ids=57i77

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_ids": [
        "57i77"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "video_poster_height": "9",
      "name": "sondaggio costa migliore",
      "start_time": "2018-01-09T04:51:34Z",
      "first_choice": "Est",
      "video_height": "9",
      "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
      "content_duration_seconds": "8",
      "second_choice": "Ovest",
      "end_time": "2018-01-16T04:51:34Z",
      "id": "57i77",
      "video_width": "16",
      "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
      "created_at": "2018-01-09T04:51:34Z",
      "duration_in_minutes": "10080",
      "card_uri": "card://950590850777497601",
      "updated_at": "2018-01-09T04:51:34Z",
      "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
      "video_poster_width": "16",
      "deleted": false,
      "card_type": "VIDEO_POLLS"
    }
  ]
}

Recupera una scheda sondaggio specifica associata all’account corrente.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account con leva. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_id obbligatorio	Riferimento alla poll card utilizzata nella richiesta. Type: string Example: 57i8t
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i8t

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_type": "poll",
      "card_id": "57i8t",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "sondaggio solo testo",
    "start_time": "2018-01-09T05:03:05Z",
    "first_choice": "Mattina",
    "second_choice": "Sera",
    "end_time": "2018-01-11T05:03:05Z",
    "id": "57i8t",
    "created_at": "2018-01-09T05:03:05Z",
    "duration_in_minutes": "2880",
    "card_uri": "card://950593749658189824",
    "updated_at": "2018-01-09T05:03:05Z",
    "deleted": false,
    "card_type": "TEXT_POLLS"
  }
}

​

POST accounts/:account_id/cards/poll

Crea una nuova poll card associata all’account specificato. Questo endpoint consente di creare poll card con un’immagine, un video o senza contenuti multimediali. I sondaggi con contenuti multimediali sono denominati Media Forward Polls.

Nota: Il prodotto Media Forward Polls è in beta e richiede la funzionalità di account PROMOTED_MEDIA_POLLS.

Nota: Non è possibile aggiornare (PUT) le poll card.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/poll

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro richiesto per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
duration_in_minutes obbligatorio	Il periodo di tempo (in minuti) durante il quale il sondaggio rimarrà aperto. Trascorso il duration_in_minutes specificato, il sondaggio si chiuderà e non saranno più accettati voti. Corrisponde a end_time nella risposta. Nota: l’intervallo decorre non appena la card viene creata e non quando viene aggiunta a un Tweet. Tipo: int Min, Max: 5, 10080
first_choice obbligatorio	La prima opzione del sondaggio. Lunghezza massima: 25 caratteri. Tipo: string Esempio: One
name obbligatorio	Il nome della card. Tipo: string Esempio: poll card
second_choice obbligatorio	La seconda opzione del sondaggio. Lunghezza massima: 25 caratteri. Tipo: string Esempio: Two
fourth_choice opzionale	La quarta opzione del sondaggio. Lunghezza massima: 25 caratteri. Nota: la prima, la seconda e la terza opzione devono essere impostate quando si utilizza questo parametro. Tipo: string Esempio: Four
media_key opzionale	Il media_key di un’immagine o di un video della libreria multimediale che verrà utilizzato in questa card. Questo è un campo di sola scrittura. Nella risposta, l’API fornirà un URL di X per questo contenuto multimediale. Nota: l’immagine o il video devono essere presenti nella libreria multimediale dell’account. Nota: è richiesta una larghezza minima dell’immagine di 800 px e un rapporto larghezza:altezza di 1,91:1.
third_choice opzionale	La terza opzione del sondaggio. Lunghezza massima: 25 caratteri. Nota: la prima e la seconda opzione devono essere impostate quando si utilizza questo parametro. Tipo: string Esempio: Three

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll?duration_in_minutes=10080&first_choice=East&second_choice=West&media_key=13_950589518557540353&name=best coast poll

​

Esempio di risposta

{
  "request": {
    "params": {
      "first_choice": "East",
      "name": "sondaggio migliore costa",
      "second_choice": "West",
      "media_key": "13_950589518557540353",
      "duration_in_minutes": 10080
    }
  },
  "data": {
    "video_poster_height": "9",
    "name": "sondaggio migliore costa",
    "start_time": "2018-01-09T04:51:34Z",
    "first_choice": "Est",
    "video_height": "9",
    "video_url": "https://video.twimg.com/amplify_video/vmap/950589518557540353.vmap",
    "content_duration_seconds": "8",
    "second_choice": "Ovest",
    "end_time": "2018-01-16T04:51:34Z",
    "id": "57i77",
    "video_width": "16",
    "video_hls_url": "https://video.twimg.com/amplify_video/950589518557540353/vid/1280x720/BRkAhPxFoBREIaFA.mp4",
    "created_at": "2018-01-09T04:51:34Z",
    "duration_in_minutes": "10080",
    "card_uri": "card://950590850777497601",
    "updated_at": "2018-01-09T04:51:34Z",
    "video_poster_url": "https://pbs.twimg.com/amplify_video_thumb/950589518557540353/img/nZ1vX_MXYqmvbsXP.jpg",
    "video_poster_width": "16",
    "deleted": false,
    "card_type": "VIDEO_POLLS"
  }
}

Elimina in modo permanente la scheda del sondaggio specificata appartenente all’account corrente.

Nota: si tratta di un’eliminazione definitiva (hard delete). Di conseguenza, non è possibile recuperare le schede eliminate.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/poll/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Ads, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_id obbligatorio	Riferimento alla poll card utilizzata nella richiesta. Type: string Example: 57i9t

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/poll/57i9t

​

Esempio di risposta

{
  "data": {
    "name": "sondaggio con immagine",
    "start_time": "2018-01-09T05:10:51Z",
    "id": "57i9t",
    "created_at": "2018-01-09T05:10:51Z",
    "updated_at": "2018-01-09T05:11:04Z",
    "deleted": true,
    "card_type": "IMAGE_POLLS"
  },
  "request": {
    "params": {
      "card_id": "57i9t",
      "card_type": "poll",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Call to action preroll

Apri in Postman

​

GET accounts/:account_id/preroll_call_to_actions

Recupera i dettagli di alcune o tutte le Call-To-Action (CTA) preroll associate agli elementi della campagna dell’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
line_item_ids facoltativo	Limita la risposta alle sole CTA preroll associate ai line item specificati indicando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Tipo: string Esempio: 8v53k
count facoltativo	Specifica il numero di record da provare a recuperare per ogni singola richiesta. Tipo: int Predefinito: 200 Min, Max: 1, 1000
cursor facoltativo	Specifica un cursore per ottenere la pagina successiva dei risultati. Consulta Pagination per maggiori informazioni. Tipo: string Esempio: 8x7v00oow
preroll_call_to_action_ids facoltativo	Limita la risposta alle sole CTA preroll desiderate indicando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Tipo: string Esempio: 8f0
sort_by facoltativo	Ordina in base a un attributo supportato, in ordine crescente o decrescente. Consulta Sorting per maggiori informazioni. Tipo: string Esempio: created_at-asc
with_deleted facoltativo	Includi i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false
with_total_count facoltativo	Includi l’attributo di risposta total_count. Nota: questo parametro e cursor sono mutuamente esclusivi. Nota: le richieste che includono total_count avranno limiti di velocità più bassi, attualmente impostati a 200 per 15 minuti. Tipo: boolean Predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_ids=8v53k

​

Esempio di risposta

{
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "line_item_ids": [
        "8v53k"
      ]
    }
  },
  "next_cursor": null,
  "data": [
    {
      "line_item_id": "8v53k",
      "call_to_action_url": "https://www.x.com",
      "call_to_action": "VISIT_SITE",
      "id": "8f0",
      "created_at": "2017-07-07T19:28:40Z",
      "updated_at": "2017-07-07T19:28:40Z",
      "deleted": false
    }
  ]
}

Recupera una specifica call to action (CTA) associata a questo account.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	Identificatore dell’account in uso. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id obbligatorio	Riferimento alla call to action preroll con cui operi nella richiesta. Type: string Example: 8f0
with_deleted opzionale	Includi anche i risultati eliminati nella richiesta. Type: boolean Default: false Possible values: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

Esempio di risposta

{
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  }
}

​

POST accounts/:account_id/preroll_call_to_actions

Imposta la Call-to-Action (CTA) facoltativa per un elemento di riga PREROLL_VIEWS.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
call_to_action obbligatorio	Il testo della CTA per il pulsante mostrato nell’annuncio. Tipo: enum Valori possibili: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url obbligatorio	L’URL verso cui reindirizzare l’utente quando si fa clic sul pulsante CTA. Tipo: string Esempio: https://www.x.com
line_item_id obbligatorio	Riferimento alla voce di riga con cui stai operando nella richiesta. Tipo: string Esempio: 8v53k

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions?line_item_id=8v53k&call_to_action=VISIT_SITE&call_to_action_url=https://www.x.com

​

Esempio di risposta

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-07-07T19:28:40Z",
    "deleted": false
  },
  "request": {
    "params": {
      "line_item_id": "8v53k",
      "call_to_action": "VISIT_SITE",
      "call_to_action_url": "https://www.x.com",
      "account_id": "18ce54d4x5t"
    }
  }
}

Aggiorna la Call-to-Action (CTA) facoltativa per una riga PREROLL_VIEWS.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
preroll_call_to_action_id obbligatorio	Un riferimento alla CTA preroll utilizzata nella richiesta. Type: string Example: 8f0
call_to_action opzionale	Il testo della CTA per il pulsante visualizzato nell’annuncio. Type: enum Possible values: GO_TO, SEE_MORE, SHOP, VISIT_SITE, WATCH_NOW
call_to_action_url opzionale	L’URL a cui reindirizzare l’utente quando si fa clic sul pulsante CTA. Type: string Example: https://www.x.com

​

Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0?call_to_action=WATCH_NOW

​

Esempio di risposta

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "WATCH_NOW",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-09-09T05:51:26Z",
    "deleted": false
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "call_to_action": "WATCH_NOW",
      "account_id": "18ce54d4x5t"
    }
  }
}

Elimina la call to action (CTA) preroll specificata dell’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/preroll_call_to_actions/:preroll_call_to_action_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account leveraged. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
preroll_call_to_action_id obbligatorio	Un riferimento alla CTA preroll con cui operi nella richiesta. Tipo: string Esempio: 8f0

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/preroll_call_to_actions/8f0

​

Esempio di risposta

{
  "data": {
    "line_item_id": "8v53k",
    "call_to_action_url": "https://www.x.com",
    "call_to_action": "VISIT_SITE",
    "id": "8f0",
    "created_at": "2017-07-07T19:28:40Z",
    "updated_at": "2017-08-30T06:08:21Z",
    "deleted": true
  },
  "request": {
    "params": {
      "preroll_call_to_action_id": "8f0",
      "account_id": "18ce54d4x5t"
    }
  }
}

​

Tweet programmati

Apri in Postman

​

GET accounts/:account_id/scheduled_tweets

Recupera i dettagli di alcuni o di tutti i Tweet programmati associati all’account corrente.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, tranne GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
count opzionale	Specifica il numero di record da recuperare per ogni singola richiesta. Type: int Default: 100 Min, Max: 1, 200
cursor opzionale	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedere Pagination per ulteriori informazioni. Type: string Example: c-j3cn6n40
user_id opzionale	Specifica l’utente per cui recuperare i Tweet programmati. Se non impostato, il valore predefinito è l’utente promuovibile FULL sull’account. Type: long Example: 756201191646691328

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?count=1

​

Esempio di risposta

{
  "request": {
    "params": {
      "count": 1
    }
  },
  "data": [
    {
      "name": "nome di prova",
      "completed_at": "2017-06-18T22:00:05Z",
      "text": "dove vuoi essere",
      "user_id": "756201191646691328",
      "scheduled_status": "SUCCESS",
      "id": "875828692081037312",
      "nullcast": true,
      "created_at": "2017-06-16T21:33:27Z",
      "scheduled_at": "2017-06-18T22:00:00Z",
      "card_uri": null,
      "updated_at": "2017-06-19T18:02:20Z",
      "tweet_id": "876560168963645440",
      "media_keys": []
    }
  ],
  "next_cursor": "c-j41uw400"
}

Recupera uno specifico Tweet programmato associato all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account con leva finanziaria. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
scheduled_tweet_id obbligatorio	Un riferimento al Tweet programmato con cui si opera nella richiesta. Type: string Example: 917438609065623552

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/917438609065623552

​

Esempio di risposta

{
  "request": {
    "params": {
      "scheduled_tweet_id": "917438609065623552"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

​

POST accounts/:account_id/scheduled_tweets

Crea un Tweet programmato per l’utente completamente promozionabile dell’account (predefinito) o per l’utente specificato nel parametro as_user_id.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
scheduled_at obbligatorio	L’orario, espresso in formato ISO 8601, in cui il Tweet deve essere pubblicato (ovvero andare online). Nota: i Tweet possono essere programmati al massimo fino a un anno nel futuro. Nota: i Tweet devono essere programmati con granularità al minuto; i secondi verranno ignorati. Tipo: string Esempio: 2017-12-31T23:59:00Z
as_user_id obbligatorio	L’ID utente dell’inserzionista per conto del quale pubblichi il Tweet. L’inserzionista deve concedere al tuo handle (o ai tuoi handle) l’accesso al suo account pubblicitario tramite ads.x.com. Questa autorizzazione ti consente di chiamare l’API utilizzando i token OAuth del tuo handle anziché quelli dell’inserzionista. Tipo: long Esempio: 756201191646691328
text a volte obbligatorio	Il testo dell’aggiornamento di stato. Obbligatorio se non sono specificati media_keys. Tipo: string Esempio: just setting up my twttr
card_uri opzionale	Associa una card al Tweet utilizzando il valore card_uri restituito da qualsiasi risposta delle card, se disponibile. Tipo: string Esempio: card://855591459410511943
media_keys opzionale	Associa contenuti multimediali al Tweet specificando un elenco di identificatori separati da virgole. Includi fino a 4 immagini, 1 GIF animata o 1 video. Nota: la risorsa multimediale deve essere presente nella Media Library dell’account. Tipo: string Esempio: 13_1153584529292270722
nullcast opzionale	Indica se creare un Tweet nullcast (o “solo promozionato”). Tipo: boolean Predefinito: true Valori possibili: true, false
name opzionale	Il nome del Tweet programmato. Lunghezza massima: 80 caratteri. Tipo: string Esempio: Tweet with name

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets?as_user_id=756201191646691328&media_keys=3_917438348871983104&scheduled_at=2018-01-01

​

Esempio di risposta

{
  "request": {
    "params": {
      "media_keys": [
        "3_917438348871983104"
      ],
      "scheduled_at": "2018-01-01T00:00:00Z",
      "as_user_id": 756201191646691328
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "text": "",
    "user_id": "756201191646691328",
    "scheduled_status": "SCHEDULED",
    "id": "917438609065623552",
    "nullcast": true,
    "created_at": "2017-10-09T17:16:24Z",
    "scheduled_at": "2018-01-01T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-10-09T17:16:24Z",
    "tweet_id": null,
    "media_keys": [
      "3_917438348871983104"
    ]
  }
}

Aggiorna il Tweet programmato specificato dell’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
scheduled_tweet_id obbligatorio	Un riferimento al Scheduled Tweet a cui si fa operazione nella richiesta. Tipo: string Esempio: 870321875435442177
card_uri opzionale	Associa una card al Tweet usando il valore card_uri restituito da qualsiasi risposta delle card, se disponibile. Nota: per annullare (rimuovere), specificare il parametro senza un valore. Tipo: string Esempio: card://875146925316386347
media_keys opzionale	Associa contenuti multimediali al Tweet specificando un elenco di identificatori separati da virgole. Includere fino a 4 immagini, 1 GIF animata o 1 video. Nota: la risorsa multimediale deve trovarsi nella Media Library dell’account. Nota: per annullare (rimuovere), specificare il parametro senza un valore. Tipo: string Esempio: 13_1153584529292270722
nullcast opzionale	Indica se creare un Tweet nullcasted (ovvero “Promoted-only”). Tipo: boolean Valori possibili: true, false
scheduled_at opzionale	L’orario, espresso in formato ISO 8601, in cui il Tweet deve essere pubblicato (ovvero messo online). Tipo: string Esempio: 2017-12-31T23:59:59Z
text opzionale	Il testo dell’aggiornamento di stato. Tipo: string Esempio: just setting up my twttr
name opzionale	Il nome del Scheduled Tweet. Lunghezza massima: 80 caratteri. Tipo: string Esempio: Tweet with name

​

Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875057751231037440?text=winter solstice

​

Esempio di risposta

{
  "request": {
    "params": {
      "scheduled_tweet_id": "875057751231037440",
      "text": "solstizio d'inverno"
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "SCHEDULED",
    "text": "solstizio d'inverno",
    "user_id": "756201191646691328",
    "id": "875057751231037440",
    "nullcast": true,
    "created_at": "2017-06-14T18:30:00Z",
    "scheduled_at": "2017-12-21T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T18:30:00Z",
    "tweet_id": null,
    "media_keys": []
  }
}

Elimina in modo permanente il Tweet programmato specificato appartenente all’account corrente.

Nota: si tratta di un’eliminazione definitiva. Di conseguenza, non è possibile recuperare i Tweet programmati eliminati.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/scheduled_tweets/:scheduled_tweet_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account con leva finanziaria. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste della Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
scheduled_tweet_id obbligatorio	Un riferimento al Scheduled Tweet con cui operi nella richiesta. Tipo: string Esempio: 870321875435442177

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/scheduled_tweets/875064008595787776

​

Esempio di risposta

{
  "request": {
    "params": {
      "scheduled_tweet_id": 875064008595787776
    }
  },
  "data": {
    "name": null,
    "completed_at": null,
    "scheduled_status": "DELETED",
    "text": "ciao, mondo",
    "user_id": "756201191646691328",
    "id": "875064008595787776",
    "nullcast": true,
    "created_at": "2017-06-14T18:54:52Z",
    "scheduled_at": "2017-06-15T00:00:00Z",
    "card_uri": null,
    "updated_at": "2017-06-14T19:01:16Z",
    "tweet_id": null,
    "media_keys": []
  }
}

​

Anteprime di Tweet

Apri in Postman

​

GET accounts/:account_id/tweet_previews

Anteprima di Tweet pubblicati, pianificati o in bozza.

• Consente l’anteprima di più Tweet—fino a 200—in una singola richiesta API
• Rendering accurato e aggiornato del layout e dello stile del Tweet
• Supporta tutti i formati più recenti e i tipi di card
• Restituisce un iframe

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/tweet_previews

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account sfruttato. Appare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
tweet_ids obbligatorio	Un elenco di identificatori separati da virgola. È possibile fornire fino a 200 ID. Nota: gli ID devono corrispondere al tweet_type specificato. Ad esempio, se viene passato l’ID di un Tweet programmato e viene specificato tweet_type=PUBLISHED, non verrà restituita un’anteprima per quell’ID. Tipo: long Esempio: 1122911801354510336,1102836745790316550
tweet_type obbligatorio	Il tipo di Tweet per i tweet_ids specificati. Tipo: enum Valori possibili: DRAFT, PUBLISHED, SCHEDULED

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet_previews?tweet_ids=1122911801354510336,1102836745790316550&tweet_type=PUBLISHED

​

Esempio di risposta

{
  "request": {
    "params": {
      "tweet_ids": [
        "1122911801354510336",
        "1102836745790316550"
      ],
      "tweet_type": "PUBLISHED",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": [
    {
      "tweet_id": "1122911801354510336",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAANVYW2%2FbNhT%2BKwJf59iiZDuSgWLI0suyrUXbZBuGaiAoibbZUKRGUk7TIP99h6Jsy4mdC5CX%2BiUiz%2F0cfueQuUH2ijGLZsENKjSjlpWEwhK9VzI4qXUQpQE%2BnuF4FofBTyH8gijEKRogXqIZxlGUYpyEOJ6MJziM46kjEGM1qNhDBbl5IwSx7JszsuIlU8EVyw23DGhWN7JwPqDZnArDBqjkphb0uhUgmsoFQ7Mv4QDH%2Fw4Qk5Zbzgya3aAlNUtLF%2FD9BSjmusqV6BaNYZpUjlnJ9Zb2xFtgVY0uQCnKmjCMCxosNZu%2FytDS2trMslE2oqU5ojUf2ituLdPDQlUZCjQTwCXVXAmhrjIvzi48T3BSmuBUVbUC214x6PEsLnWSaFYLiEpBqqhtDHHZlJCZA0Sf0fsMbWz7ZTvSIUkD1WaSSFqxNdlJuFw6fceTKdQZp3g6nk5THEdJr7D3iRCU14ROPp4F74sLZuycFi7YHUMIElkVdksVCuoNhQHSOZXBWyhxwU2hBsHpCWoLtfauZKCJ1x3zmbQqcHq4XARUlgHYNSBQa2VZ0T9BvkBMG1KoRsKpO8KwqTmT5c6W4MYd%2Fm7H29xBxMWyCX5rRBDhACezyXQWJVtEtCebruAwwUne0dvYgqj53LCNVssrRr4ruUn8ginCJM1Fz%2B0V03zOexv%2BLOzqFgAI8IxJsF4oaTXPG6sg1LvauCEWUmsEBfK%2BXcjqPSHI5ZwLRnJaXC40WHXZEU4ehe0P7eXhFV0w0lauRZEHUW4cgKpFC59Ry2OykV2yavMXZ6N8MawhpIf1khabnXbzUuotrO%2BFvjeWetfYDi8YA3TE4yTGx%2BNJMgnTJJpko9cXvxefT%2BtzIpWuqBh%2BrftePBTZixvLqZTQGbYxPWjHc3tDdzCfjfAYvqbROMY9%2FYLLy8PnxEDHz6kmudIlePEoHyzEYa52KhykAlrunZ%2FtYGFz2ghLOuZD%2B3ekfDPhDnUeun4D2up%2FDTQjYti2eUhlAcG%2BvZkN9jcoJPa6dh1RukZw2zaBTdtRkB0uofVs5GAIFmxL30J9vadZO8jX3SH07ch1oz1bW4x3Yn3UK2N4DkMCYoGxzFfb6KEv137cbppqRwP%2FC6pLR%2BoafTRJpnEaHuPpDFJZKdLOerKd9f4AOqn2%2FOFwPI5DHKZpGOPpJBmnrqU6cpuouxh0hCNHOALCETdHJas1a%2B8OQy5XVMAQG6CcS8jjgsC68Y539olZKm2ZhN7eKr5BXTXOLz6ffXjnxhZkeC25AxQLAMlG32nJ%2Fjz%2F6zVOXO1cQaDypGy0b6WGwVZpnqA4GjsF7o4DcLjipV0%2BQQjGzVZobZyXT5GMSQroPR5HyRiuZfAVJWFP2ZLxxdI%2BQVHqhFZUcnv9xBSWbMUEHCDdv0k5LeualA5Bzy3HQa1dQOpKdlekR5Xuudb0EiPMs31rj3y%2Fq9KqFnx%2B7bGQje5XAhqvyEbmk%2F7FvEmrt6sPrE5Pvw2ruEl%2Bhuvtq8h5BLde17AedeT1OjXBR%2Bg4cxgG%2FWy%2FdKJBkNHqxXO0qmi9L1NDR%2BiZ9zPUwLzr2z97f%2FLujbtxt9TO%2Bg16ZPjtuEDssqny%2FcUCiWz0T56%2F%2B%2FTr6u%2FPX9Xbhf7jezdvOyxjYBygNayOI1hQ0c2I2zvu%2F7COE0H1j%2Bz%2Btx8wgHY0Pnt49aDbPs14zsglu%2B4mcatvo7xedw2w0P%2BGTsAL1pv18No9qTlqHy3Gv89w7LBJmxLeWTu8cBkom6J9xcF8bopLtonJGd6%2BaG4HAWpvDv5VJv2%2FDIKbzSYsrG7Y7e3%2FCm%2FIC8QQAAA%3D'>"
    },
    {
      "tweet_id": "1102836745790316550",
      "preview": "<iframe class='tweet-preview' src='https://ton.twimg.com/ads-manager/tweet-preview/index.html?data=H4sIAAAAAAAAAO1YbW%2FbNhD%2BK4K%2Bzo3eZdlAMQQttqZrt6FNEXRVIVASJTOhSIWkHDeB%2F%2FuOomXLb%2BuHdQWGzV8s3T13vCOPz539ZKsHjJU9t57sQmCkcJkheLWvO2y9RcJyI8udzkN%2F7ofWDy58LN%2F1ZvbEJqU99zzXT4J4GkbTmRt4cRS5WpFJJcDFCS3YVR2lmcIrvcgNWmJpLZRq5Tx1UkddFDx16mUU8Lv4UhQAV6JjhQ7LnleISjyxSyJbir70PjKBWI3t%2BSd3En2e2JgpogiW9vzJXiC5UKiG50%2BgkV%2BanNPNSyexyBoN5mwQiUHZ4JIgeHwyGbpumLjh1PcDfxZ6XpSE4wyPtXpnWEkKHcSneOLPBpcZLAEmOtk%2B1zaXF%2BqBNDXk3KSOTkY9ZEtSYp6pRdfkqXPCPdh1qQNWYPFz%2BfHls7v7y6s3dZm%2Fci9u29oeLZb1%2B7pZUv6ja%2B5SO3uOw6kZaEsKHYhSWJhQ9rB41SJWQiUe%2BR2boJY0hcJSVajAqSMVUp2EBI6rLnX6FEGnC%2BpLi3UEC644vEryaOqlz18%2FPMCp6zpebL4F1hgwKQRv7bXZ4a4ZoL5rsPE0GmErojRUNojSDTJODDBIgmMgRULX8cblBjn13UMkQCu4pZ3og16vP6%2F1dincb9e4%2FP8v4%2F9EGfeSf2UZm%2BMirOIaj2SLC03nwMlQcV480RVXdr2AZQ2hlEhdx9MYnC2RIIgp2dd3ThSgwHUSQBKgLTiDCwE1Mdqi1Gna8MQR98pzxfQXZQT61IlDdxXEcC7Rm1fsHl96H8sau%2Fer1xew2I%2FQfJ4HsCmjCP0o%2Fr4Rwo6svAQivLvqXn14mRD%2FD%2BnWuX91NkJv%2Bp1D1GWyghJJnbD56HePt%2FjXG%2FJbVd3cHsR4EBFqW0qKvjxSZ%2FWsaXH94d2bbxhdS1Nn5r17CF7cTMurt6%2Ffh7fJRRN0yRDT5wMyntioLIkOCNHM8NdQ3sDLVAetGQTLQpBWw4wANzkuS5RrAEw7MOE0nGFFHo2on3oM0UveiUK7STvXDQpkLQSunqejXFEp9wjJtgSmgGC84pTyh9SY4muDsS5LaXyBqdH0xJ8J3FKYsHhm6CjTPYTB4HZGafrIMaAftE7bblTnLGGPMGYZQw0e1NpC76X2N41iGEO9mReHcTzzAj8ZtbNjJSRlPNmXv19Zb4vrDd1q4hwvZO%2BRMWgpNxUGqveIWT%2FBuFkQWfCJ9eJyKDUT3f6xXjHFLe2HsNqCJmDBuhIMWsEV8NxomjXngoXMCt4xGIqfeSAUBDr6ngjoT8%2FmG4lZc39gX3TW645avmd5yTyK536yG9hjPXijJdQPgajGfjtVZLyqJN56VaTB2SOU4CCogacx09W4C3uJBanISGBqYd83heEcIsPMNnwiSN4pDqkeeiMyA%2F5hkiJQn5LqHnBoBHtZEYqzHBV3tYBV9e5QbW%2B7%2Fcc%2BiSENqvHhFIP2J4oeA01YLXCz%2FfZSJ68vWlZ%2Fxe%2BJgeUbuFdkSwY7%2FclcDqajPSwsBrcjCJPAg8kiidxZ4kep8%2FL6l%2BLdi%2FZ9xriAVr8Zh45W%2Bfoo9vcXyxFjwAyHJH5mHYM2Cx3ceWD2EJ5iPwy8kX9K2N35OpHQE3IkspyLEqL4Kg5e6HlU%2Fwv1rBZuy1H97H7k4gp1VGUb8Dn5gZUhE6Jvnbm6RgC0et8BGWUS78iDcQU32NCb3N797S0c2izTRLDuSWBLOxx2hzCgnq0dzMQF3ul3V32QCdz%2FzzCwg2voSLPRCdHujm%2FMxreeS0lyaBKQi4Rmu9xlD7zcmiF4S6pD%2Bxxz0Xpi6TNouOFTZv6LsJ62QnjRfXi9%2FhONbe6QHREAAA%3D%3D'>"
    }
  ]
}

​

Tweet

Apri in Postman

​

GET accounts/:account_id/tweets

Recupera i dettagli del Tweet per l’utente promuovibile principale dell’account (predefinito) o per l’utente specificato nel parametro user_id. Può trattarsi di uno qualsiasi degli utenti promuovibili dell’account.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/tweets

​

Parametri

Name	Description
account_id obbligatorio	Identificatore dell’account leveraged. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Ads, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
tweet_type obbligatorio	Il tipo di Tweet per i tweet_ids specificati. Type: enum Possible values: DRAFT, PUBLISHED, SCHEDULED
count opzionale	Specifica il numero di record da recuperare per ogni singola richiesta. Type: int Default: 200 Min, Max: 1, 1000
cursor opzionale	Specifica un cursore per ottenere la pagina successiva di risultati. Consulta Pagination per ulteriori informazioni. Type: string Example: AAAAAFhLRpQLNF-sGBSgAA
include_mentions_and_replies opzionale	Se filtrare menzioni e risposte dall’elenco dei Tweet disponibili. Type: boolean Default: false Possible values: true, false
name opzionale	Una query opzionale per limitare i Tweet in base a name. Ometti questo parametro per recuperarli tutti. Lunghezza massima: 80 caratteri. Nota: Esegue un matching per prefisso senza distinzione tra maiuscole e minuscole. Type: string Example: dtc
timeline_type opzionale	Se restituire Tweet nullcast (ovvero “solo promossi”), Tweet organici o entrambi. Type: enum Default: NULLCAST Possible values: ALL, NULLCAST, ORGANIC
trim_user opzionale	Se escludere l’oggetto utente nella risposta del Tweet. Quando abilitato, l’unica parte dell’oggetto utente restituita sarà l’user ID dell’autore del Tweet. Type: boolean Default: false Possible values: true, false
tweet_ids opzionale	Elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Nota: Gli ID devono corrispondere al tweet_type specificato. Ad esempio, se viene passato l’ID di un Tweet programmato, il tweet_type deve essere SCHEDULED affinché quel Tweet venga restituito nella risposta. Type: long Example: 1122911801354510336,1102836745790316550
user_id opzionale	Specifica l’utente a cui limitare i Tweet. Se non impostato, per impostazione predefinita verrà usato l’utente promuovibile FULL dell’account. Type: long Example: 756201191646691328

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets?tweet_ids=1166476031668015104&tweet_type=PUBLISHED&trim_user=true

​

Esempio di risposta

{
  "request": {
    "params": {
      "tweet_ids": [
        "1166476031668015104"
      ],
      "tweet_type": "PUBLISHED",
      "trim_user": true,
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "coordinates": null,
      "retweeted": false,
      "name": null,
      "source": "<a href="https://ads-api.x.com" rel="nofollow">App di Test Interno X Ads API</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        9
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "1166476031668015104",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "id": 1166476031668015104,
      "in_reply_to_status_id": null,
      "conversation_settings": "TUTTI",
      "nullcast": true,
      "created_at": "Tue Aug 27 22:22:12 +0000 2019",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "ciao, v6",
      "lang": "es",
      "contributors": [
        2417045708
      ],
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "id": 756201191646691328,
        "id_str": "756201191646691328"
      },
      "tweet_id": "1166476031668015104"
    }
  ]
}

​

POST accounts/:account_id/tweet

Crea un Tweet per l’utente completamente promuovibile dell’account (impostazione predefinita) o per l’utente specificato nel parametro as_user_id. Sono supportate sia la creazione di Tweet nullcast (predefinita) sia di Tweet organici. I Tweet nullcast non compaiono nella timeline pubblica e non vengono recapitati ai follower. Entrambi i tipi possono essere utilizzati nelle campagne.

Se l’utente autenticato non è l’utente promuovibile FULL di questo account, verifica se dispone dell’autorizzazione a pubblicare Tweet per conto di tale utente effettuando una richiesta all’endpoint GET accounts/:account_id/authenticated_user_access. Un’autorizzazione TWEET_COMPOSER indica che l’utente può utilizzare questo endpoint per creare Tweet nullcast per conto dell’utente promuovibile FULL.

Quando si utilizza l’endpoint upload.x.com per i contenuti multimediali, passa lo stesso valore di user_id per il parametro additional_owners del valore as_user_id che invii a questo endpoint.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/tweet

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Ads API per inserzionisti, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
as_user_id obbligatorio	L’ID utente dell’inserzionista per conto del quale pubblichi il Tweet. L’inserzionista deve concedere al tuo handle (o ai tuoi handle) l’accesso al suo account pubblicitario tramite ads.x.com. Questa autorizzazione ti consente di chiamare l’API utilizzando i token OAuth del tuo handle invece di quelli dell’inserzionista. Tipo: long Esempio: 756201191646691328
text a volte obbligatorio	Il testo dell’aggiornamento di stato. Obbligatorio se non vengono specificati media_keys. Tipo: string Esempio: hello, world
card_uri opzionale	Associa una card al Tweet utilizzando il valore card_uri da qualsiasi risposta delle card, se disponibile. Tipo: string Esempio: card://853503245793641682
conversation_settings opzionale	Scegli chi può rispondere a questo Tweet. Chiunque sia menzionato può sempre rispondere. Nota: questo campo non verrà restituito nella risposta alla richiesta POST, ma verrà restituito quando si effettua una richiesta GET. Nota: questo parametro funziona solo in Ads API v8 e successive. Tipo: enum Predefinito: EVERYONE Valori possibili: EVERYONE, FOLLOWING, MENTIONED_USERS
media_keys opzionale	Associa dei media al Tweet specificando un elenco di identificatori separati da virgole. Includi fino a 4 immagini, 1 GIF animata o 1 video. Tipo: string Esempio: 13_1153584529292270722
name opzionale	Il nome del Tweet. Lunghezza massima: 80 caratteri. Tipo: string Esempio: Tweet with name
nullcast opzionale	Se creare un Tweet nullcast (o “Solo promozionato”). Nota: i Tweet organici (nullcast=false) possono essere creati solo per l’utente autenticato. Tipo: boolean Predefinito: true Valori possibili: true, false
trim_user opzionale	Se escludere l’oggetto utente nella risposta del Tweet. Quando abilitato, l’unica parte dell’oggetto utente che verrà restituita è l’ID utente dell’autore del Tweet. Tipo: boolean Predefinito: false Valori possibili: true, false
tweet_mode opzionale	Se la risposta deve essere in modalità compatibility o extended. Vedi qui per ulteriori informazioni. Tipo: string Valori possibili: compat, extended
video_cta opzionale	La CTA per il video. Tipo: enum Valori possibili: VISIT_SITE, WATCH_NOW
video_cta_value opzionale	Il valore della relativa CTA sul video. Tipo: string Esempio: https://dev.x.com
video_description opzionale	La descrizione che appare sotto il video. Lunghezza massima: 200 caratteri. Tipo: string Esempio: Integra con la piattaforma pubblicitaria di X
video_title opzionale	Il titolo (headline) che appare sotto il video. Lunghezza massima: 70 caratteri. Tipo: string Esempio: X Ads API

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/tweet?text=hello, world&as_user_id=756201191646691328&trim_user=true

​

Esempio di risposta

{
  "data": {
    "created_at": "Sat Jun 24 05:08:30 +0000 2017",
    "id": 878479925472251906,
    "id_str": "878479925472251906",
    "text": "ciao, mondo",
    "name": null,
    "truncated": false,
    "entities": {
      "hashtags": [],
      "symbols": [],
      "user_mentions": [],
      "urls": []
    },
    "source": "<a href='"https://ads-api.x.com"' rel='"nofollow"'>App di Test Interno X Ads API</a>",
    "in_reply_to_status_id": null,
    "in_reply_to_status_id_str": null,
    "in_reply_to_user_id": null,
    "in_reply_to_user_id_str": null,
    "in_reply_to_screen_name": null,
    "user": {
      "id": 756201191646691328,
      "id_str": "756201191646691328"
    },
    "geo": null,
    "coordinates": null,
    "place": null,
    "contributors": null,
    "retweet_count": 0,
    "favorite_count": 0,
    "favorited": false,
    "retweeted": false,
    "scopes": {
      "followers": false
    },
    "lang": "en"
  },
  "request": {
    "params": {
      "text": "ciao, mondo",
      "trim_user": true,
      "as_user_id": 756201191646691328,
      "account_id": "18ce54d4x5t"
    }
  }
}

Aggiorna il campo name del Tweet specificato appartenente all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/tweets/:tweet_id/name

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Advertiser API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
tweet_id obbligatorio	Un riferimento al Tweet con cui operi nella richiesta. Type: long Example: 994747471329873920
name opzionale	Il nome del Tweet. Lunghezza massima: 80 caratteri. Type: string Example: Tweet with name

​

Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/tweets/994747471329873920/name?name=new Tweet name

​

Esempio di risposta

{
  "request": {
    "params": {
      "tweet_id": 994747471329873920,
      "name": "nuovo nome Tweet",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
      "coordinates": null,
      "retweeted": false,
      "name": "nuovo nome Tweet",
      "conversation_settings": "EVERYONE",
      "source": "<a href="https://ads-api.x.com" rel="nofollow">App di Test Interno X Ads API</a>",
      "entities": {
        "hashtags": [],
        "symbols": [],
        "user_mentions": [],
        "urls": []
      },
      "display_text_range": [
        0,
        5
      ],
      "favorite_count": 0,
      "in_reply_to_status_id_str": null,
      "geo": null,
      "id_str": "994747471329873920",
      "scopes": {
        "followers": false
      },
      "in_reply_to_user_id": null,
      "truncated": false,
      "retweet_count": 0,
      "scheduled_status": null,
      "id": 994747471329873920,
      "in_reply_to_status_id": null,
      "nullcast": true,
      "created_at": "Wed Jan 01 00:00:00 +0000 2020",
      "place": null,
      "scheduled_at": null,
      "tweet_type": "PUBLISHED",
      "favorited": false,
      "full_text": "ciao",
      "lang": "en",
      "contributors": null,
      "in_reply_to_screen_name": null,
      "in_reply_to_user_id_str": null,
      "user": {
        "utc_offset": null,
        "name": "Tushar Bhushan",
        "friends_count": 1065,
        "screen_name": "imit8me",
        "location": "San Francisco, CA",
        "protected": false,
        "url": "https://tushdante.github.io",
        "profile_image_url": "http://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_background_color": "C0DEED",
        "profile_use_background_image": true,
        "is_translator": false,
        "geo_enabled": true,
        "description": "Open Source Developer / Partner Engineer @twitter / Viaggiatore dello Spazio | Ex evangelista @sendgrid @keen_io",
        "profile_link_color": "1DA1F2",
        "id_str": "3271358660",
        "listed_count": 31,
        "default_profile_image": false,
        "followers_count": 407,
        "profile_image_url_https": "https://pbs.twimg.com/profile_images/618551153131786241/g-MIydXB_normal.jpg",
        "profile_sidebar_border_color": "C0DEED",
        "profile_background_image_url": "http://abs.twimg.com/images/themes/theme1/bg.png",
        "favourites_count": 5993,
        "following": null,
        "default_profile": true,
        "withheld_in_countries": [],
        "id": 3271358660,
        "profile_background_tile": false,
        "contributors_enabled": false,
        "follow_request_sent": null,
        "created_at": "Tue Jul 07 22:34:58 +0000 2015",
        "profile_sidebar_fill_color": "DDEEF6",
        "translator_type": "regular",
        "lang": null,
        "profile_text_color": "333333",
        "notifications": null,
        "verified": false,
        "time_zone": null,
        "profile_banner_url": "https://pbs.twimg.com/profile_banners/3271358660/1474853576",
        "statuses_count": 500,
        "profile_background_image_url_https": "https://abs.twimg.com/images/themes/theme1/bg.png",
        "is_translation_enabled": false
      },
      "tweet_id": "994747471329873920"
    }
}

​

Video Conversation Cards

Apri in Postman

Nota: Per associare una card a un Tweet, usa il parametro card_uri con uno degli endpoint POST accounts/:account_id/tweet, POST statuses/update o POST accounts/:account_id/scheduled_tweets.

​

GET accounts/:account_id/cards/video_conversation

Recupera i dettagli di una parte o di tutte le video conversation cards associate all’account corrente.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation

​

Parametri

Nome	Descrizione
account_id required	L’identificatore dell’account in uso. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
card_ids optional	Limita la risposta alle sole video conversation cards desiderate specificando un elenco di identificatori separati da virgole. È possibile fornire fino a 200 ID. Tipo: string Esempio: 5a86h
count optional	Specifica il numero di record da recuperare per ciascuna richiesta. Tipo: int Predefinito: 200 Min, Max: 1, 1000
cursor optional	Specifica un cursore per ottenere la pagina successiva dei risultati. Vedere Pagination per maggiori informazioni. Tipo: string Esempio: 8x7v00oow
q optional	Una query opzionale per filtrare le card per name. Omettere questo parametro per recuperare tutto. Lunghezza massima: 80 caratteri. Nota: esegue un confronto per prefisso senza distinzione tra maiuscole e minuscole. Tipo: string Esempio: night sky
sort_by optional	Ordina in base a un attributo supportato in ordine crescente o decrescente. Vedere Sorting per maggiori informazioni. Tipo: string Esempio: created_at-asc
with_deleted optional	Includi i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false
with_total_count optional	Includi l’attributo di risposta total_count. Nota: questo parametro e cursor si escludono a vicenda. Nota: le richieste che includono total_count avranno limiti di velocità inferiori, attualmente 200 ogni 15 minuti. Tipo: boolean Predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?card_ids=5a86h

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_ids": [
        "5a86h"
      ],
      "account_id": "18ce54d4x5t"
    }
  },
  "next_cursor": null,
  "data": [
    {
      "name": "scheda conversazione video",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Crealo",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "id": "5a86h",
      "video_width": "16",
      "first_cta_tweet": "Ads API",
      "created_at": "2018-01-30T17:53:04Z",
      "card_uri": "card://958397665015775232",
      "title": "Sviluppatori",
      "updated_at": "2018-01-30T17:53:04Z",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "deleted": false,
      "card_type": "VIDEO_CONVERSATION"
    }
  ]
}

Recupera una specifica scheda di conversazione video associata all’account in uso.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è in genere un parametro obbligatorio per tutte le richieste dell’API Ads, tranne per GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
card_id obbligatorio	Un riferimento alla video conversation card utilizzata nella richiesta. Tipo: string Esempio: 4i0ya
with_deleted opzionale	Includi i risultati eliminati nella richiesta. Tipo: boolean Predefinito: false Valori possibili: true, false

​

Esempio di richiesta

GET https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h

​

Esempio di risposta

{
  "request": {
    "params": {
      "card_type": "video_conversation",
      "card_id": "5a86h",
      "account_id": "18ce54d4x5t"
    }
  },
  "data": {
    "name": "scheda conversazione video",
    "first_cta": "#API",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Crealo",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "X Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Sviluppatori",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  }
}

​

POST accounts/:account_id/cards/video_conversation

Crea una nuova card di conversazione video associata all’account specificato.

Consulta Uploading Media per informazioni utili sul caricamento di immagini sui nostri endpoint.

​

URL della risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Appare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’API Advertiser, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
first_cta obbligatorio	L’hashtag Call-To-Action (CTA) per la prima opzione. Lunghezza massima: 20 caratteri (escluso il #). Tipo: string Esempio: #APIs
first_cta_tweet obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la prima CTA. Tipo: string Esempio: Ads API
media_key obbligatorio	La chiave media per un video da utilizzare in questa scheda. Nota: Il video deve trovarsi nella Media Library dell’account. Nota: È richiesto un rapporto di aspetto di 16:9. Tipo: string Esempio: 13_1168079965037467209
name obbligatorio	Il nome della scheda. Tipo: string Esempio: video conversation card
thank_you_text obbligatorio	Il testo da visualizzare dopo aver selezionato la CTA. Lunghezza massima: 23 caratteri. Tipo: string Esempio: Build it
title talvolta obbligatorio	Il titolo della scheda, che appare sotto il video e sopra le CTA. Lunghezza massima: 23 caratteri. Tipo: string Nota: Obbligatorio se second_cta non è impostato. Esempio: Developers
second_cta talvolta obbligatorio	L’hashtag Call-To-Action (CTA) per la seconda opzione. Lunghezza massima: 20 caratteri (escluso il #). Tipo: string Nota: Obbligatorio se title non è impostato. Esempio: #ShareAgain
second_cta_tweet talvolta obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la seconda CTA. Nota: Obbligatorio se second_cta è impostato. Tipo: string Esempio: I Heart @AdsAPI Again
poster_media_key opzionale	La chiave media per un’immagine poster da utilizzare in questa scheda. Se non specificata, verrà utilizzato il primo frame. Nota: Il video deve trovarsi nella Media Library dell’account. Tipo: long Esempio: 3_882726458191298561
third_cta opzionale	L’hashtag Call-To-Action (CTA) per la terza opzione. Lunghezza massima: 20 caratteri (escluso il #). Tipo: string Esempio: #ShareMore
third_cta_tweet talvolta obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la terza CTA. Tipo: string Nota: Obbligatorio se third_cta è impostato. Esempio: I Heart @TwitterDev
fourth_cta opzionale	L’hashtag Call-To-Action (CTA) per la quarta opzione. Lunghezza massima: 20 caratteri (escluso il #). Tipo: string Esempio: #ShareExtra
fourth_cta_tweet talvolta obbligatorio	Il testo del Tweet da utilizzare quando viene selezionata la quarta CTA. Tipo: string Nota: Obbligatorio se fourth_cta è impostato. Esempio: I Heart @TwitterDev Again
thank_you_url opzionale	L’URL da visualizzare insieme al testo di ringraziamento. Tipo: string Esempio: https://example.com/thankyou
unlocked_image_media_key opzionale	Un media_key di un’immagine che verrà utilizzata nello scenario di sblocco istantaneo. Questo è un campo di sola scrittura. Nella risposta, l’API fornirà un URL X per questa immagine. Nota: L’immagine deve trovarsi nella media library dell’account. Tipo: string Esempio: 3_883112887618682880
unlocked_video_media_key opzionale	L’identificatore di un video dall’endpoint GET accounts/:account_id/media_library che verrà utilizzato nello scenario di sblocco istantaneo. Tipo: string Esempio: 13_867520357225418752

​

Esempio di richiesta

POST https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation?first_cta=#APIs&first_cta_tweet=X Ads API&name=video conversation card&thank_you_text=Build it&title=Sviluppatori&media_key=13_958388276489895936

​

Esempio di risposta

{
  "data": {
    "name": "scheda conversazione video",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Crealo",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "X Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Sviluppatori",
    "updated_at": "2018-01-30T17:53:04Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "video_poster_height": "9",
      "name": "scheda conversazione video",
      "first_cta": "#APIs",
      "video_height": "9",
      "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
      "thank_you_text": "Crealo",
      "video_owner_id": "756201191646691328",
      "media_key": "13_958388276489895936",
      "account_id": "18ce54d4x5t",
      "video_width": "16",
      "first_cta_tweet": "X Ads API",
      "title": "Sviluppatori",
      "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
      "video_poster_width": "16",
      "card_type": "VIDEO_CONVERSATION"
    }
  }
}

Aggiorna la video conversation card specificata appartenente all’account corrente.

Consulta Uploading Media per informazioni utili sul caricamento delle immagini sui nostri endpoint.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore per l’account utilizzato. Appare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste API Advertiser escluso GET accounts. L’account specificato deve essere associato all’utente autenticato. Tipo: string Esempio: 18ce54d4x5t
card_id obbligatorio	Un riferimento alla scheda di conversazione video con cui stai operando nella richiesta. Tipo: string Esempio: 5a86h
first_cta opzionale	L’hashtag Call-To-Action (CTA) per la prima opzione. Lunghezza massima: 20 caratteri (senza contare il #). Tipo: string Esempio: #APIs
first_cta_tweet opzionale	Il testo del Tweet da utilizzare quando viene cliccata la prima CTA. Tipo: string Esempio: X Ads API
second_cta opzionale	L’hashtag Call-To-Action (CTA) per la seconda opzione. Lunghezza massima: 20 caratteri (senza contare il #). Tipo: string Nota: Obbligatorio se title non è impostato. Esempio: #ShareAgain
second_cta_tweet opzionale	Il testo del Tweet da utilizzare quando viene cliccata la seconda CTA. Nota: Obbligatorio se second_cta è impostato. Tipo: string Esempio: I Heart @AdsAPI Again
third_cta opzionale	L’hashtag Call-To-Action (CTA) per la terza opzione. Lunghezza massima: 20 caratteri (senza contare il #). Tipo: string Esempio: #ShareMore
third_cta_tweet opzionale	Il testo del Tweet da utilizzare quando viene cliccata la terza CTA. Tipo: string Nota: Obbligatorio se third_cta è impostato. Esempio: I Heart @TwitterDev
fourth_cta opzionale	L’hashtag Call-To-Action (CTA) per la quarta opzione. Lunghezza massima: 20 caratteri (senza contare il #). Tipo: string Esempio: #ShareExtra
fourth_cta_tweet opzionale	Il testo del Tweet da utilizzare quando viene cliccata la quarta CTA. Tipo: string Nota: Obbligatorio se fourth_cta è impostato. Esempio: I Heart @TwitterDev Again
media_key opzionale	La chiave media per un video da utilizzare in questa scheda. Nota: Il video deve essere nella Libreria Media dell’account. Nota: È richiesto un rapporto di aspetto di 16:9. Tipo: string Esempio: 13_1168079965037467209
name opzionale	Il nome per la scheda. Tipo: string Esempio: scheda sviluppatori
poster_media_key opzionale	La chiave media per un’immagine poster da utilizzare in questa scheda. Se non specificata, verrà utilizzato il primo frame. Nota: Il video deve essere nella Libreria Media dell’account. Tipo: long Esempio: 3_882726458191298561
thank_you_text opzionale	Il testo da visualizzare dopo che la CTA è stata cliccata. Lunghezza massima: 23 caratteri. Tipo: string Esempio: Costruiscilo
thank_you_url opzionale	L’URL da visualizzare con il testo di ringraziamento. Tipo: string Esempio: https://example.com/thankyou
title opzionale	Il titolo per la scheda, che appare sotto il video e sopra le CTA. Lunghezza massima: 23 caratteri. Tipo: string Nota: Obbligatorio se second_cta non è impostato. Esempio: Inizia una conversazione
unlocked_image_media_key opzionale	Un media_key di un’immagine che verrà utilizzata nello scenario di sblocco istantaneo. Questo è un campo di sola scrittura. Nella risposta, l’API fornirà un URL X per questa immagine. Nota: L’immagine deve essere nella libreria media dell’account. Tipo: string Esempio: 3_883112887618682880
unlocked_video_media_key opzionale	L’identificatore di un video dall’endpoint GET accounts/:account_id/media_library che verrà utilizzato nello scenario di sblocco istantaneo. Tipo: string Esempio: 13_867520357225418752

​

Esempio di richiesta

PUT https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/5a86h?name=developers card

​

Esempio di risposta

{
  "data": {
    "name": "scheda sviluppatori",
    "first_cta": "#APIs",
    "video_height": "9",
    "media_url": "https://video.twimg.com/amplify_video/vmap/958388276489895936.vmap",
    "thank_you_text": "Crealo",
    "video_owner_id": "756201191646691328",
    "media_key": "13_958388276489895936",
    "id": "5a86h",
    "video_width": "16",
    "first_cta_tweet": "Ads API",
    "created_at": "2018-01-30T17:53:04Z",
    "card_uri": "card://958397665015775232",
    "title": "Sviluppatori",
    "updated_at": "2018-01-30T18:02:15Z",
    "poster_media_url": "https://pbs.twimg.com/amplify_video_thumb/958388276489895936/img/W-OL5rZ_MZ19A7Pa.jpg",
    "deleted": false,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "account_id": "18ce54d4x5t",
      "card_type": "VIDEO_CONVERSATION",
      "card_id": "5a86h",
      "name": "scheda sviluppatori"
    }
  }
}

Elimina in modo permanente la scheda di conversazione video specificata appartenente all’account corrente.

Nota: Si tratta di un’eliminazione definitiva. Di conseguenza, non è possibile recuperare le schede eliminate.

​

URL risorsa

https://ads-api.x.com/12/accounts/:account_id/cards/video_conversation/:card_id

​

Parametri

Nome	Descrizione
account_id obbligatorio	L’identificatore dell’account utilizzato. Compare nel percorso della risorsa ed è generalmente un parametro obbligatorio per tutte le richieste dell’Ads API, ad eccezione di GET accounts. L’account specificato deve essere associato all’utente autenticato. Type: string Example: 18ce54d4x5t
card_id obbligatorio	Un riferimento alla video conversation card con cui operi nella richiesta. Type: string Example: 4i0ya

​

Esempio di richiesta

DELETE https://ads-api.x.com/12/accounts/18ce54d4x5t/cards/video_conversation/4i0ya

​

Esempio di risposta

{
  "data": {
    "name": "card conversazione video",
    "id": "4i0ya",
    "created_at": "2017-07-07T01:36:39Z",
    "updated_at": "2017-08-23T13:29:13Z",
    "deleted": true,
    "card_type": "VIDEO_CONVERSATION"
  },
  "request": {
    "params": {
      "card_id": "4i0ya",
      "card_type": "video_conversation",
      "account_id": "18ce54d4x5t"
    }
  }
}