Schnellstart

​

Erste Schritte mit den Direct Message-Endpoints für Verwaltung

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

Bitte 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 diese Anleitung 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:

• Melden Sie sich für ein Developer-Konto an 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 Zugangsdaten zu generieren. Stellen Sie sicher, dass Sie alle Zugangsdaten an einem sicheren Ort speichern.

​

Schritte zum Verwalten von Direktnachrichtenanfragen

In diesem Beispiel erstellen wir mit einer einzigen Anfrage eine neue Gruppenunterhaltung und fügen die 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 Manage-Direct-Message-Endpunkten zu arbeiten, verwenden wir das Tool Postman, um den Prozess zu vereinfachen. Eine von XDev erstellte Sammlung von Beispielanfragen an die X API v2 wird genutzt, um sechs Endpunkte zu erkunden, die zum Erstellen neuer Direct Messages und zum Auflisten von Direct-Message-Unterhaltungsereignissen dienen.

Obwohl ein Großteil der Sammlung vorausgefüllt ist, gibt es einige Angaben, die Sie bereitstellen müssen und die auf der X App basieren, mit der diese API-Anfragen ausgeführt werden. Zunächst laden bzw. aktualisieren wir 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“. Der Reiter „Authorization“ dieses Ordners wurde, wo möglich, vorausgefüllt, und Sie können einige Einstellungen aktualisieren, um die Authentifizierungsdetails Ihrer X App zu hinterlegen. Dieser Ordner enthält auch drei Endpunkte zum Erstellen neuer Direct Messages. Beachten Sie, dass es außerdem einen Ordner „Direct Message lookup“ mit drei verfügbaren Endpunkten zum Abrufen von Direct-Message-Unterhaltungsereignissen gibt, einschließlich des Sendens und Empfangens von Nachrichten sowie wenn Teilnehmer Unterhaltungen beitreten oder sie verlassen. 

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

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

Schritt zwei: Authentifizieren Sie Ihre Anfrage

Um korrekt eine Anfrage an die X API zu stellen, müssen Sie verifizieren, dass Sie die Berechtigung dazu haben. Für eine erfolgreiche Anfrage an diesen Endpunkt 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 Anforderungsebene festlegen. Hier konfigurieren wir die Authentifizierungsdetails auf Ordnerebene.

Navigieren Sie zum Ordner „Manage Direct Messages“, wählen Sie den Reiter „Authorization“ und bestätigen Sie, dass Type auf „OAuth 2.0“ gesetzt ist und „Add auth data to“ auf „Request Headers“ steht. Stellen Sie im Abschnitt „Current Token“ sicher, dass „header Prefix“ auf Bearer gesetzt ist.  

So konfigurieren und generieren Sie ein neues Token:

1. Erstellen Sie einen Token-Namen, z. B. „Manage DMs“.

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

3. Setzen Sie Ihre Callback URL. Aktualisieren Sie Ihre Callback URL so, dass sie exakt der Callback URL entspricht, 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 gesetzt ist.
   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 und 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 klicken Sie 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 diese Fehlermeldung erhalten, müssen Sie sich bei dem X Konto anmelden, 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 „Authorization“-Tab 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“ neu generieren müssen. Ein Klick darauf startet den „Sign-in with X“-Prozess und erzeugt ein neues Token, mit dem Sie Anfragen stellen können.

​

Schritt drei: Geben Sie die Teilnehmer der Direct-Message-Unterhaltung und den Nachrichteninhalt an

Navigieren Sie zur Registerkarte „Body“ und nehmen Sie Änderungen am Beispiel-JSON-Objekt vor. Setzen Sie das Attribut participant_ids auf die Accounts, an die Sie die Direct Message senden möchten.

{ "message": {"text": "Hello to just you two, this is a new group conversation."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

​

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

Sobald alles eingerichtet ist, klicken Sie auf die Schaltfläche „Send“, und Sie erhalten eine ähnliche Antwort wie in der unten stehenden Beispielantwort. Hinweis: Wenn Ihr Token seit der oben erfolgten Erstellung abgelaufen ist, können Sie zum Reiter „Authorization“ des Ordners zurückkehren und auf „Get New Access Token“ klicken, um ein neues Token zu erstellen.

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

Wenn das zurückgegebene „data“-Antwortobjekt sowohl eine dm_conversation_id als auch eine dm_event_id enthält, haben Sie erfolgreich eine neue Direct-Message-Unterhaltung erstellt. Um mit dem Abrufen der zu dieser Unterhaltung gehörenden Events zu beginnen, wechseln Sie zum Schnellstart-Leitfaden für die Direct-Message-Abfrage.

​

Schritt fünf: Fügen Sie dieser Gruppenkonversation eine weitere Nachricht hinzu

Wählen Sie nun das Beispiel „Add DM to conversation“ und anschließend den Tab „Params“. Aktualisieren Sie unter „Path Variables“ die dm_conversation_id auf die ID der Konversation, die Sie oben erstellt haben.

Key	Value
dm_conversation_id	1582103724607971328

Mit dieser Konversations-ID ergibt sich folgender Anforderungspfad: https://api.x.com/2/dm_conversations/1582103724607971328/messages

Aktualisieren Sie außerdem den Tab „Body“ mit dem JSON-Request, der den zu sendenden Nachrichtentext enthält:

{
   "text": "Neue Nachricht zur Gruppenunterhaltung hinzufügen..."
}

Sobald alles eingerichtet ist, klicken Sie auf „Send“, und Sie erhalten eine Antwort, die der folgenden Beispielantwort ähnelt:

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