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 Utilizzo di Postman.

Consulta il nostro repository GitHub X API v2 sample code se vuoi esaminare esempi in Python. Inoltre, gli SDK (software development kit) ufficiali della X Developer Platform 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 tua richiesta. Puoi generare queste chiavi e token seguendo questi passaggi:

• Registrati per un account sviluppatore e ottieni l’approvazione.
• Crea un Project e una App sviluppatore 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 gestire le richieste dei Messaggi Diretti

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

​

Primo passaggio: Inizia 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. Una raccolta di richieste di esempio per la X API v2, redatta da XDev, verrà utilizzata per esplorare sei endpoint impiegati per creare nuovi Messaggi Diretti e per elencare gli eventi delle conversazioni dei 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 dove possibile e puoi aggiornare alcune impostazioni per condividere i dettagli di autenticazione della tua X App. Questa cartella contiene anche tre endpoint per la creazione di nuovi Messaggi Diretti. Nota che è presente anche una cartella “Direct Message lookup” con tre endpoint disponibili per il recupero degli eventi delle conversazioni dei Messaggi Diretti, inclusi l’invio e la ricezione dei messaggi e i momenti in cui i partecipanti alla conversazione si uniscono o lasciano.

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

Il passaggio successivo è autenticarsi con l’endpoint.

Secondo passaggio: Autentica la tua richiesta

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

Con Postman puoi impostare il metodo di autenticazione a livello di cartella o a livello di richiesta. Qui configureremo i dettagli di autenticazione a livello di cartella.

Naviga alla cartella “Manage Direct Messages”, seleziona la scheda “Authorization” e conferma che 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 nome per il token, ad esempio “Manage DMs”.

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

3. Imposta la Callback URL. Devi aggiornarla affinché 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 impostato su https://x.com/i/oauth2/authorize.

5. Conferma che Access Token URL sia impostato 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 utilizzando un tipo di App che è un client confidenziale. 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 e 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 fai clic 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 cercando di pubblicare direttamente in Postman.

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

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

​

Passaggio tre: specificare i partecipanti alla conversazione di Messaggi Diretti e il contenuto del messaggio

Vai alla scheda “Body” e aggiorna l’oggetto JSON di esempio. Imposta l’attributo participant_ids sugli account a cui vuoi inviare il Messaggio Diretto.

{ "message": {"text": "Ciao a voi due, questa è una nuova conversazione di gruppo."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

​

Passaggio quattro: invia la richiesta e verifica la risposta

Dopo aver configurato tutto, fai clic sul pulsante “Send” e riceverai una risposta simile all’esempio riportato qui sotto. Promemoria: se il tuo token è scaduto da quando lo hai creato, puoi tornare alla scheda Authorization della cartella e fare clic su “Get New Access Token” per generare un nuovo token.

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582103724607971332"
   }
}

Se l’oggetto “data” nella risposta contiene un dm_conversation_id e un dm_event_id, la nuova conversazione di Messaggi Diretti è stata creata correttamente. Per iniziare a consultare gli eventi associati a questa conversazione, vai alla guida Avvio rapido per la ricerca dei Messaggi Diretti.

​

Passaggio cinque: aggiungi un altro messaggio a quella conversazione di gruppo

Ora seleziona l’esempio “Add DM to conversation” e poi la scheda “Params”. In “Path Variables”, aggiorna dm_conversation_id con l’ID della conversazione che hai creato sopra.

Chiave	Valore
dm_conversation_id	1582103724607971328

Utilizzando questo ID conversazione, il percorso della richiesta sarà: https://api.x.com/2/dm_conversations/1582103724607971328/messages

Aggiorna anche la scheda “Body” con il JSON della richiesta contenente il testo del messaggio che desideri inviare:

{
   "text": "Aggiunta di un nuovo messaggio alla nostra conversazione di gruppo..."
}

Una volta completata la configurazione, fai clic sul pulsante “Send” e riceverai una risposta simile al seguente esempio:

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}