Vai al contenuto principale
Gli endpoint dei Messaggi Diretti v2 introducono le conversazioni e gli eventi di conversazione come oggetti fondamentali della X API e distinguono tra conversazioni 1-1 e di gruppo. Le conversazioni 1-1 hanno sempre due, e solo due, partecipanti, mentre le conversazioni di gruppo possono avere due o più partecipanti e una composizione che può cambiare.    Questa pagina contiene informazioni su diversi strumenti e concetti chiave di cui dovresti essere a conoscenza mentre integri gli endpoint di lookup dei Messaggi Diretti nel tuo sistema. Abbiamo suddiviso la pagina in due sezioni:

​
Concetti fondamentali

​
Conversazioni di Messaggi Diretti

Tutti i Messaggi Diretti fanno parte di una conversazione di Messaggi Diretti. Queste conversazioni possono essere one‑to‑one oppure di gruppo. Questo rilascio fornisce gli endpoint di base necessari per creare Messaggi Diretti e recuperare gli eventi associati alle conversazioni di Messaggi Diretti. Tutte le conversazioni hanno un dm_conversation_id univoco e gli eventi che compongono quella conversazione hanno ciascuno un dm_event_id univoco.   Gli endpoint di lookup dei Messaggi Diretti forniscono metodi per recuperare gli eventi associati alle conversazioni. Questi endpoint GET vengono utilizzati per recuperare i messaggi che compongono una conversazione e, per le conversazioni di gruppo, possono essere usati per capire chi è entrato e chi ha lasciato le conversazioni di gruppo. Questa versione iniziale del lookup dei Messaggi Diretti include tre metodi GET:
  • GET /2/dm_conversations/with/:participant_id/dm_events - Recupera gli eventi dei Messaggi Diretti associati a una conversazione one‑to‑one. Il parametro di percorso :participant_id è l’ID utente numerico dell’account che sta conversando con l’utente autenticato che effettua questa richiesta.  
  • GET /2/dm_conversations/:dm_conversation_id/dm_events - Recupera gli eventi dei Messaggi Diretti associati a uno specifico ID conversazione, come indicato dal parametro di percorso :dm_conversation_id. Sono supportati sia gli ID delle conversazioni one‑to‑one sia quelli di gruppo.  
  • GET /2/dm_events - Recupera gli eventi dei Messaggi Diretti associati all’utente autenticato, incluse sia le conversazioni one‑to‑one sia quelle di gruppo. Sono disponibili eventi fino a 30 giorni precedenti.  
Tutti questi endpoint GET supportano il recupero di dm_events per tipo di evento tramite il parametro di query della richiesta event_types. Attualmente sono supportati tre tipi di eventi di conversazione:
  • MessageCreate - Creato quando viene inviato un nuovo Messaggio Diretto. Questo oggetto evento può includere l’ora e il testo del messaggio, insieme all’ID dell’account che ha inviato il messaggio e agli ID della conversazione e dell’evento. 
  • ParticipantsJoin - Creato quando un nuovo partecipante entra in una conversazione di gruppo. Questo oggetto dm_event include l’ID del partecipante che entra, insieme al timestamp created_at e al sender_id dell’evento “invite”. 
  • ParticipantsLeave - Creato quando un partecipante lascia una conversazione. Questo oggetto evento include l’ID del partecipante che lascia, insieme all’ora dell’evento. 
Per ulteriori informazioni, vedere i riferimenti dell’API di lookup dei Messaggi Diretti.

​
ID di conversazione ed evento condivisi tra v1.1 e v2

Un concetto importante è che gli ID di conversazione ed evento sono condivisi tra le versioni v1.1 e v2 della piattaforma X. Ciò significa che entrambe le versioni possono essere usate insieme. Ad esempio, gli endpoint dei Messaggi Diretti v1.1 offrono metodi per recuperare un singolo evento e per eliminare eventi, metodi non ancora disponibili con v2. Poiché gli ID sono comuni tra v1.1 e v2, puoi effettuare richieste v1.1 basandoti sugli ID forniti da v2 oppure facendo riferimento agli ID di conversazione mostrati negli URL della conversazione sull’app X.  

