Schnellstart

​

Erste Schritte mit den Direct-Message-Management-endpoints

Dieser Schnellstartleitfaden hilft Ihnen, Ihre erste Anfrage an die Direct-Message-endpoints mit Postman zu stellen, einem Tool zum Verwalten und Ausführen von HTTP-Anfragen. Weitere Informationen zu unseren Postman-Collections finden Sie im Leitfaden Using Postman.

Besuchen Sie unser GitHub-Repository X API v2 sample code, wenn Sie Python-basierte Beispiele ansehen möchten. Außerdem werden die offiziellen X Developer Platform Software Development Kits (SDKs) aktualisiert, um diese Direct-Message-endpoints zu unterstützen.  

Voraussetzungen

Um diesen Leitfaden abzuschließen, benötigen Sie einen Satz von Keys und Tokens, um Ihre Anfrage zu authentifizieren. Sie können diese Keys und Tokens generieren, indem Sie die folgenden Schritte ausführen:

• Registrieren Sie sich für ein Developer-Konto und lassen Sie es genehmigen.
• Erstellen Sie ein Project und eine zugehörige Developer-App im Entwicklerportal.
• Navigieren Sie zur „Keys and tokens“-Seite Ihrer App, um die erforderlichen Anmeldedaten zu generieren. Speichern Sie alle Anmeldedaten an einem sicheren Ort.

​

Schritte zum Erstellen von Direct-Message-Lookup-Anfragen

In diesem Beispiel erstellen wir in einer einzigen Anfrage eine neue Gruppenunterhaltung und fügen ihre erste Nachricht hinzu. Anschließend fügen wir der erstellten Unterhaltung eine zweite Nachricht hinzu.

​

Schritt eins: Beginnen Sie mit einem Tool oder einer Bibliothek

Um mit den Endpoints zum Verwalten von Direct Messages zu arbeiten, verwenden wir das Tool Postman, um den Prozess zu vereinfachen. Eine von XDevelopers erstellte Sammlung von Beispielanfragen für die X API v2 wird genutzt, um sechs Endpoints zu erkunden, die zum Erstellen neuer Direct Messages und zum Auflisten von Ereignissen in Direct-Message-Unterhaltungen dienen.

Obwohl der Großteil der Sammlung vorausgefüllt ist, gibt es einige Details, die Sie anhand der X App angeben müssen, die zum Ausführen dieser API-Anfragen erstellt wurde. Laden bzw. aktualisieren wir zunächst die Sammlung.

Um die X API v2-Postman-Sammlung in Ihre Umgebung zu laden, klicken Sie bitte auf die folgende Schaltfläche:

X API v2 zu Postman hinzufügen

Sobald Sie die X API v2-Sammlung in Postman geladen haben, navigieren Sie zum Ordner „Manage Direct Messages“. Die Registerkarte Authorization dieses Ordners wurde, wo möglich, vorausgefüllt. Sie müssen einige Einstellungen aktualisieren, um die Authentifizierungsdetails Ihrer X App zu hinterlegen.

Dieser Ordner enthält außerdem drei Endpoints zum Erstellen neuer Direct Messages. Beachten Sie, dass es auch einen Ordner „Direct Message lookup“ mit drei verfügbaren Endpoints zum Abrufen von Ereignissen in Direct-Message-Unterhaltungen gibt, darunter das Senden und Empfangen von Nachrichten sowie das Beitreten und Verlassen von Teilnehmenden.

Da das Erstellen von Gruppenkonversationen eine neue Funktion der X API v2 ist, konzentriert sich dieses Beispiel darauf. Wir arbeiten mit dem Beispiel „New group DM and conversation“. Mit dieser Anfrage erstellen wir eine Direct-Message-Gruppenkonversation.

Der nächste Schritt besteht darin, sich beim Endpoint zu authentifizieren.

​

Schritt zwei: Authentifizieren Sie Ihre Anfrage

Um eine Anfrage an die X API korrekt zu stellen, müssen Sie nachweisen, dass Sie dazu berechtigt sind. Für eine erfolgreiche Anfrage an dieses endpoint verwenden wir den OAuth 2.0 Authorization Code Flow mit PKCE. Sie können in Postman ein access token generieren. 

Mit Postman können Sie die Authentifizierungsmethode auf Ordnerebene oder auf Anfrageebene festlegen. Hier konfigurieren wir die Authentifizierungsdetails auf Ordnerebene. Navigieren Sie zum Ordner “Mange Direct Messages”, wählen Sie die Registerkarte “Authorization” und bestätigen Sie, dass der Type auf „OAuth 2.0“ gesetzt ist und “Add auth data to” auf “Request Headers” eingestellt ist. Stellen Sie im Abschnitt “Current Token” sicher, dass der “header Prefix” auf Bearer gesetzt ist.  

So konfigurieren und generieren Sie ein neues Token:

1. Erstellen Sie einen Token-Namen, z. B. „DM lookup“.

2. Bestätigen Sie, dass Grant Type auf Authorization Code (with PKCE) gesetzt ist.

