Guida rapida

​

Introduzione agli endpoint per la gestione dei Messaggi Diretti

Questa guida di Avvio rapido ti aiuterà a inviare la tua prima richiesta agli endpoint dei Messaggi Diretti utilizzando Postman, uno strumento per gestire ed effettuare richieste HTTP. Per saperne di più sulle nostre raccolte Postman, consulta la guida Uso di Postman.

Consulta il nostro repository GitHub X API v2 sample code se desideri esempi in Python. Inoltre, i software development kit (SDK) della X Developer Platform ufficiali saranno aggiornati per supportare questi endpoint dei Messaggi Diretti.  

Prerequisiti

Per completare questa guida, avrai bisogno di un set di chiavi e token per autenticare la richiesta. Puoi generare queste chiavi e token seguendo questi passaggi:

• Registrati per un account sviluppatore e attendi l’approvazione.
• Crea un Project e una developer App associata nel developer portal.
• Vai alla pagina “Keys and tokens” della tua App per generare le credenziali necessarie. Assicurati di salvare tutte le credenziali in un luogo sicuro.

​

Passaggi per creare richieste di ricerca dei Messaggi diretti

In questo esempio, con un’unica richiesta creeremo una nuova conversazione di gruppo e vi aggiungeremo il primo messaggio. Quindi aggiungeremo un secondo messaggio alla conversazione creata.

​

Primo passaggio: iniziare con uno strumento o una libreria

Per iniziare a lavorare con gli endpoint per la gestione dei Messaggi Diretti, utilizzeremo lo strumento Postman per semplificare il processo. Useremo una raccolta di richieste d’esempio della X API v2, curata da XDevelopers, per esplorare sei endpoint utilizzati per creare nuovi Messaggi Diretti e per elencare gli eventi delle conversazioni di Messaggi Diretti.

Sebbene gran parte della raccolta sia precompilata, ci sono alcuni dettagli che dovrai fornire in base alla X App creata per ospitare queste richieste API. Per prima cosa, carichiamo/aggiorniamo la raccolta.

Per caricare la raccolta X API v2 di Postman nel tuo ambiente, fai clic sul seguente pulsante:

Aggiungi X API v2 a Postman

Una volta caricata la raccolta X API v2 in Postman, vai alla cartella “Manage Direct Messages”. La scheda Authorization di questa cartella è stata precompilata ove possibile. Dovrai aggiornare alcune impostazioni per inserire i dettagli di autenticazione della tua X App.

Questa cartella contiene anche tre endpoint per creare nuovi Messaggi Diretti. Nota che è presente anche una cartella “Direct Message lookup” con tre endpoint disponibili per recuperare gli eventi delle conversazioni di Messaggi Diretti, inclusi l’invio e la ricezione di messaggi e i momenti in cui i partecipanti alla conversazione si uniscono o lasciano.

Poiché la creazione di conversazioni di gruppo è una nuova funzionalità della X API v2, questo esempio si concentrerà su questo aspetto. Lavoreremo con l’esempio “New group DM and conversation”. Useremo questa richiesta per creare una conversazione di gruppo nei Messaggi Diretti.

Il passo successivo è autenticarsi con l’endpoint.

​

Secondo passaggio: Autentica la richiesta

Per effettuare correttamente una richiesta alla X API, devi verificare di avere l’autorizzazione a farlo. Per inviare con successo una richiesta a questo endpoint, utilizzeremo l’OAuth 2.0 Authorization Code Flow with PKCE. Puoi generare un access token in Postman. 

Con Postman puoi impostare il metodo di autenticazione a livello di cartella o a livello di singola richiesta. Qui configureremo i dettagli di autenticazione a livello di cartella. Vai alla cartella “Manage Direct Messages”, seleziona la scheda “Authorization” e conferma che il Type sia impostato su “OAuth 2.0” e che “Add auth data to” sia impostato su “Request Headers.” Nella sezione “Current Token”, assicurati che “Header Prefix” sia impostato su Bearer.  

Per configurare e generare un nuovo token:

1. Crea un Token Name, ad esempio “DM lookup.”

2. Conferma che Grant Type sia impostato su Authorization Code (with PKCE).