​
Campi ed expansions degli eventi dei Messaggi Diretti

La X API v2 consente agli utenti di selezionare esattamente quali data restituire dall’API utilizzando un set di strumenti chiamati fields ed expansions. Ad esempio, gli endpoint di ricerca dei Messaggi Diretti supportano i seguenti campi dm_events:
  • id, event_type e text sono i valori predefiniti per gli eventi MessageCreate.
  • id, event_type e participant_ids sono i valori predefiniti per gli eventi ParticipantsJoin e ParticipantsLeave.
  • dm_conversation_id e created_at sono disponibili per tutti gli eventi.
  • attachments e referenced_tweets sono disponibili per gli eventi MessageCreate.
  • sender_id è disponibile per gli eventi MessageCreate e ParticipantsJoin.
  • participant_ids è disponibile per gli eventi ParticipantsJoin e ParticipantsLeave.
Inoltre, gli endpoint di ricerca dei Messaggi Diretti supportano le seguenti expansions:
  • sender_id - Espande l’oggetto User associato a chi ha inviato il messaggio o a chi ha invitato qualcuno alla conversazione.
  • referenced_tweets.id - Espande l’Oggetto Post se il testo del Messaggio Diretto include un link a un Post.
  • attachments.media_keys - Espande l’oggetto Media se il Messaggio Diretto include un allegato multimediale.
  • participant_ids - Espande l’oggetto User associato a chi è entrato o uscito da una conversazione di gruppo.
Poiché le expansions includono oggetti Posts, Users e Media, puoi anche utilizzare i parametri di query della richiesta tweet.fields, user.fields e media.fields. Consulta la nostra guida su come usare fields ed expansions per maggiori informazioni.

​
Tipi di eventi di conversazione

Di seguito sono riportati esempi di oggetti JSON per i tipi di evento di Direct Message: MessageCreate, ParticipantsJoin e ParticipantsLeave. Campi disponibili dell’oggetto dm_event: id, text, event_type, dm_conversation_id, created_at, sender_id, attachments, referenced_tweets, participant_ids. Consulta la sezione Fields and Expansion per maggiori dettagli sulla selezione di questi campi nelle richieste. Esempio di evento MessageCreate: Con tutti i campi dm_event specificati, ecco la risposta per un Direct Message di solo testo: { "text": "Hi everyone.", "sender_id": "944480690", "dm_conversation_id": "1578398451921985538", "id": "1582838499983564806", "event_type": "MessageCreate", "created_at": "2022-10-19T20:58:00.000Z" } Esempio di evento ParticipantsJoin: Con tutti i campi dm_event specificati, ecco la risposta per l’ingresso di un partecipante in una conversazione: { "participant_ids": [ "944480690" ], "sender_id": "17200003", "dm_conversation_id": "1578398451921985538", "id": "1582835469712138240", "event_type": "ParticipantsJoin", "created_at": "2022-10-19T20:45:58.000Z" } Esempio di evento ParticipantsLeave: Con tutti i campi dm_event specificati, ecco la risposta per l’uscita di un partecipante da una conversazione: { "participant_ids": [ "944480690" ], "dm_conversation_id": "1578398451921985538", "id": "1582838535115067392", "event_type": "ParticipantsLeave", "created_at": "2022-10-19T20:58:09.000Z" }

​
Autenticazione