3. Legen Sie Ihre Callback URL fest. Sie sollten Ihre Callback URL so aktualisieren, dass sie exakt mit der Callback URL übereinstimmt, die Ihrer Anwendung im v2 Dev Portal zugeordnet ist. Bei der in diesem Beispiel verwendeten X App ist die Callback URL auf – https://www.example.com. gesetzt (Beachten Sie, dass dies exakt übereinstimmen muss; https://example.com würde nicht funktionieren.) 

4. Bestätigen Sie, dass Auth URL auf https://x.com/i/oauth2/authorize gesetzt ist.

5. Bestätigen Sie, dass Access Token URL auf https://api.x.com/2/oauth2/token.Client ID - Kopieren Sie die OAuth 2.0 client ID aus dem Entwicklerportal und fügen Sie sie ein Client Secret - Dies benötigen Sie nur, wenn Sie einen App-Typ verwenden, der ein vertraulicher Client ist. Falls ja, kopieren Sie das OAuth 2.0 Client Secret aus dem Entwicklerportal und fügen Sie es ein. 

6. Bestätigen Sie, dass Scope auf dm.read dm.write tweet.read users.read gesetzt ist.

7. Bestätigen Sie, dass State auf „state“ gesetzt ist.

8. Bestätigen Sie, dass Client Authentication auf Send as Basic Auth header gesetzt ist.

9. Klicken Sie auf „Get New Access Token“ und dann im Rahmen des „Sign-in with X“-Prozesses auf “Authorize app”.

10. Klicken Sie auf die Schaltfläche “Proceed” und anschließend auf “Use Token”, um ein Token zu generieren. 

11. Klicken Sie auf die Schaltfläche “Save”, um diese Konfigurationsdetails zu speichern.

Es kann sein, dass Sie eine Meldung erhalten, dass Sie nicht bei X angemeldet sind. Wenn Sie diesen Fehler erhalten, müssen Sie sich in das X-Konto einloggen, in dessen Namen Sie innerhalb von Postman posten möchten.

Nachdem diese OAuth 2.0-Details auf Ordnerebene festgelegt wurden, navigieren Sie zu jedem der Beispiele und deren Registerkarte “Authorization” und bestätigen Sie, dass deren Type auf “Inherit auth from parent” gesetzt ist. 

Beachten Sie, dass dieses Token bald abläuft und Sie es durch Klicken auf die Schaltfläche “Get New Access Token” erneut generieren müssen. Durch Klicken darauf wird der „Sign-in with X“-Prozess gestartet und ein neues Token generiert, mit dem Sie Anfragen stellen können.

​

Schritt drei: Konversationsereignisse für Direct Messages abrufen

Wenn Sie Konversationsereignisse für Direct Messages mit diesem endpoint abrufen, müssen Sie eine Konversations-ID angeben. Die Konversations-ID ist Teil des endpoint-Pfads: https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

Navigieren Sie in Postman zur Registerkarte „Params“ und geben Sie die ID der Konversation, für die Sie Ereignisse abrufen möchten, im Abschnitt „Path Variables“ ein.

Die Einstellung lautet:

Key	Value
dm_conversation_id	1228393702244134912

Mit dieser angegebenen Konversation ergibt sich folgender Pfad: https://api.x.com/2/dm_conversations/1582103724607971328/dm_events

Wenn Sie auf die Schaltfläche „Send“ klicken, erhalten Sie in Ihrer Antwort die standardmäßigen Objekt-fields für Direct Messages: id, text und event_type. Außerdem gibt es ein „meta“-Objekt mit der Anzahl der Ergebnisse sowie Paginierungs-Token, die zum Abrufen weiterer Ereignisse verwendet werden, sofern verfügbar.

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "Hallo ihr beiden, das ist eine neue Gruppenunterhaltung."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

Wenn Sie zusätzliche fields erhalten möchten, müssen Sie diese fields in Ihrer Anfrage über die Parameter fields und/oder expansions angeben.

Für diese Übung fordern wir zusätzliche Sets von fields des dm_event-Objekts an:

1. Die Standardfelder des Direct-Message-Objekts: id, text und event_type.

2. Zusätzliche Felder des Direct-Message-Objekts: dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets

Navigieren Sie in Postman zur Registerkarte „Params“ und fügen Sie der Tabelle „Query Params“ das folgende key:value-Paar hinzu:

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

Neben der Schaltfläche „Send“ sollten Sie nun die folgende URL sehen:

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

​

Schritt vier: Senden Sie Ihre Anfrage und überprüfen Sie die Antwort

Sobald alles eingerichtet ist, klicken Sie erneut auf die Schaltfläche „Send“, und Sie erhalten eine Antwort, die der unten stehenden ähnlich ist. Beachten Sie, dass diese Antwort alle verfügbaren dm_event fields enthält.

{
   "data": [
       {
           "text": "Hallo ihr beiden, das ist eine neue Gruppenunterhaltung.",
           "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"
   }
}