3. Imposta la Callback URL. Devi aggiornarla in modo che corrisponda esattamente alla Callback URL associata alla tua applicazione nel v2 Dev Portal. Con la X App utilizzata in questo esempio, la Callback URL è impostata su - https://www.example.com. (Nota: poiché deve corrispondere esattamente, https://example.com non funzionerebbe.) 

4. Conferma che Auth URL sia impostata su https://x.com/i/oauth2/authorize

5. Conferma che Access Token URL sia impostata su https://api.x.com/2/oauth2/token.Client ID - Copia e incolla l’OAuth 2.0 client ID dal developer portal Client Secret - Ti servirà solo se stai usando un tipo di App che è un confidential client. In tal caso, copia e incolla l’OAuth 2.0 Client Secret dal developer portal. 

6. Conferma che Scope sia impostato su dm.read dm.write tweet.read users.read.

7. Conferma che State sia impostato su “state.”

8. Conferma che Client Authentication sia impostato su Send as Basic Auth header.

9. Fai clic su “Get New Access Token”, quindi su “Authorize app” come parte del processo “Sign-in with X”.

10. Fai clic sul pulsante “Proceed” e poi su “Use Token” per generare un token. 

11. Fai clic sul pulsante “Save” per salvare questi dettagli di configurazione.

Potresti ricevere un messaggio che indica che non hai effettuato l’accesso a X. In tal caso, accedi all’account X per conto del quale stai tentando di pubblicare all’interno di Postman.

Ora che questi dettagli OAuth 2.0 sono stati impostati a livello di cartella, apri ciascuno degli esempi, vai alla loro scheda “Authorization” e conferma che il Type sia impostato su “Inherit auth from parent.” 

Nota che questo token scadrà a breve e dovrai rigenerarlo facendo clic sul pulsante “Get New Access Token”. Facendolo, verrà avviato il processo “Sign-in with X” e verrà generato un nuovo token con cui effettuare le richieste.

​

Passaggio tre: recuperare gli eventi della conversazione dei Messaggi Diretti

Quando si recuperano gli eventi della conversazione dei Messaggi Diretti con questo endpoint, è necessario specificare un id della conversazione. L’id della conversazione fa parte del percorso dell’endpoint: https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

In Postman, vai alla scheda “Params” e inserisci l’id della conversazione per cui vuoi recuperare gli eventi nella sezione “Path Variables”.

L’impostazione sarà:

Key	Value
dm_conversation_id	1228393702244134912

Con questa conversazione specificata, il percorso risultante diventa https://api.x.com/2/dm_conversations/1582103724607971328/dm_events

Se fai clic sul pulsante “Send”, riceverai nella risposta i campi oggetto predefiniti dei Messaggi Diretti: id, text ed event_type. Sarà incluso anche un oggetto “meta” con il numero di risultati, insieme ai token di paginazione utilizzati per recuperare altri eventi, se disponibili.

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "ciao a entrambi, questa è una nuova conversazione di gruppo."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

Se desideri includere campi aggiuntivi, devi specificarli nella richiesta usando i parametri fields e/o expansions.

Per questo esercizio richiederemo set aggiuntivi di campi dell’oggetto dm_event:

1. I campi predefiniti dell’oggetto Direct Message: id, text ed event_type.

2. Campi aggiuntivi dell’oggetto Direct Message: dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets

In Postman, vai alla scheda “Params” e aggiungi la seguente coppia chiave:valore alla tabella “Query Params”:

Key	Value
dm_event.fields	dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

Ora dovresti vedere il seguente URL accanto al pulsante “Send”:

https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events?dm_event.fields=id,text,event_type,dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

​

Passaggio quattro: invia la richiesta e verifica la risposta

Una volta configurato tutto, fai di nuovo clic sul pulsante “Send” e riceverai una risposta simile a quella riportata di seguito. Nota che questa risposta include tutti i campi dm_event disponibili.

{
   "data": [
       {
           "text": "ciao a entrambi, questa è una nuova conversazione di gruppo.",
           "id": "1580705921830768647",
           "dm_conversation_id": "1580705921830768643",
           "event_type": "MessageCreate",
           "sender_id": "17200003",
           "created_at": "2022-10-13T23:43:54.000Z"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}