Questo endpoint è stato aggiornato per includere i metadata di modifica dei Post. Scopri di più su questi metadata nella pagina dei fondamenti “Modifica dei Post”. Questo endpoint è spesso utilizzato insieme agli endpoint dei Messaggi Diretti. Abbiamo rilasciato i nuovi endpoint dei Messaggi Diretti v2. Nota che le Account Activity API Enterprise e Premium supportano i messaggi one-to-one v2, ma non supportano ancora le conversazioni di gruppo. Enterprise
L’Account Activity API consente di sottoscrivere attività in tempo reale relative a un account utente tramite webhook. Ciò significa che puoi ricevere in tempo reale Post, Messaggi Diretti e altri eventi dell’account da uno o più account di tua proprietà o sottoscritti attraverso un’unica connessione.
Riceverai tutte le attività elencate di seguito per ogni sottoscrizione utente nella tua registrazione webhook:
| Tipi di attività | |
|---|
* Post (dell’utente)
* Eliminazioni di Post (dell’utente)
* @menzioni (dell’utente)
* Risposte (all’utente o da parte dell’utente)
* Retweet (dell’utente o relativi all’utente)
* Quote Tweet (dell’utente o relativi all’utente)
* Retweet di Quote Tweet (dell’utente o relativi all’utente)
* Like (dell’utente o relativi all’utente)
* Segui (dell’utente o relativi all’utente)
* Smetti di seguire (dell’utente) | * Blocchi (dell’utente)
* Sblocchi (dell’utente)
* Silenziamenti (dell’utente)
* Annullamenti del silenziamento (dell’utente)
* Messaggi Diretti inviati (dell’utente)
* Messaggi Diretti ricevuti (dell’utente)
* Indicatori di digitazione (verso l’utente)
* Conferme di lettura (verso l’utente)
* Revoche della sottoscrizione (dell’utente) |
Nota bene - Non forniamo i dati della home timeline tramite l’Account Activity API. Usa GET statuses/home_timeline per recuperare questi dati.
Dai un’occhiata alla nostra serie di quattro video sulla Account Activity API per metterti al passo!
Riepilogo delle funzionalità
-
Hai domande? Riscontri errori?
-
Esplora gli esempi di codice:
Gestire i webhook e gli utenti iscritti
Iniziamo registrando un nuovo URL del webhook per il contesto dell’applicazione specificato.L’URL verrà verificato tramite una richiesta CRC prima del salvataggio. Dopo aver registrato un webhook, assicurati di annotarne l’id, poiché ti servirà in seguito.Copia la seguente richiesta cURL nel tuo terminale dopo aver sostituito i segnaposto di seguito:
-
URL
<URL> ad es. https://yourdomain.com/webhooks/twitter/
-
Consumer key
<CONSUMER_KEY> ad es. xvz1evFS4wEEPTGEFPHBog
-
Access token
<ACCESS_TOKEN> ad es. 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
curl --request POST --url 'https://api.x.com/1.1/account_activity/webhooks.json?url=<URL>' --header 'authorization: OAuth oauth_consumer_key="<CONSUMER_KEY>", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="<ACCESS_TOKEN>", oauth_version="1.0"'
Gestione degli utenti iscritti:
Per iniziare, iscriviamo un utente così riceverai tutti i tipi di evento.Copia il seguente comando cURL nel tuo terminale dopo aver aggiornato i seguenti valori:
-
Webhook ID
<:WEBHOOK_ID> ad es. 1234567890
-
Nome della consumer key
<CONSUMER_KEY> ad es. xvz1evFS4wEEPTGEFPHBog
-
Access token dell’utente che si iscrive
<SUBSCRIBING_USER'S_ACCESS_TOKEN> ad es. 370773112-GmHxMAgYyLbNEtIKZeRNFsMKPR9EyMZeS9weJAEb
curl --request POST --url https://api.x.com/1.1/account_activity/webhooks/<:WEBHOOK_ID>/subscriptions/all.json --header 'authorization: OAuth oauth_consumer_key="<CONSUMER_KEY>", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="<SUBSCRIBING_USER'S_ACCESS_TOKEN>", oauth_version="1.0"'
Panoramica video dell’Account Activity API
In questa panoramica video scoprirai le funzionalità dei livelli premium ed Enterprise dell’Account Activity API.
Al termine del video, avrai imparato a:
- Registrare un webhook
- Aggiungere una sottoscrizione utente
- Rimuovere una sottoscrizione utente
- Ricevere le attività dell’account
- Riprodurre le attività dell’account
-
Hai domande? Riscontri degli errori?
-
Esplora i nostri esempi di codice:
Enterprise
L’Account Activity API è un’API basata su webhook che invia eventi dell’account a una web app che sviluppi, distribuisci e ospiti.
Prima di poter iniziare a ricevere eventi webhook nella tua applicazione di consumo degli eventi, ci sono diversi dettagli di “infrastruttura” a cui prestare attenzione. Come descritto di seguito, dovrai creare una X App, ottenere l’accesso all’Account Activity API e sviluppare una web app che elabori gli eventi webhook.
- Crea una X app con un account sviluppatore approvato dal developer portal. Se stai creando l’App per conto della tua azienda, è consigliabile crearla con un account X aziendale. Per richiedere un account sviluppatore, fai clic qui.
- Abilita “Read, Write and Access direct messages” nella scheda permissions della pagina della tua App.
- Nella scheda “Keys and Access Tokens”, annota il Consumer Key (API Key) e il Consumer Token (API Secret) della tua App.
- Nella stessa scheda, genera gli Access Token and Access Token Secret della tua App. Avrai bisogno di questi Access Tokens per registrare l’URL del tuo webhook, dove X invierà gli eventi dell’account.
- Se non conosci X Sign-in e come funzionano i contesti utente con la X API, consulta Obtaining Access Tokens. Quando aggiungi gli account per i quali desideri ricevere eventi, li sottoscriverai utilizzando gli access token di quell’account.
- Prendi nota dell’id numerico della tua App, come visualizzato nella pagina “Apps” del developer portal. Quando richiedi l’accesso all’Account Activity API, avrai bisogno di questo id della tua App.
2. Ottenere l’accesso all’Account Activity API
3. Sviluppare l’app consumer del webhook
Una volta ottenuto l’accesso all’Account Activity API, devi sviluppare, distribuire e ospitare un’app web che riceva gli eventi webhook di X.
-
Crea un’app web con un URL da utilizzare come webhook per ricevere gli eventi. Questo è l’endpoint distribuito sul tuo server che ascolta gli eventi webhook di X in arrivo.
-
Come descritto nella nostra guida Securing Webhooks, il primo passo è scrivere codice che riceva una richiesta GET di X Challenge Response Check (CRC) e risponda con un JSON correttamente formattato.
-
Registra l’URL del tuo webhook. Eseguirai una richiesta POST all’endpoint /webhooks.json?url=. Quando effettui questa richiesta, X invierà una richiesta CRC alla tua app web. Quando un webhook viene registrato correttamente, la risposta includerà un webhook id. Questo webhook id sarà necessario più avanti per alcune richieste all’Account Activity API.
-
X invierà gli eventi webhook dell’account all’URL che hai registrato. Assicurati che la tua app web supporti le richieste POST per gli eventi in arrivo. Questi eventi saranno codificati in JSON. Vedi QUI per esempi di payload JSON dei webhook.
-
Una volta che la tua app web è pronta, il passo successivo è aggiungere gli account per cui ricevere le attività. Quando aggiungi (o elimini) account, effettuerai richieste POST facendo riferimento all’account id. Consulta la nostra guida sull’aggiunta delle sottoscrizioni per ulteriori informazioni.
4. Convalidare la configurazione
- Per verificare che la tua App e il webhook siano configurati correttamente, metti Mi piace a un Post pubblicato da uno degli account X a cui la tua App è iscritta. Dovresti ricevere un
favorite_events tramite una richiesta POST all’URL del tuo webhook per ogni Preferito ricevuto dai tuoi iscritti.
- Nota che potrebbero essere necessari fino a 10 secondi prima che la consegna degli eventi inizi dopo l’aggiunta di un’iscrizione.
Note importanti
-
Quando registri l’URL del tuo webhook, la tua web app deve autenticarsi con il proprio consumer token e secret e anche con l’access token e il secret dell’utente proprietario dell’App.
-
Tutti i Messaggi Diretti in arrivo saranno recapitati tramite webhook. Tutti i Messaggi Diretti inviati tramite POST direct_messages/events/new (message_create) saranno anch’essi recapitati tramite webhook. Questo consente alla tua web app di conoscere i Messaggi Diretti inviati tramite un client diverso.
-
Nota che ogni evento del webhook include un user ID for_user_id che indica per quale iscrizione è stato recapitato l’evento.
-
Se due utenti utilizzano la tua web app per i Messaggi Diretti nella stessa conversazione, il tuo webhook riceverà due eventi duplicati (uno per ciascun utente). La tua web app dovrebbe tenere conto di questo.
-
Se hai più di una web app che condivide lo stesso URL del webhook e lo stesso utente mappato a ciascuna app, lo stesso evento verrà inviato più volte al tuo webhook (una volta per web app).
-
In alcuni casi, il tuo webhook potrebbe ricevere eventi duplicati. La tua web app dovrebbe tollerarlo e deduplicare in base all’ID dell’evento.
-
Non aspettarti che una risposta Quick Reply segua direttamente una richiesta. Un utente può ignorare una richiesta Quick Reply e rispondere tramite un Messaggio Diretto tradizionale. L’utente può anche inviare una risposta Quick Reply a una richiesta a cui non aveva risposto in precedenza nel thread dei messaggi.
-
Vedi codice di esempio:
-
Enterprise Account Activity API dashboard, una web app Node che mostra gli eventi del webhook utilizzando il livello Enterprise della Account Activity API e include la funzionalità di Replay.
-
Il chatbot SnowBot, una web app Ruby basata sulle API Account Activity e Messaggi Diretti. Questa codebase include uno script per aiutare a configurare i webhook della Account Activity API.
Le API di X basate su webhook offrono due metodi per verificare la sicurezza del tuo server webhook:
- I controlli di challenge-response consentono a X di confermare la titolarità della web app che riceve gli eventi del webhook.
- L’intestazione della firma in ogni richiesta POST ti consente di verificare che X sia l’origine dei webhook in arrivo.
Verifiche Challenge-Response
Per verificare che tu sia il proprietario sia dell’App sia dell’URL del webhook, X eseguirà una Challenge-Response Check (CRC), da non confondere con un controllo di ridondanza ciclica. Quando viene inviata una CRC, X effettuerà una richiesta GET alla tua web app con un parametro crc_token. Quando tale richiesta viene ricevuta, la tua web app deve creare un response_token cifrato basato sul parametro crc_token e sul Consumer Secret della tua App (dettagli di seguito). Il response_token deve essere codificato in JSON (vedi esempio sotto) e restituito entro tre secondi. In caso di esito positivo, verrà restituito l’id del webhook.
Una CRC verrà inviata quando registri l’URL del tuo webhook, quindi implementare il codice di risposta alla CRC è un primo passo fondamentale. Una volta stabilito il tuo webhook, X attiverà una CRC all’incirca ogni 24 ore dall’ultima volta in cui abbiamo ricevuto una risposta positiva. La tua App può anche attivare una CRC, quando necessario, effettuando una richiesta PUT con l’id del webhook. Attivare una CRC è utile durante lo sviluppo dell’applicazione webhook, dopo aver distribuito nuovo codice e riavviato il servizio.
Il crc_token dovrebbe cambiare per ogni richiesta CRC in arrivo e va usato come messaggio nel calcolo, dove il tuo Consumer Secret è la chiave.
Se la risposta non viene restituita entro 3 secondi o diventa non valida, l’invio degli eventi al webhook registrato verrà interrotto.
La richiesta CRC si verificherà:
- Quando viene registrato un URL di webhook.
- Approssimativamente con cadenza oraria per convalidare l’URL del webhook.
- Puoi attivare manualmente un CRC effettuando una richiesta PUT. Durante lo sviluppo del client del webhook, prevedi di attivare manualmente il CRC mentre sviluppi la relativa risposta.
Requisiti della risposta:
- Un hash HMAC SHA-256 codificato in base64, generato a partire dal
crc_token e dal Consumer Secret della tua App
response_token valido e formato JSON.- Latenza inferiore a 3 secondi.
- Codice di risposta HTTP 200.
Librerie HMAC specifiche per lingua:
Esempio di generazione del token di risposta in Python:
import base64
import hashlib
import hmac
import json
\# Definisce una route per la richiesta GET
@app.route('/webhooks/twitter', methods=\['GET'\])
def webhook_challenge():
# crea un hash HMAC SHA-256 dal token in ingresso e dal tuo consumer secret
sha256\_hash\_digest = hmac.new(TWITTER\_CONSUMER\_SECRET, msg=request.args.get('crc_token'), digestmod=hashlib.sha256).digest()
# costruisce i dati di risposta con hash codificato in base64
response = {
'response\_token': 'sha256=' + base64.b64encode(sha256\_hash_digest)
}
# restituisce una risposta JSON formattata correttamente
return json.dumps(response)
Esempio di risposta JSON:
{
"response_token": "sha256=x0mYd8hz2goCTfcNAaMqENy2BFgJJfJOb4PdvTffpwg="
}
- QUI trovi un esempio di metodo di risposta CRC scritto in Node/JS.
- QUI trovi un esempio di metodo di risposta CRC scritto in Ruby (vedi generate_crc_response e la route /GET che riceve gli eventi CRC).
Quando si riceve una richiesta POST da X, si invia una richiesta GET per creare un webhook o si invia una richiesta GET per eseguire un CRC manuale, nell’intestazione sarà presente una firma hash come x-twitter-webhooks-signature. Questa firma può essere usata per verificare che l’origine dei data sia X. La firma hash del POST inizia con sha256=, a indicare l’uso di HMAC SHA-256 per firmare il tuo X App Consumer Secret e il payload. L’hash del GET è calcolato dalla stringa del parametro query crc_token=token&nonce=nonce.
Passaggi per convalidare una richiesta
- Crea un hash utilizzando il tuo consumer secret e il body del payload in ingresso.
- Confronta l’hash creato con il valore x-twitter-webhooks-signature codificato in base64. Usa un metodo come compare_digest per ridurre la vulnerabilità ad attacchi di timing.
Linee guida di sicurezza aggiuntive
Blocchi di rete aggregati di X
-
199.59.148.0/22
-
199.16.156.0/22
-
192.133.77.0/26
-
64.63.15.0/24
-
64.63.31.0/24
-
64.63.47.0/24
-
202.160.128.0/24
-
202.160.129.0/24
-
202.160.130.0/24
Configurazioni del server consigliate
- Valutazione “A” nel test di ssllabs.com
- Abilitare TLS 1.2
- Abilitare Forward Secrecy
- Disattivare SSLv2
- Disattivare SSLv3 (a causa di POODLE)
- Disattivare TLS 1.0
- Disattivare TLS 1.1
- Disattivare la compressione TLS
- Disattivare i session ticket, a meno che non si eseguano rotazioni delle relative chiavi.
- Impostare l’opzione “ssl_prefer_server_ciphers” o “SSLHonorCipherOrder” nella configurazione SSL su “on”.
- Assicurarsi che l’elenco dei cifrari sia aggiornato, ad esempio:
ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES128-SHA256:AES128-SHA:AES256-GCM-SHA384:AES256-SHA256:AES256-SHA:ECDHE-RSA-DES-CBC3-SHA:DES-CBC3-SHA
Gestione di webhook e sottoscrizioni
Creazione e modifica dei webhook
Endpoint di gestione della configurazione dei webhook:
Perché non posso semplicemente aggiornare l’URL del webhook?
Perché le configurazioni dei webhook sono immutabili? X prende la sicurezza molto sul serio. Se l’URL del tuo webhook viene modificato, esiste la possibilità che la consumer key e la consumer secret della tua App siano state compromesse. Richiedendo la creazione di una nuova configurazione del webhook, ti viene anche chiesto di iscriverti nuovamente agli eventi dei tuoi utenti. Questo richiede l’uso di access token che è meno probabile che un soggetto malintenzionato possieda. Di conseguenza, si riduce la probabilità che un’altra parte riceva informazioni private dei tuoi utenti.
Aggiungere e rimuovere le sottoscrizioni utente
Endpoint per la gestione delle sottoscrizioni
Nota: X deve abilitare l’accesso all’Account Activity API per la tua App sviluppatore prima che tu possa iniziare a usare l’API. A tal fine, assicurati di condividere l’id dell’App che intendi usare per l’autenticazione con il tuo account manager o con il team di supporto tecnico.
- Consumer Keys (API Key e Secret)
- Access Tokens (Access Token e Secret)
Nel caso dei tre endpoint seguenti, esegui azioni di scrittura nel contesto della tua applicazione (nessun utente X è coinvolto). Pertanto, gli Access Tokens da fornire sono quelli appartenenti alla tua App sviluppatore. Possono essere generati direttamente dal developer portal, nella scheda “Keys and tokens” della tua App.
D’altra parte, per i tre endpoint seguenti stai effettuando una richiesta che consente alla tua applicazione di accedere a dati protetti per conto di un utente di X (ad esempio, Messaggi Diretti). Devi quindi fornire gli Access Tokens appartenenti all’utente sottoscrittore in questione. Gli Access Tokens richiesti possono essere ottenuti utilizzando il flusso OAuth a 3 vie (vedi OAuth 1.0a: how to obtain a user’s Access Tokens). Questi endpoint sono contrassegnati con un asterisco nella tabella sopra (*).
Nota bene: Assicurati che la tua App sviluppatore sia abilitata per “Read, Write, and Direct Messages.” Puoi modificare questa impostazione nella sezione Projects & Apps del tuo account sviluppatore, sotto “App permissions” per l’App sviluppatore selezionata. Dovrai rigenerare le credenziali della tua App dopo aver modificato le impostazioni delle autorizzazioni. Nota bene: X deve abilitare l’accesso all’Account Activity API per la tua App sviluppatore prima che tu possa iniziare a utilizzare l’API. A tal fine, assicurati di condividere l’App id che intendi utilizzare per scopi di autenticazione con il tuo account manager o il team di supporto tecnico.
- Consumer Keys (API Key e Secret)
- Access Tokens (Access Token e Secret)
Per i tre endpoint seguenti esegui azioni di scrittura nel contesto della tua applicazione (non sono coinvolti utenti X). Pertanto, gli Access Tokens che devi fornire sono quelli appartenenti alla tua App sviluppatore. Puoi generarli direttamente dal developer portal, nella scheda “Keys and tokens” della tua App.
Nel caso dei tre endpoint seguenti, effettui una richiesta che consente alla tua applicazione di accedere a dati protetti per conto di un utente di X (ad esempio, Messaggi Diretti). Devi quindi fornire gli Access Tokens appartenenti all’utente sottoscrittore in questione. Gli Access Tokens necessari possono essere ottenuti utilizzando il flusso OAuth a 3 vie (vedi OAuth 1.0a: how to obtain a user’s Access Tokens). Questi endpoint sono contrassegnati con un asterisco nella tabella sopra (*).
Nota: Assicurati che la tua App sviluppatore sia abilitata per “Read, Write, and Direct Messages.” Puoi modificare questa impostazione nella sezione Projects & Apps del tuo account sviluppatore, in “App permissions” per l’App sviluppatore selezionata. Dopo aver modificato le autorizzazioni, dovrai rigenerare le credenziali della tua App. Enterprise
Uno dei vantaggi del livello Enterprise della Account Activity API è un meccanismo di ritentativo per gli eventi webhook. Se non viene ricevuto un codice di risposta HTTP 200 “success”, il server di X avvierà un meccanismo di ritentativo, reinviando l’evento webhook fino a tre volte nell’arco di cinque minuti. Questo servizio di ritentativo degli eventi webhook contribuisce a garantire l’affidabilità e il recupero degli eventi quando si verificano problemi di rete e durante interruzioni del servizio lato client e deployment.
Che cosa sono i tentativi di ritrasmissione?
|
|---|
| Attività creata, POST all’URL del webhook dall’Account Activity API, con timeout dopo tre secondi. |
| Attendere tre secondi dopo il timeout precedente, quindi POST all’URL del webhook dall’Account Activity API, con timeout dopo tre secondi. |
| Attendere 27 secondi dopo il timeout precedente, quindi POST all’URL del webhook dall’Account Activity API, con timeout dopo tre secondi. |
| Attendere 242 secondi dopo il timeout precedente, quindi POST all’URL del webhook dall’Account Activity API, con timeout dopo tre secondi. |
| Dopo questo, l’Account Activity API interromperà i tentativi di POST. Il client deve utilizzare altri endpoint di X per recuperare i data. |
Struttura dell’oggetto dei dati di Account Activity
| Oggetto | Dettagli |
|---|
| for_user_id | Identifica l’utente (abbonamento) a cui è correlato l’evento. |
| is_blocked_by | (condizionale) Mostrato solo quando un altro utente menziona l’utente abbonato. Incluso se true solo per gli eventi di menzione del Post. |
| source | L’utente che esegue l’attività. Ad esempio, l’utente che segue, blocca o silenzia è l’utente di origine. |
| target | L’utente a cui si applica l’attività. Ad esempio, l’utente che viene seguito, bloccato o silenziato è l’utente di destinazione. |
Attività disponibili
| Tipo di messaggio | Dettagli |
|---|
| tweet_create_events | Payload di stato del Post quando una delle seguenti azioni viene eseguita dall’utente dell’abbonamento o nei suoi confronti: Post, Retweet, risposte, @menzioni, Quote Tweets, Retweet di Quote Tweets. |
| favorite_events | Stato dell’evento Preferito (like) con l’utente e il destinatario. |
| follow_events | Evento di follow con l’utente e il destinatario. |
| unfollow_events | Evento di unfollow con l’utente e il destinatario. |
| block_events | Evento di blocco con l’utente e il destinatario. |
| unblock_events | Evento di sblocco con l’utente e il destinatario. |
| mute_events | Evento di silenziamento con l’utente e il destinatario. |
| unmute_events | Evento di riattivazione del silenziamento con l’utente e il destinatario. |
| user_event | Eventi di revoca inviati quando un utente rimuove l’autorizzazione dell’applicazione e l’abbonamento viene eliminato automaticamente. |
| direct_message_events | Stato del messaggio diretto con l’utente e il destinatario quando un messaggio diretto viene inviato o ricevuto. |
| direct_message_indicate_typing_events | Evento di digitazione del messaggio diretto con l’utente e il destinatario. |
| direct_message_mark_read_events | Evento di lettura del messaggio diretto con l’utente e il destinatario. |
| tweet_delete_events | Notifica di Post eliminati per semplificare il mantenimento della conformità. |
Esempi di payload
Consulta gli esempi di payload riportati di seguito per ciascun evento di Account Activity descritto nella tabella sopra.
{
"for_user_id": "2244994945",
"tweet_create_events": [
{
<Oggetto Tweet>
}
]
}
{
"for_user_id": "2244994945",
"user_has_blocked": "false",
"tweet_create_events": [
{
<Oggetto Tweet>
}
]
}
eventi_preferiti
{
"for_user_id": "2244994945",
"favorite_events": [{
"id": "a7ba59eab0bfcba386f7acedac279542",
"created_at": "Mon Mar 26 16:33:26 +0000 2018",
"timestamp_ms": 1522082006140,
"favorited_status": {
<Oggetto Tweet>
},
"user": {
<Oggetto User>
}
}]
}
follow_events
{
"for_user_id": "2244994945",
"follow_events": [{
"type": "follow",
"created_timestamp": "1517588749178",
"target": {
<Oggetto utente >
},
"source": {
< Oggetto utente >
}
]
}
}
eventi_unfollow
{
"for_user_id": "2244994945",
"follow_events": [{
"type": "unfollow",
"created_timestamp": "1517588749178",
"target": {
<Oggetto utente >
},
"source": {
< Oggetto utente >
}
]
}
}
block_events
{
"for_user_id": "2244994945",
"block_events": [{
"type": "block",
"created_timestamp": "1518127020304",
"source": {
<Oggetto utente>
},
"target": {
<Oggetto utente>
}
}]
}
unblock_events
{
"for_user_id": "2244994945",
"block_events": [{
"type": "unblock",
"created_timestamp": "1518127020304",
"source": {
<Oggetto utente>
},
"target": {
<Oggetto utente>
}
}]
}
mute_events
{
"for_user_id": "2244994945",
"mute_events": [
{
"type": "mute",
"created_timestamp": "1518127020304",
"source": {
<Oggetto utente>
},
"target": {
<Oggetto utente>
}
}
]
}
eventi_riattivazione
{
"for_user_id": "2244994945",
"mute_events": [
{
"type": "unmute",
"created_timestamp": "1518127020304",
"source": {
<Oggetto utente>
},
"target": {
<Oggetto utente>
}
}
]
}
user_event
{
"user_event": {
"revoke": {
"date_time": "2018-05-24T09:48:12+00:00",
"target": {
"app_id": "13090192"
},
"source": {
"user_id": "63046977"
}
}
}
}
direct_message_events
{
"for_user_id": "4337869213",
"direct_message_events": [{
"type": "message_create",
"id": "954491830116155396",
"created_timestamp": "1516403560557",
"message_create": {
"target": {
"recipient_id": "4337869213"
},
"sender_id": "3001969357",
"source_app_id": "13090192",
"message_data": {
"text": "Ciao Mondo!",
"entities": {
"hashtags": [],
"symbols": [],
"user_mentions": [],
"urls": []
}
}
}
}],
"apps": {
"13090192": {
"id": "13090192",
"name": "FuriousCamperTestApp1",
"url": "https://x.com/furiouscamper"
},
"users": {},
"3001969357": {
"id": "3001969357",
"created_timestamp": "1422556069340",
"name": "Jordan Brinks",
"screen_name": "furiouscamper",
"location": "Boulder, CO",
"description": "Alter Ego - X PE le opinioni sono mie",
"url": "https://t.co/SnxaA15ZuY",
"protected": false,
"verified": false,
"followers_count": 22,
"friends_count": 45,
"statuses_count": 494,
"profile_image_url": "null",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
},
"4337869213": {
"id": "4337869213",
"created_timestamp": "1448312972328",
"name": "Harrison Test",
"screen_name": "Harris_0ff",
"location": "Burlington, MA",
"protected": false,
"verified": false,
"followers_count": 8,
"friends_count": 8,
"profile_image_url": "null",
"statuses_count": 240,
"profile_image_url_https": "https://abs.twimg.com/sticky/default_profile_images/default_profile_normal.png"
}
}
}
direct_message_indicate_typing_events
{
"for_user_id": "4337869213",
"direct_message_indicate_typing_events": [{
"created_timestamp": "1518127183443",
"sender_id": "3284025577",
"target": {
"recipient_id": "3001969357"
}
}],
"users": {
"3001969357": {
"id": "3001969357",
"created_timestamp": "1422556069340",
"name": "Jordan Brinks",
"screen_name": "furiouscamper",
"location": "Boulder, CO",
"description": "Alter Ego - X PE le opinioni sono personali",
"url": "https://t.co/SnxaA15ZuY",
"protected": false,
"verified": false,
"followers_count": 23,
"friends_count": 47,
"statuses_count": 509,
"profile_image_url": "null",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
},
"3284025577": {
"id": "3284025577",
"created_timestamp": "1437281176085",
"name": "Bogus Bogart",
"screen_name": "bogusbogart",
"protected": true,
"verified": false,
"followers_count": 1,
"friends_count": 4,
"statuses_count": 35,
"profile_image_url": "null",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/763383202857779200/ndvZ96mE_normal.jpg"
}
}
}
direct_message_mark_read_events
{
"for_user_id": "4337869213",
"direct_message_mark_read_events": [{
"created_timestamp": "1518452444662",
"sender_id": "199566737",
"target": {
"recipient_id": "3001969357"
},
"last_read_event_id": "963085315333238788"
}],
"users": {
"199566737": {
"id": "199566737",
"created_timestamp": "1286429788000",
"name": "Le Braat",
"screen_name": "LeBraat",
"location": "Denver, CO",
"description": "dati di giorno @X, design al crepuscolo",
"protected": false,
"verified": false,
"followers_count": 299,
"friends_count": 336,
"statuses_count": 752,
"profile_image_url": "null",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/936652894371119105/YHEozVAg_normal.jpg"
},
"3001969357": {
"id": "3001969357",
"created_timestamp": "1422556069340",
"name": "Jordan Brinks",
"screen_name": "furiouscamper",
"location": "Boulder, CO",
"description": "Alter Ego - X PE le opinioni sono personali",
"url": "https://t.co/SnxaA15ZuY",
"protected": false,
"verified": false,
"followers_count": 23,
"friends_count": 48,
"statuses_count": 510,
"profile_image_url": "null",
"profile_image_url_https": "https://pbs.twimg.com/profile_images/851526626785480705/cW4WTi7C_normal.jpg"
}
}
}
{
"for_user_id": "930524282358325248",
"tweet_delete_events": [
{
"status": {
"id": "1045405559317569537",
"user_id": "930524282358325248"
},
"timestamp_ms": "1432228155593"
}
]
}
API di Replay dell’attività dell’account
Enterprise
L’API di Replay dell’attività dell’account è uno strumento di ripristino dei dati che consente di recuperare eventi fino a cinque giorni nel passato. Va utilizzata per recuperare i dati quando il tuo server webhook perde eventi, sia a causa di disconnessioni più lunghe della finestra di retry, sia in scenari di disaster recovery in cui servono alcuni giorni per riportare il sistema alla normalità.
L’API di Replay dell’attività dell’account è stata progettata per qualsiasi scenario in cui non riesci a acquisire le attività per un certo periodo. Recapita le attività allo stesso webhook utilizzato per la consegna in tempo reale originale. Questo prodotto è uno strumento di ripristino e non di backfill, il che significa che gli eventi verranno riprodotti solo se ne è stato tentato un invio in precedenza. L’API di Replay dell’attività dell’account non può recapitare eventi relativi a un periodo precedente alla data di creazione di una sottoscrizione.
Utilizzo di Account Activity Replay API
Disponibilità e tipi di dati
Introduzione alla migrazione
- User Streams
- Site Streams
- GET direct_messages
- GET direct_messages/sent
- GET direct_messages/show
- POST direct_messages/new
- POST direct_messages/destroy
Abbiamo nuovi endpoint e servizi che offrono un accesso analogo e, per i Messaggi Diretti, funzionalità aggiuntive:
Per aiutarti a eseguire una migrazione senza intoppi verso questi nuovi endpoint e servizi, mettiamo a disposizione due guide alla migrazione:
Inoltre, abbiamo una serie di video sull’Account Activity API e su come iniziare.
Infine, forniamo esempi di codice per approfondire la comprensione e aiutarti a iniziare rapidamente:
- L’Account Activity Dashboard è una web app Node.js di esempio con script di supporto per iniziare a usare l’Account Activity API.
- SnowBot è un chatbot di esempio che utilizza l’Account Activity API e gli endpoint REST dei Messaggi Diretti. È scritto in Ruby, usa il framework web Sinatra ed è distribuito su Heroku.
Guida alla migrazione: passare da User Streams/Site Streams ad Account Activity API
Riepilogo delle modifiche
Differenze e considerazioni per la migrazione
Gestione delle sottoscrizioni utente
Segui i passaggi seguenti per migrare facilmente dalla Site Streams API all’Account Activity API
- Numero di webhook necessari
- Abbonamenti/utenti autorizzati attuali e previsti gestiti dalla tua applicazione
- Numero attuale di applicazioni client X
- Il livello di supporto che preferisci da X (supporto tramite forum o supporto Enterprise gestito 1:1)
- Prezzo di ciascun pacchetto
Passaggio 2: Verifica la configurazione della tua X App nel developer portal
La X App attualmente utilizzata per User Streams o Site Streams sarà elencata per l’utente proprietario all’interno del developer portal. Questa X App può essere usata anche per l’Account Activity API per mantenere gli utenti autorizzati per quella applicazione. È possibile anche creare una nuova App e, se lo desideri, far ri-autorizzare gli utenti per questa nuova App. Se stai creando una nuova App per conto di un’azienda, è consigliabile crearla con un account X @handle aziendale.
- Abilita “Read, Write and Access direct messages” nella scheda permissions della pagina della tua X App.
*Nota che la modifica di queste impostazioni non è retroattiva: gli eventuali utenti autorizzati manterranno le impostazioni di autorizzazione dal momento in cui sono stati autorizzati. Se un utente non ti ha già concesso l’accesso in lettura, scrittura e ai Messaggi Diretti, dovrai far ri-autorizzare la tua applicazione da quell’utente.
- Se non conosci X Sign-in e come funzionano i contesti utente con la X API, consulta Obtaining Access Tokens.
- Genera gli access token per il proprietario della X App in fondo alla scheda “Keys and Tokens”. Nella stessa scheda prendi nota di Consumer Key, Consumer Secret, Access Token e Access Token Secret. Ti serviranno per usare l’API.
- Genera un Bearer Token usando la tua Consumer Key e Consumer Secret per i metodi API application-only.
Passaggio 3: Configura i tuoi webhook
-
Crea una web app con un endpoint da utilizzare come webhook per ricevere eventi (ad es. https://your_domain.com/webhook/twitter o https://webhooks.your_domain.com).
-
Usa la tua Consumer Key, Consumer Secret, Access Token e Access Token Secret quando crei il webhook. Nota che il tuo endpoint deve restituire una risposta JSON con un response_token, che è un hash HMAC SHA-256 codificato in base64 creato dal crc_token e dal Consumer Secret della tua App.
-
Consulta la documentazione Securing Webhooks prestando particolare attenzione ai requisiti del Challenge Response Check (CRC).
-
Assicurati che il tuo webhook supporti richieste POST per gli eventi in ingresso e richieste GET per il CRC.
-
Assicurati che il tuo webhook abbia bassa latenza (<3 secondi per rispondere alle richieste POST)
Passaggio 4: Convalida la configurazione del tuo webhook
- Le Webhook API metteranno in sicurezza i tuoi webhook in due modi:
- Richiedere challenge response check per convalidare che il proprietario del webhook sia il proprietario della web app.
- Un’intestazione di firma in ogni richiesta POST per permettere alla tua web app di convalidare la fonte.
- Per verificare che tu sia il proprietario sia della web app sia dell’URL del webhook, X eseguirà un Challenge Response Check (CRC), da non confondere con un controllo di ridondanza ciclica.
- Una richiesta GET con un parametro denominato crc_token verrà inviata all’URL del tuo webhook. Il tuo endpoint deve restituire una risposta JSON con un response_token, che è un hash HMAC SHA-256 codificato in base64 creato dal crc_token e dal Consumer Secret della tua App.
- È previsto che il crc_token cambi per ogni richiesta CRC in arrivo. Il crc_token deve essere usato come messaggio nel calcolo, dove la tua Consumer Secret è la chiave.
- Nel caso in cui la risposta sia non valida, gli eventi smetteranno di essere inviati al webhook registrato.
Passaggio 5: Crea le sottoscrizioni per ciascun utente autorizzato di User Streams o Site Streams
Conversione all’Account Activity API da User Streams:
- Genera un elenco delle sottoscrizioni utente correnti su User Streams
- Configura le nuove sottoscrizioni all’Account Activity API usando la richiesta: POST account_activity/all/:env_name/subscriptions
- Conferma le sottoscrizioni all’Account Activity API usando la richiesta: _GET account_activity/all/:env_name/subscriptions/list
_
Conversione all’Account Activity API da Site Streams (utilizzando i control stream):
- Genera un elenco delle sottoscrizioni correnti su Site Streams usando la richiesta: GET /1.1/site/c/:stream_id/info.json
- Configura le nuove sottoscrizioni all’Account Activity API usando la richiesta: POST account_activity/all/:env_name/subscriptions
- Conferma le sottoscrizioni all’Account Activity API usando la richiesta: _GET account_activity/all/:env_name/subscriptions/list
_
Registrazione di un webhook e creazione di sottoscrizioni (non in migrazione da Site Streams o User Streams)
La dashboard di Account Activity (applicazione di esempio per Account Activity API)
- Scarica l’applicazione di esempio Account Activity Dashboard qui (usa Node.js)
- Segui le istruzioni nel README per installare e avviare l’app
- Una volta avviata l’applicazione, puoi usare l’interfaccia utente per configurare facilmente il tuo webhook e creare una nuova sottoscrizione
Tipi di messaggi dello stream deprecati
| |
|---|
| Righe vuote | Le righe vuote non saranno più inviate nell’Account Activity API, poiché venivano usate come messaggi di keep-alive in User Streams e Site Streams. |
| Avvisi di limite | Gli avvisi di limite non saranno più inviati a un webhook specifico. In alternativa, gli utenti possono chiamare l’API per ottenere l’utilizzo corrente degli handle disponibili. Questa informazione verrà aggiunta al developer portal in futuro. |
| Messaggi di disconnessione | Gli avvisi di disconnessione non saranno più necessari, poiché i webhook non dipendono da una connessione attiva. |
| Avvisi di stallo | Gli avvisi di stallo non saranno più necessari, poiché i webhook non dipendono da una connessione attiva in grado di gestire un elevato volume di messaggi in arrivo. |
| Friends list | Le Friends list non saranno più inviate proattivamente. Sarà disponibile un endpoint REST per ottenere queste informazioni. |
| | | | |
|---|
| Descrizione | Nome evento | Origine | Destinazione | Oggetto destinazione |
| L’utente elimina un Post | delete | Utente corrente | Utente corrente | Post |
| Un utente seguito elimina un Post | delete | Utente seguito | Utente seguito | Post |
| L’utente rimuove il “mi piace” da un Post | unfavorite | Utente corrente | Autore del Post | Post |
| Al Post dell’utente viene rimosso il “mi piace” | unfavorite | Utente che rimuove il “mi piace” | Utente corrente | Post |
| L’utente smette di seguire qualcuno | unfollow | Utente corrente | Utente seguito | Null |
| L’utente crea una List | list_created | Utente corrente | Utente corrente | List |
| L’utente elimina una List | list_destroyed | Utente corrente | Utente corrente | List |
| L’utente modifica una List | list_updated | Utente corrente | Utente corrente | List |
| L’utente aggiunge qualcuno a una List | list_member_added | Utente corrente | Utente aggiunto | List |
| L’utente viene aggiunto a una List | list_member_added | Utente che aggiunge | Utente corrente | List |
| L’utente rimuove qualcuno da una List | list_member_removed | Utente corrente | Utente rimosso | List |
| L’utente viene rimosso da una List | list_member_removed | Utente che rimuove | Utente corrente | List |
| L’utente si iscrive a una List | list_user_subscribed | Utente corrente | Proprietario della List | List |
| La List dell’utente riceve una nuova iscrizione | list_user_subscribed | Utente che si iscrive | Utente corrente | List |
| L’utente annulla l’iscrizione a una List | list_user_unsubscribed | Utente corrente | Proprietario della List | List |
| L’iscrizione alla List dell’utente viene annullata | list_user_unsubscribed | Utente che annulla l’iscrizione | Utente corrente | List |
| L’utente aggiorna il proprio profilo | user_update | Utente corrente | Utente corrente | Null |
| L’utente aggiorna lo stato protetto | user_update | Utente corrente | Utente corrente | Null |
Guida alla migrazione dei Messaggi Diretti
Riepilogo delle modifiche
- Supporto per allegati multimediali (immagini, GIF e video).
- Possibilità di proporre agli utenti risposte strutturate con un elenco di opzioni predefinite.
- Fino a 30 giorni di accesso ai Messaggi Diretti precedenti.
Per l’elenco completo delle nuove funzionalità dei Messaggi Diretti e dei nuovi endpoint dell’API, consulta la documentazione tecnica.
Differenze e considerazioni per la migrazione
Nuovo oggetto Messaggio Diretto
{
"type": "message_create",
"id": "1234858592",
"created_timestamp": "1392078023603",
"initiated_via": {
"tweet_id": "123456",
"welcome_message_id": "456789"
},
"message_create": {
"target": {
"recipient_id": "1234858592"
},
"sender_id": "3805104374",
"source_app_id": "268278",
"message_data": {
"text": "Blue Bird",
"entities": {
"hashtags": [],
"symbols": [],
"urls": [],
"user_mentions": [],
},
"quick_reply_response": {
"type": "options",
"metadata": "external_id_2"
},
"attachment": {
"type": "media",
"media": {
...
}
}
}
}
- Struttura dell’oggetto Direct Message completamente nuova.
- Oggetto utente semplificato.
- Nuove informazioni disponibili (risposte tramite quick reply, allegati, ecc.).
Invio di Messaggi Diretti
twurl -A 'Content-type: application/json' -X POST /1.1/direct\_messages/events/new.json -d '{"event": {"type": "message\_create", "message\_create": {"target": {"recipient\_id": "4534871"}, "message_data": {"text": "Hello World!"}}}}'
- Il messaggio è definito nel body della richiesta POST in formato JSON
- L’intestazione Content-Type deve essere impostata su application/json
- Il body JSON non è incluso nella generazione della firma OAuth.
Recupero dei Messaggi Diretti
- I messaggi inviati e ricevuti sono ora restituiti dallo stesso endpoint.
- Fino a 30 giorni di messaggi restituiti.
- Paginazione basata su cursore.
- Accesso in tempo reale ai Messaggi diretti tramite webhook.
Eliminazione dei Messaggi Diretti
- L’eliminazione di un Messaggio Diretto richiede l’id.
- Il nuovo endpoint richiede una richiesta DELETE.
- Il modo in cui i Messaggi Diretti eliminati vengono visualizzati nei client ufficiali di X rimane invariato.
Domande sulla migrazione ai nuovi endpoint dei Messaggi Diretti?
Pubblica la tua domanda nel forum della community degli sviluppatori su devcommunity.com.
Quali sono i vantaggi dell’utilizzo della Account Activity API?
La Account Activity API utilizza i webhook, il che significa che, a differenza delle streaming API, non richiediamo che tu mantenga una connessione aperta per inviarci informazioni. I webhook sono anche diversi dalle REST API perché non devi interrogarci centinaia di volte ogni 15 minuti per ottenere i dati che ti interessano. Questo aumenta l’efficienza tra un utente e la tua App, poiché consegna i dati nel momento in cui si verificano.
La Account Activity API offre numerosi vantaggi:
- Velocità: consegniamo i dati alla velocità di X.
- Semplicità: consegniamo tutti gli eventi di un account tramite un’unica connessione webhook. Le attività fornite nell’API includono Post, @mention, risposte, Retweet, Quote Tweets, Retweet di Quote Tweets, like, Messaggi Diretti inviati, Messaggi Diretti ricevuti, follow, blocchi, silenziamenti.
- Scalabilità: ricevi tutte le attività per un account che gestisci senza essere limitato da alcun limite di velocità o soglie di eventi.
La Account Activity API è disponibile come sandbox Premium, Premium a pagamento e offerta Enterprise, così puoi scalare man mano che richiedi più account per funzionalità di responsabilità o funzionalità aggiuntive.
Per iniziare, scarica snippet di Esempio di codice da GitHub.
Come posso identificare quale livello di prodotto è migliore per me?
Leggi la nostra pagina Account Activity API Overview per saperne di più sulle differenze tra le opzioni Premium e l’opzione Enterprise.
Qual è la differenza tra un ambiente Premium e un webhook Enterprise?
Non c’è alcuna differenza. Ogni ambiente Premium avrà il proprio webhook_id.
Ho bisogno di un ambiente di sviluppo, staging e produzione per la Account Activity API, è possibile?
Sì! Con i livelli a pagamento della Account Activity API (Premium a pagamento ed Enterprise), è possibile registrare più URL di webhook e gestire separatamente le sottoscrizioni per ciascuno tramite i metodi dell’API. Inoltre, più client App possono essere aggiunte a una allowlist per mantenere l’autorizzazione per i tuoi users attualmente autorizzati.
Avete guide passo‑passo su come configurare la Account Activity API?
In effetti, sì!
-
Se stai iniziando, ti consigliamo di visitare la nostra guida Getting started with webhooks
-
Segui i nostri script supportati da X Dev:
- Account Activity API dashboard, una web app Node che visualizza gli eventi dei webhook.
- Il SnowBot chatbot, una web app Ruby basata sulle Account Activity e Direct Message APIs. Questa codebase include uno script per aiutare a configurare i webhook della Account Activity API.
Esiste un modo per recuperare i dati se il nostro sistema è inattivo per un periodo di tempo?
Con i livelli a pagamento della Account Activity API (Premium a pagamento ed Enterprise), il nostro sistema ritenterà di inviarti le attività più volte nell’arco di quattro ore. Se il tuo sistema non risponde entro quel periodo di quattro ore, l’attività andrà persa e dovrai utilizzare altri endpoint REST per recuperare i dati entro 7 giorni.
Suggeriamo di utilizzare i diversi webhook, o ambienti, come strumento di ridondanza, come la Account Activity Replay API, per assicurarti di non perdere alcuna attività se uno dei tuoi sistemi va giù.
Quale autenticazione devo usare con la Account Activity API?
I metodi di autorizzazione richiesti per la Account Activity API sono descritti per metodo nelle pagine di riferimento dell’API. Se stai appena iniziando con l’autenticazione di X, ti consigliamo di leggere questa sezione.
Che cos’è un controllo challenge-response (CRC)?
Il controllo della risposta alla challenge della Account Activity API è una funzione di sicurezza pensata per garantire che le attività della Account Activity API vengano inviate allo sviluppatore corretto. Può anche essere utilizzata dagli sviluppatori per assicurarsi che i dati ricevuti provengano da X. X invierà automaticamente un CRC all’URL del tuo webhook una volta ogni 24 ore, a partire dall’ultima volta in cui l’URL del webhook è stato convalidato. Il tuo sistema deve rispondere con una risposta valida entro 3 secondi per restare convalidato.
Visita la nostra pagina Securing webhooks per maggiori dettagli.
C’è qualcosa che invaliderebbe immediatamente l’URL del mio webhook?
Se si verifica una delle seguenti condizioni, contrassegneremo immediatamente il tuo webhook come non valido:
- Il server risponde a un CRC con un token errato. In questo caso, il nostro sistema non ritenterà di inviarti l’attività.
- L’URL del webhook ha un certificato configurato in modo errato. In questo caso, il nostro sistema non ritenterà di inviarti l’attività.
- Il tuo server restituisce un codice di risposta non 2XX, non 4XXX, non 5XXX.
- Specifichi l’uso di gzip senza effettivamente inviarlo.
- Non specifichi l’uso di gzip, ma lo invii effettivamente nella risposta.
Riceverò attività duplicate se sono iscritto a utenti che interagiscono tra loro?
Sì. Se la tua web app ha sottoscrizioni attive per l’Utente A e l’Utente B, e l’Utente A menziona l’Utente B in un Post, verranno inviate due attività POST al webhook registrato. Ciascuna attività avrà un indicatore “for_user_id” per mostrare a quale sottoscrizione appartiene l’attività.
Quando creo una sottoscrizione al mio webhook, posso sostituire la parte /all/ del seguente endpoint con altri oggetti di dati dell’attività account per limitare le attività che l’API consegna?POST https://api.x.com/1.1/account_activity/all/:env_name/subscriptions.json
No, non è possibile. Allo stato attuale, è disponibile solo il prodotto /all/.
Esiste un modo per utilizzare la Account Activity API senza richiedere le autorizzazioni per i Messaggi Diretti agli utenti?
Al momento, le autorizzazioni per i Messaggi Diretti sono necessarie perché non c’è modo di filtrare le attività dei Messaggi Diretti per questa API.
Esiste una versione gratuita della Account Activity API?
Sì, offriamo la versione sandbox come livello gratuito. La nostra opzione sandbox è limitata a un singolo webhook con un massimo di 15 sottoscrizioni. Puoi leggere di più sull’opzione sandbox nella nostra documentazione.
È possibile utilizzare la Account Activity API per ottenere Retweet di Post che menzionano utenti sottoscritti?
Purtroppo, questo non rientra tra le attività fornite da questa API. Per questo, suggeriamo di utilizzare la Streaming API.
Quali sono i possibili tipi di attività rappresentati da un tweet_create_event?
Verrà inviato un payload tweet_create_event:
Se l’utente sottoscritto esegue una delle seguenti azioni:
- Crea un Post
- Effettua un Retweet
- Risponde a un Post
Se un altro utente:
- @menziona* l’utente sottoscritto
- Cita un Tweet creato dall’utente sottoscritto
*Nota: La Account Activity API consegna eventi solo quando l’utente sottoscritto riceverebbe una notifica da X e potrebbe vedere l’evento pubblicamente. Questo significa che, se l’account menzionato (@userA) segue l’account protetto (@userB), allora UserA riceverà una notifica che UserB lo ha menzionato. Se UserA non segue UserB (ed è approvato da UserB) UserA non riceverà una notifica e, pertanto, un tweet_create_event non verrebbe inviato tramite AAA se @userA avesse una sottoscrizione.
Se un utente bloccato menziona il mio utente sottoscritto, come posso identificarlo?
Vedrai un campo booleano user_has_blocked al livello superiore della risposta JSON, impostato su “true” o “false”. Questo campo sarà esposto solo sulle menzioni dei Post.
Enterprise
Come posso aggiungere la mia app a una allowlist o verificare se la mia app è già nella allowlist?
Per gestire le X apps che hai aggiunto a un’allowlist per l’accesso tramite le Enterprise API, contatta il tuo account manager indicando l’id della tua app. Puoi trovare l’id della tua app aprendo la pagina “Apps” nel developer portal.
Se ho accesso a tre webhook, posso usare tre webhook per ciascuna delle app che ho registrato per uso Enterprise?
Il limite dei webhook è impostato a livello di account, non di app. Se hai accesso a tre webhook e due app registrate per uso Enterprise, puoi usare due webhook su un’app e il terzo sull’altra, ma non tre su ciascuna app.
Posso specificare quali tipi di eventi verranno riconsegnati usando l’Account Activity Replay API?
I tipi di eventi da riprodurre non possono essere specificati. Tutti gli eventi consegnati durante l’intervallo di data e ora indicato verranno riprodotti.
Sono previsti dei tentativi di nuovo invio se la mia applicazione non riesce a elaborare un evento dell’Account Activity Replay API?
No, non sono previsti nuovi tentativi. Se un’applicazione non riesce a elaborare un evento inviato dall’Account Activity Replay API, è possibile inviare un altro job di Replay per lo stesso periodo di tempo per tentare la riconsegna di eventuali eventi di Replay mancati.
Cosa dovrei fare quando ricevo un evento di completamento con esito parziale?
Consigliamo di annotare i timestamp degli eventi ricevuti e di richiedere un altro job di Replay per gli eventi mancati.
Quanti job dell’Account Activity Replay API posso eseguire contemporaneamente?
Può essere in esecuzione un solo job dell’Account Activity Replay API per webhook alla volta.
Come posso distinguere gli eventi dell’Account Activity Replay API dagli eventi di produzione in tempo reale mentre vengono consegnati al mio webhook?
Poiché l’Account Activity Replay API consegnerà sempre eventi dal passato, possono essere distinti dagli eventi di produzione in tempo reale in base al timestamp dell’evento.
Quanto presto posso iniziare a usare l’Account Activity Replay API per riconsegnare un’attività che la mia applicazione ha scartato o mancato?
Un’attività diventa disponibile per la riconsegna circa 10 minuti dopo la sua creazione.
Guida alla risoluzione dei problemi
-
Enterprise - Assicurati che le consumer key e gli access token che stai usando appartengano a una X App registrata per l’utilizzo dei prodotti Enterprise. Se non disponi delle tue consumer key e degli access token, o se devi aggiungere la tua X App alla allowlist, contatta il tuo account manager.
-
Se effettui l’autenticazione con contesto utente, assicurati di aver autorizzato correttamente la richiesta con
oauth_nonce, oauth_signature e oauth_timestamp corretti.
-
Assicurati che i tuoi access token abbiano il livello di autorizzazione corretto.
- Nella scheda “Keys and tokens” della app dashboard, verifica che i tuoi access token abbiano il permission level “Read, write, and direct messages”.
- Se il livello di autorizzazione dei token è impostato su un valore inferiore, vai alla scheda “Permissions”, imposta l’autorizzazione di accesso su “Read, write, and direct messages”, quindi rigenera i tuoi access token e il secret dalla scheda “Keys and tokens”.
-
Assicurati che il tuo URL sia formattato correttamente.
- Tieni presente che
:env_name è case-sensitive.
-
Premium - Assicurati di disporre di un account sviluppatore approvato prima di effettuare una richiesta all’API. Devi anche usare il :env_name corretto nella richiesta, che puoi configurare nella pagina dev environments.
-
Enterprise - Assicurati che il tuo account manager ti abbia abilitato l’accesso all’Account Activity API.
-
Verifica di aver configurato correttamente l’URI. Questo errore può verificarsi se nella richiesta è stato inserito un URI non corretto.
Codice 214 - L’URL del webhook non soddisfa i requisiti.
Codice 214 - Latenza elevata sulla richiesta GET del CRC. Il webhook deve rispondere in meno di 3 secondi.
- Significa che il server è lento. Assicurati di rispondere al CRC entro 3 secondi.
Codice 214 - Codice di risposta diverso da 200 durante la richiesta CRC con GET (ad es. 404, 500, ecc.).
- Il server è inattivo. Assicurati che il server sia in esecuzione correttamente.
Codice 214 - Troppe risorse già create.
- Enterprise - Hai già utilizzato tutti i tuoi webhook. Usa l’endpoint GET webhooks con ciascuna delle tue App registrate per identificare dove sono distribuiti i webhook.
Codice 261 - L’applicazione non può eseguire azioni di scrittura.
- L’App che stai utilizzando con l’API non ha il livello di autorizzazione corretto impostato per il suo Access Token e Access Token Secret. Vai alla scheda “Keys and tokens” nella dashboard delle X apps e verifica i livelli di autorizzazione assegnati al tuo Access Token e Access Token Secret. Se è impostato su qualcosa di diverso da “Read, write and Direct Messages”, dovrai modificare le impostazioni nella scheda “Permission” e rigenerare il tuo Access Token e Access Token Secret per applicare le nuove impostazioni.
- In alternativa, potresti star tentando di registrare un webhook utilizzando l’autenticazione solo App, che non è supportata. Esegui invece l’autenticazione con contesto utente come indicato nelle sezioni di riferimento dell’API per la registrazione di un webhook per l’Enterprise Account Activity API.
Indice di riferimento di Account Activity API
Account Activity API (Enterprise)
POST account_activity/webhooks
Registra un nuovo URL webhook per il contesto applicativo specificato. L’URL verrà convalidato tramite una richiesta CRC prima di essere salvato. Se la convalida non riesce, viene restituito al richiedente un messaggio di errore dettagliato.
Il numero di webhook consentiti è determinato dal piano di fatturazione.
https://api.x.com/1.1/account_activity/webhooks.json
| |
|---|
| Formato della risposta | JSON |
| Richiede autenticazione | Sì (contesto utente - tutti i consumer e access token) |
| Soggetto a limite di velocità | Sì |
| Richieste / finestra di 15 minuti (autenticazione utente) | 15 |
| Supporto per le modifiche ai Tweet | Tutti gli oggetti Tweet includeranno i metadata di modifica del Tweet che descrivono la cronologia delle modifiche del Tweet. Consulta la pagina “Nozioni di base sulle modifiche ai Tweet” per maggiori dettagli. |
| |
|---|
| url (obbligatorio) | URL codificato per l’endpoint di callback. |
$ curl —request POST
—url ‘https://api.x.com/1.1/account_activity/webhooks.json?url=https%3A%2F%2Fyour_domain.com%2Fwebhooks%2Ftwitter%2F0'
—header ‘authorization: OAuth oauth_consumer_key=“CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“ACCESS_TOKEN”, oauth_version=“1.0“‘
| Codice HTTP | Messaggio |
|---|
| 200 | L’URL del webhook è registrato all’App fornita |
| 403 | Si è verificato un errore nella richiesta. Vedi la sezione dei messaggi di errore qui sotto. |
Risposta di esempio - Operazione riuscita
_HTTP 200_
{
"id": "1234567890",
"url": "https://your_domain.com/webhook/twitter/0",
"valid": true,
"created_at": "2016-06-02T23:54:02Z"
}
| Codice | Messaggio |
|---|
| 214 | L’URL del webhook non soddisfa i requisiti. |
| 214 | Numero eccessivo di risorse già create. |
| 214 | L’URL del webhook non soddisfa i requisiti. Token CRC non valido o formato della risposta JSON non valido. |
| 214 | Latenza elevata nella richiesta GET del CRC. Il webhook dovrebbe rispondere in meno di 3 secondi. |
| 214 | Codice di risposta diverso da 200 durante la richiesta GET del CRC (ad es. 404, 500, ecc.). |
HTTP 403
{
"errors": [
{
"code": 214,
"message": "Troppe risorse già create."
}
]
}
GET account_activity/webhooks
Restituisce tutti gli URL e i relativi statuses per l’App specificata.
Contrassegniamo un URL come non valido se non supera il controllo di convalida giornaliero. Per riabilitare l’URL, chiama l’endpoint di aggiornamento.
URL della risorsa
https://api.x.com/1.1/account_activity/webhooks.json
| |
|---|
| Formato di risposta | JSON |
| Richiede autenticazione | Sì (solo App - Bearer Token) |
| Soggetto a limite di velocità | Sì |
| Richieste / finestra di 15 minuti (autenticazione dell’App) | 15 |
$ curl --request GET
--url https://api.x.com/1.1/account_activity/webhooks.json
--header 'authorization: Bearer TOKEN'
[
{
"id": "1234567890",
"url": "https://your_domain.com/webhook/twitter/0",
"valid": true,
"created_at": "2016-06-02T23:54:02Z"
}
{
"id": "2468013579",
"url": "https://your_domain2.com/webhook/twitter/0",
"valid": true,
"created_at": "2016-06-04T22:31:29Z"
}
]
Messaggi di errore
| Codice | Messaggio |
|---|
| 99 | Non disponi dell’accesso a questa risorsa. |
PUT account_activity/webhooks/:webhook_id
Avvia il controllo della risposta alla sfida (CRC) per l’URL del webhook specificato. Se il controllo ha esito positivo, restituisce 204 e riabilita il webhook impostandone lo stato su valid.
https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json
| |
|---|
| Formato di risposta | JSON |
| Richiede autenticazione | Sì (contesto utente - tutti i consumer e access token) |
| Soggetto a limite di velocità | Sì |
| Richieste per finestra di 15 minuti (autenticazione utente) | 15 |
Parametri
| |
|---|
| webhook_id (obbligatorio) | id del webhook. Definito nel percorso della risorsa. |
$ curl --request PUT
--url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
--header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'
Messaggi di errore
| Code | Message |
|---|
| 34 | Il webhook non esiste o è associato a un’altra X App. |
| 214 | L’URL del webhook non soddisfa i requisiti. |
| 214 | L’URL del webhook non soddisfa i requisiti. Token CRC non valido o formato della risposta JSON non valido. |
| 214 | Latenza elevata sulla richiesta GET di CRC. Il tuo webhook dovrebbe rispondere in meno di 3 secondi. |
| 214 | Codice di risposta diverso da 200 durante la richiesta GET di CRC (ad es. 404, 500, ecc.). |
POST account_activity/webhooks/:webhook_id/subscriptions/all
Iscrive l’App fornita a tutti gli eventi nel contesto utente indicato per tutti i tipi di messaggio. Dopo l’attivazione, tutti gli eventi relativi all’utente richiedente saranno inviati al webhook dell’applicazione tramite una richiesta POST.
Al momento le iscrizioni sono limitate in base alla configurazione del tuo account. Se hai necessità di aggiungerne altre, contatta il tuo account manager.
URL risorsa
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json
| |
|---|
| Formato di risposta | JSON |
| Richiede autenticazione | Sì (OAuth a 3 fasi - consumer key in whitelist e access token dell’utente sottoscrittore) |
| Soggetto a limite di velocità | Sì |
| Richieste/15 minuti (autenticazione utente) | 500 |
Parametri
| |
|---|
| webhook_id (obbligatorio) | ID del webhook. Definito nel percorso della risorsa. |
$ curl --request POST
--url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
--header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBING_USER'S_ACCESS_TOKEN", oauth_version="1.0"'
Esempio di risposta - esito positivo
Messaggi di errore
| Codice | Messaggio |
|---|
| 34 | Il webhook non esiste o è associato a un’App X diversa. |
| 348 | L’App client non è autorizzata ad accedere alle sottoscrizioni del webhook di questo utente. |
GET account_activity/subscriptions/count
Restituisce il numero di sottoscrizioni attualmente attive sul tuo account. Tieni presente che l’endpoint /count richiede l’autenticazione OAuth in modalità solo applicazione; pertanto le richieste vanno effettuate utilizzando un Bearer Token anziché il contesto utente.
URL della risorsa
https://api.x.com/1.1/account_activity/subscriptions/count.json
| |
|---|
| Formato di risposta | Codice di risposta HTTP |
| Richiede autenticazione | Sì (solo App - Bearer Token) |
| Soggetto a limite di velocità | Sì |
| Richieste / finestra di 15 minuti (autenticazione App) | 15 |
| |
|---|
| Codice | Messaggio |
| 200 | Operazione riuscita. Verrà restituito il numero di sottoscrizioni per il webhook richiesto. |
| 401 | L’App non dispone delle autorizzazioni per visualizzare le sottoscrizioni per il webhook specificato. |
$ curl --request GET
--url https://api.x.com/1.1/account_activity/subscriptions/count.json
--header 'authorization: Bearer TOKEN'
Esempio di risposta - Esito positivo
{
"account_name":"il-mio-account",
"subscriptions_count_all":"1",
"subscriptions_count_direct_messages":"0",
"provisioned_count":"50"
}
Messaggi di errore
| Codice | Messaggio |
|---|
| 32 | Impossibile eseguire l’autenticazione. |
HTTP 401
{
"errors": [
{
"code": 32,
"message": "Impossibile autenticare l'utente."
}
]
}
GET account_activity/webhooks/:webhook_id/subscriptions/all
Consente di verificare se una configurazione di webhook è iscritta agli eventi dell’utente indicato. Se il contesto utente fornito ha un abbonamento attivo con l’App indicata, viene restituito 204 OK. Se il codice di risposta non è 204, l’utente non ha un abbonamento attivo. Vedi di seguito i codici di risposta HTTP e i messaggi di errore per maggiori dettagli.
URL della risorsa
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json
| |
|---|
| Formato della risposta | JSON |
| Richiede autenticazione | Sì (OAuth a 3 fasi - consumer key in whitelist e access token dell’utente sottoscrittore) |
| Soggetto a limite di velocità | Sì |
| Richieste / finestra di 15 minuti (autenticazione utente) | 500 |
Parametri
| |
|---|
| webhook_id (obbligatorio) | ID del webhook. Definito nel percorso della risorsa. |
Esempio di richiesta
$ curl —request GET
—url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
—header ‘authorization: OAuth oauth_consumer_key=“WHITELISTED_CONSUMER_KEY”, oauth_nonce=“GENERATED”, oauth_signature=“GENERATED”, oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“GENERATED”, oauth_token=“SUBSCRIBING_USER'''S_ACCESS_TOKEN”, oauth_version=“1.0“‘
Esempio di risposta - esito positivo
GET account_activity/webhooks/:webhook_id/subscriptions/all/list
Restituisce l’elenco delle sottoscrizioni correnti di tipo All Activity per il webhook specificato. Nota: l’endpoint /list richiede l’autenticazione OAuth in modalità solo applicazione; pertanto le richieste devono essere effettuate utilizzando un Bearer Token invece del contesto utente.
URL della risorsa
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all/list.json
| |
|---|
| Formato della risposta | Codice di risposta HTTP |
| Richiede autenticazione | Sì (solo App - Bearer Token) |
| Soggetto a limite di velocità | Sì |
| Richieste per finestra di 15 minuti (autenticazione dell’App) | 50 |
Parametri
| |
|---|
| webhook_id (obbligatorio) | id del webhook. Definito nel percorso della risorsa. |
| Codice | Messaggio |
|---|
| 200 | Operazione riuscita. Verrà restituito un elenco di abbonamenti per il webhook richiesto. |
| 401 | L’App non dispone dell’autorizzazione per visualizzare gli abbonamenti per il webhook specificato. |
Esempio di richiesta
$ curl —request GET
—url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all/list.json
—header ‘authorization: Bearer TOKEN’
Esempio di risposta - esito positivo
{
"webhook_id": "1234567890",
"webhook_url": "https://your_domain.com/webhook/twitter/0",
"application_id": "11231812",
"subscriptions": [{
"user_id": "20212306"
}]
}
| Codice | Messaggio |
|---|
| 32 | Impossibile eseguire l’autenticazione. |
HTTP 401
{
"errors": [
{
"code": 32,
"message": "Impossibile autenticare l'utente."
}
]
}
DELETE account_activity/webhooks/:webhook_id
Rimuove il webhook dalla configurazione dell’App specificata. L’id del webhook è reperibile effettuando una chiamata GET a /1.1/account_activity/webhooks.
https://api.x.com/1.1/account_activity/webhooks/:webhook_id.json
| |
|---|
| Formato di risposta | JSON |
| Richiede autenticazione | Sì (contesto utente — tutti i consumer e access token) |
| Soggetto a limite di velocità | Sì |
| Richieste per finestra di 15 minuti (autenticazione utente) | 15 |
Parametri
| |
|---|
| webhook_id (obbligatorio) | id del webhook. Definito nel percorso della risorsa. |
$ curl --request DELETE
--url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID.json
--header 'authorization: OAuth oauth_consumer_key="CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="ACCESS_TOKEN", oauth_version="1.0"'
Risposta
HTTP 204 OK
DELETE account_activity/webhooks/:webhook_id/subscriptions/all (DEPRECATO)
Disattiva le iscrizioni per il contesto utente e l’App specificati. Dopo la disattivazione, tutti gli eventi relativi all’utente richiedente non verranno più inviati all’URL del webhook.
URL della risorsa
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/all.json
| |
|---|
| Formato della risposta | JSON |
| Richiede autenticazione | Sì (OAuth a 3 vie - consumer key in whitelist e access token dell’utente sottoscrittore) |
| Soggetto a limite di velocità | Sì |
| Richieste / finestra di 15 minuti (autenticazione utente) | 500 |
Parametri
| |
|---|
| webhook_id (obbligatorio) | id del webhook. Definito nel percorso della risorsa. |
$ curl --request DELETE
--url https://api.x.com/1.1/account_activity/webhooks/:WEBHOOK_ID/subscriptions/all.json
--header 'authorization: OAuth oauth_consumer_key="WHITELISTED_CONSUMER_KEY", oauth_nonce="GENERATED", oauth_signature="GENERATED", oauth_signature_method="HMAC-SHA1", oauth_timestamp="GENERATED", oauth_token="SUBSCRIBED_USER'S_ACCESS_TOKEN", oauth_version="1.0"'
DELETE /account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json
Disattiva la sottoscrizione per il webhook e l’id utente specificati. Dopo la disattivazione, tutti gli eventi relativi all’utente che effettua la richiesta non verranno più inviati all’URL del webhook. Nota: questo endpoint richiede l’autenticazione OAuth in modalità solo applicazione; le richieste devono quindi essere effettuate utilizzando un Bearer Token invece del contesto utente.
URL della risorsa
https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json
| |
|---|
| Formato della risposta | JSON |
| Autenticazione richiesta | Sì (solo App - Bearer Token) |
| Soggetto a limite di velocità | Sì |
| Richieste / finestra di 15 minuti | 500 |
$ curl --request DELETE
--url https://api.x.com/1.1/account_activity/webhooks/:webhook_id/subscriptions/:user_id/all.json
--header 'authorization: Bearer TOKEN'
Messaggi di errore
| Codice | Messaggio |
|---|
| 404 | Siamo spiacenti, questa pagina non esiste. - Questo si verifica spesso quando l’utente con l’id specificato non risulta effettivamente iscritto. |
POST /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json ¶
Invia una richiesta per recuperare le attività fino ai cinque giorni precedenti da tutte le sottoscrizioni presenti nelle finestre di data e ora specificate nella richiesta. Se il tuo webhook ha sottoscrizioni utente attive, riceverai in parallelo anche tali eventi. Nota: eseguiamo un CRC prima di consegnare gli eventi di replay.
| |
|---|
| Request Method | HTTP POST |
| URL | /1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm |
| Response Format | JSON |
| Requires Authentication | Yes (solo applicazione - Bearer Token) |
| Rate Limit | 5 richieste ogni 15 minuti. Al momento non esiste un limite massimo al numero di job di replay che è possibile richiedere. |
| from_date | Il timestamp UTC più antico (iniziale) da cui verranno forniti gli eventi; deve essere nel formato ‘yyyymmddhhmm’. Il timestamp ha granularità al minuto ed è inclusivo (cioè 12:00 include il minuto 00). Gli orari validi devono rientrare negli ultimi 5 giorni, in UTC, e non essere più recenti di 31 minuti rispetto all’istante attuale. Si consiglia che from_date e to_date siano entro ~2 ore. |
| to_date | Il timestamp UTC più recente (finale) fino al quale verranno forniti gli eventi; deve essere nel formato ‘yyyymmddhhmm’. Il timestamp ha granularità al minuto ed è esclusivo (cioè 12:30 non include il 30° minuto dell’ora). Gli orari validi devono rientrare negli ultimi 5 giorni, in UTC, e non essere più recenti di 10 minuti rispetto all’istante attuale. |
Le seguenti risposte possono essere restituite dall’API. La maggior parte dei codici di errore viene restituita con una stringa che include ulteriori dettagli nel body. Per risposte diverse da 200, è necessario risolvere l’errore e riprovare.
| Status | Text | Error Code | Description | Message |
|---|
| 202 | Accepted | N/A | La richiesta è stata eseguita correttamente e le attività verranno inviate. | N/A |
| 400 | Bad Request | 214 | Il webhook è stato contrassegnato come non valido. | Il webhook è contrassegnato come non valido e richiede un controllo CRC. |
| 400 | Bad Request | 357 | Manca il parametro query. | : queryParam è obbligatorio. |
| 400 | Bad Request | 358 | Il route o il parametro query è malformato. | Impossibile analizzare il parametro. |
| 400 | Bad Request | 360 | Il parametro route è negativo. | webhook_id: [] non è maggiore o uguale a 0. |
| 400 | Bad Request | 368 | from_date o to_date non è nel passato. | : [<field_value>] non è nel passato. |
| 400 | Bad Request | 356 | from_date deve precedere to_date. | from_date deve precedere to_date. |
| 400 | Bad Request | 356 | from_date deve rientrare negli ultimi 5 giorni. | from_date deve rientrare negli ultimi 5 giorni. |
| 401 | Unauthorized | 32 | Autenticazione HTTP non riuscita a causa dell’autenticazione a 3 leg. | Metodo di autenticazione non valido. Usa l’autenticazione application-only. |
| 401 | Unauthorized | 61 | Il client non è autorizzato a richiedere questo metodo. | Il client non è autorizzato a richiedere questo metodo. |
| 403 | Forbidden | 200 | Il client non dispone di un account Enterprise con Replay abilitato. | È richiesto un account Enterprise dell’Account Activity API con replay. Conferma di avere un account Enterprise e che il replay sia abilitato. |
| 404 | Not Found | 34 | webhook_id inesistente; mancata corrispondenza tra webhook_id e application_id. | Il webhook non esiste o è associato a una diversa X App. |
| 409 | Conflict | 355 | È presente una richiesta in corso che deve terminare l’elaborazione prima di poterne effettuare un’altra. | Un job di replay è già in corso per questo webhook. |
| 429 | Too Many Requests | 88 | Limite di velocità raggiunto (raggiunto il limite di richieste per intervallo di tempo). | Troppe richieste. Riduci la frequenza delle richieste alla tua API. |
| 500 | Internal Server Error | 0 | Errore interno del server. | Errore interno del server. |
| 503 | Service Unavailable | 67 | Uno o più servizi dipendenti su X non sono disponibili. | Errore del server X. Riprova utilizzando un backoff esponenziale. |
”Messaggio: job completato correttamente”
Quando il job viene completato correttamente, l’API Account Activity Replay invia il seguente evento di completamento del job. Una volta ricevuto questo evento, il job ha terminato l’esecuzione e se ne può inviare un altro.
{
"replay\_job\_status": {
"webhook_id": "1234577122340233217",
"job_state": "Complete",
"job\_state\_description": "Job completato con successo"
"job_id": "1095098195724558337"
}
}
Messaggio “Job failed to complete”
Se il tuo job non viene completato correttamente, restituiremo il seguente messaggio invitandoti a riprovare il job di Replay. Una volta ricevuto questo evento, il job ha terminato l’esecuzione e puoi inviarne un altro.
{
"replay\_job\_status": {
"webhook_id": "123451374207332352",
"job_state": "Incomplete",
"job\_state\_description": "Il job non è riuscito a consegnare tutti gli eventi, riprovare il job di replay",
"job_id": "1093226942650736640"
}
}
Esempio di richiesta cURL
curl --request POST --url 'https://api.x.com/1.1/account_activity/replay/webhooks/:webhook_id/subscriptions/all.json?from_date=yyyymmddhhmm&to_date=yyyymmddhhmm'
--header 'authorization: Bearer TOKEN'
{
"job_id": "1234567890",
"created_at": "2016-06-02T23:54:02Z"
}
