Vai al contenuto principale
Gli endpoint dei Messaggi Diretti v2 introducono conversazioni ed eventi di conversazione come oggetti fondamentali della X API e distinguono tra conversazioni one‑to‑one e di gruppo. Le conversazioni one‑to‑one hanno sempre due, e solo due, partecipanti, mentre le conversazioni di gruppo possono averne due o più e membership che possono variare.    Questa pagina contiene informazioni su diversi strumenti e concetti chiave di cui dovresti essere a conoscenza mentre integri gli endpoint Gestione Messaggi Diretti nel tuo sistema. Abbiamo suddiviso la pagina in due sezioni: Concetti chiave

​
Conversazioni di Messaggi Diretti

Tutti i Messaggi Diretti fanno parte di una conversazione di Messaggi Diretti. Queste conversazioni possono essere uno a uno oppure di gruppo. Questo rilascio fornisce gli endpoint fondamentali 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 Gestione Messaggi Diretti forniscono tre metodi POST per creare nuovi messaggi e aggiungerli alle conversazioni:
  • POST /2/dm_conversations/with/:participant_id/messages - Crea un Messaggio Diretto uno a uno. Questo metodo aggiunge il messaggio a una conversazione uno a uno esistente oppure ne crea una nuova. Il parametro di percorso :participant_id è l’User ID dell’account che riceve il messaggio.  Ecco un esempio di corpo della richiesta JSON per inviare un Messaggio Diretto uno a uno:
{
   "text": "Ciao, solo tu. Questo apparirà come una nuova conversazione se non ci siamo mai scambiati messaggi, oppure verrà aggiunto alla nostra conversazione esistente. "
}
  • POST /2/dm_conversations - Crea una nuova conversazione di gruppo e vi aggiunge un Direct Message. Queste richieste richiedono un elenco di partecipanti alla conversazione. Nota che puoi creare più conversazioni con lo stesso elenco di partecipanti. Queste richieste restituiranno sempre un nuovo id di conversazione. Di seguito è riportato un esempio di corpo richiesta JSON per creare una nuova conversazione di gruppo e aggiungere un Direct Message. Nota che è necessario includere un campo “conversation_type” impostato su “Group” (maiuscole/minuscole rilevanti).
{
   "message": {"text": "Ciao a voi due, questa è una nuova conversazione di gruppo."},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - Crea un messaggio diretto e lo aggiunge a una conversazione esistente. Il parametro di percorso :dm_conversation_id è l’id della conversazione a cui verrà aggiunto il messaggio. Questo metodo può essere usato per aggiungere un messaggio sia alle conversazioni uno a uno sia a quelle di gruppo. Ecco un esempio di body della richiesta JSON per inviare un messaggio diretto sia a conversazioni uno a uno sia di gruppo:
{
   "text": "Ecco un nuovo messaggio."
}
Questi metodi POST consentono di allegare un singolo contenuto multimediale. I corpi delle richieste POST devono includere uno o entrambi i campi “text” e “attachments”. L’attributo “text” è obbligatorio se il campo “attachments” non è incluso, e il campo “attachments” è obbligatorio se il campo “text” non è incluso. Consulta la sezione successiva per ulteriori informazioni. Per ulteriori informazioni, consulta la sezione di riferimento Manage Direct Messages API.

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

Un concetto importante è che gli id di conversazione e di evento sono condivisi tra le versioni v1.1 e v2 della Piattaforma X. Questo significa che entrambe le versioni possono essere utilizzate insieme. Ad esempio, gli endpoint dei Messaggi Diretti v1.1 offrono metodi per restituire un singolo evento e per eliminare eventi. Questi metodi non sono ancora disponibili con v2. Poiché gli id sono comuni tra v1.1 e v2, è possibile effettuare richieste v1.1 basate su id forniti da v2, oppure facendo riferimento agli id di conversazione visualizzati negli URL delle conversazioni sull’app X.  

​
Inclusione di allegati multimediali e riferimento ai Post

Tutti gli endpoint di Manage Direct Message supportano l’allegamento di un singolo contenuto multimediale (foto, video o GIF). L’allegamento richiede un media id generato dall’endpoint v1.1 Upload media. L’utente autenticato che invia il Direct Message deve aver caricato anche il contenuto multimediale. Una volta caricato, il contenuto multimediale rimane disponibile per 24 ore per essere incluso nel messaggio. Per illustrare come includere contenuti multimediali, di seguito è riportato un esempio di corpo della richiesta JSON: 
{
 "text": "Ecco una foto...",
 "attachments": [{"media_id": "1583157113245011970}]
}
L’evento MessageCreate risultante includerà i seguenti metadata: 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
I Post possono essere inclusi anche inserendo l’URL del Post nel testo del messaggio. Per mostrare come includere i Post nei messaggi, di seguito è riportato un esempio di body della richiesta JSON: 
{
 "text": "Ecco il Tweet di cui stavo parlando: https://x.com/SnowBotDev/status/1580559079470145536"
}
L’evento MessageCreate risultante includerà i seguenti metadata: 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
Autenticazione

Tutti gli endpoint di X API v2 richiedono l’autenticazione delle richieste con un set di credenziali, note anche come chiavi e token. Tutti i Messaggi Diretti sono privati e richiedono l’autorizzazione dell’utente per poterli consultare. Questi endpoint dei 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 la 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. Se non hai familiarità con questo metodo di autenticazione, ti consigliamo di utilizzare una libreria o uno strumento come Postman per autenticare correttamente le richieste. OAuth 2.0 Authorization Code con PKCE consente un controllo più granulare sull’ambito di un’applicazione e sui flussi di autorizzazione su più dispositivi. OAuth 2.0 consente di scegliere scope specifici e dettagliati, che ti conferiscono permessi precisi per conto di un utente. Gli endpoint di ricerca dei Messaggi Diretti richiedono questi scope: dm.write, dm.read, tweet.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 avere un account sviluppatore approvato, configurare 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 all’interno della tua App sviluppatore. 

​
Limiti di velocità

Ogni giorno migliaia di sviluppatori inviano richieste alla X API. Per gestire l’elevato volume di traffico, su ciascun endpoint vengono applicati limiti di velocità che definiscono quante richieste puoi effettuare per conto della tua App o di un utente autenticato.  Gli endpoint Manage Direct Message sono soggetti a limiti di velocità sia a livello utente sia a livello di X App. Questo significa che l’utente autenticato per conto del quale stai effettuando la richiesta può inviare solo un numero limitato di messaggi tramite la tua X App. Inoltre, è previsto un limite giornaliero al numero di Messaggi Diretti che possono essere inviati dalla tua X App.  È previsto un limite di velocità per utente di 200 richieste/messaggi ogni 15 minuti per i metodi POST. Gli utenti sono inoltre limitati a 1000 Messaggi Diretti ogni 24 ore. Inoltre, le X App hanno un limite di 15000 messaggi ogni 24 ore. Questi limiti di velocità sono condivisi tra gli endpoint POST.  Strumenti utili Ecco alcuni strumenti utili che ti invitiamo a esplorare mentre lavori con gli endpoint di lookup dei Messaggi Diretti:  Postman Postman è un ottimo strumento che puoi usare per testare un endpoint. Ogni richiesta Postman include tutti i parametri di path e di body per aiutarti a capire rapidamente cosa è disponibile. Per saperne di più sulle nostre raccolte Postman, visita la pagina Using Postman.  Esempi di codice Esempi di codice Python per gli endpoint v2 dei Messaggi Diretti sono disponibili nel 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 Esiste un numero crescente di librerie di terze parti sviluppate dalla nostra community. Queste librerie sono pensate per aiutarti a iniziare e si prevede che diverse supporteranno presto gli endpoint v2 dei Messaggi Diretti. Puoi trovare una libreria compatibile con gli endpoint v2 cercando il tag di versione appropriato.
⌘I