Tutti gli endpoint di X API v2 richiedono che tu autentichi le richieste con un set di credenziali, noto anche come chiavi e token. Tutti i Messaggi Diretti sono privati e richiedono l’autorizzazione dell’utente per accedervi. Questi endpoint per i Messaggi Diretti richiedono l’uso di OAuth 2.0 Authorization Flow with PKCE o 1.0a User Context, il che significa che devi utilizzare un set di API Key e Access Tokens utente per effettuare correttamente una richiesta. Gli Access Tokens devono essere associati all’utente per conto del quale stai effettuando la richiesta. Se desideri generare un set di Access Tokens per un altro utente, quest’ultimo deve autorizzare o autenticare la tua App utilizzando il flusso OAuth a 3 vie. Tieni presente che il contesto utente di OAuth può risultare complesso da utilizzare. Se non conosci questo metodo di autenticazione, ti consigliamo di usare una libreria o uno strumento come Postman per autenticare correttamente le richieste. OAuth 2.0 Authorization Code con PKCE consente un maggiore controllo sull’ambito di un’applicazione e sui flussi di autorizzazione tra più dispositivi. OAuth 2.0 ti permette di scegliere scope specifici e granulari che ti forniscono autorizzazioni specifiche per conto di un utente. Gli endpoint di lookup dei Messaggi Diretti richiedono questi scope: dm.read, post.read, user.read Per abilitare OAuth 2.0 nella tua App, devi attivarlo nelle impostazioni di autenticazione della tua App, nella sezione delle impostazioni dell’App del developer portal.

​
Developer portal, Project e App sviluppatore

Per ottenere un set di credenziali di autenticazione compatibili con gli endpoint della X API v2, devi disporre di un account sviluppatore approvato, creare un Project all’interno di tale account e creare un’App sviluppatore all’interno di quel Project. Potrai quindi trovare le tue chiavi e token nella tua App sviluppatore. 

​
Limiti di velocità

Ogni giorno molte migliaia di sviluppatori inviano richieste alla X API. Per gestire l’elevato volume di queste richieste, vengono applicati limiti di velocità a ciascun endpoint, che determinano il numero di richieste che puoi effettuare per conto della tua App o di un utente autenticato. Gli endpoint di ricerca dei Direct Message sono soggetti a limiti di velocità a livello utente, il che significa che l’utente autenticato per conto del quale stai effettuando la richiesta può effettuare solo un determinato numero di richieste con la tua X App. È previsto un limite di velocità per utente di 300 richieste ogni 15 minuti per i metodi GET. Questi limiti di velocità sono condivisi tra gli endpoint GET.  Questi endpoint utilizzano la paginazione per restituire le risposte rapidamente. Nei casi in cui i risultati siano più di quelli che possono essere inviati in un’unica risposta (fino a 100 eventi), è necessario paginare. Usa il parametro max_results per specificare quanti risultati restituire per pagina e il parametro pagination_token per ottenere la pagina successiva di risultati. Per saperne di più, consulta la nostra guida alla paginazione. Strumenti utili Di seguito alcuni strumenti utili che ti invitiamo a esplorare mentre lavori con gli endpoint di lookup dei Messaggi Diretti: Postman Postman è un ottimo strumento per testare un endpoint. Ogni richiesta Postman include tutti i parametri di path e di body per aiutarti a comprendere rapidamente ciò che è disponibile. Per ulteriori informazioni sulle nostre raccolte Postman, visita la pagina Utilizzo di Postman. Esempi di codice Esempi di codice Python per gli endpoint v2 dei Messaggi Diretti sono disponibili nel nostro repository X API v2 sample code GitHub. La cartella “Manage-Direct-Messages” contiene esempi per i metodi POST e la cartella “Direct-Messages-lookup” contiene esempi per i metodi GET. XDev Software Development Kits (SDKs) Queste librerie sono in fase di aggiornamento per gli endpoint v2 dei Messaggi Diretti e saranno pronte a breve: Librerie di terze parti Il numero di librerie di terze parti sviluppate dalla nostra community è in crescita. Queste librerie sono progettate per aiutarti a iniziare e diverse dovrebbero supportare a breve gli endpoint v2 dei Messaggi Diretti. Puoi trovare una libreria compatibile con gli endpoint v2 cercando il tag di versione appropriato.
⌘I