Zum Hauptinhalt springen
Die Direct Messages-endpoints v2 führen Unterhaltungen und Unterhaltungsereignisse als zentrale X API-Objekte ein und unterscheiden zwischen 1-zu-1- und Gruppenunterhaltungen. 1-zu-1-Unterhaltungen haben immer zwei und nur zwei Teilnehmer, während Gruppenunterhaltungen zwei oder mehr Teilnehmer haben können und sich Mitgliedschaften ändern können. Diese Seite enthält Informationen zu mehreren Tools und Schlüsselkonzepten, die Sie kennen sollten, wenn Sie die Direct Messages-Lookup-endpoints in Ihr System integrieren. Wir haben die Seite in zwei Abschnitte unterteilt:

​
Zentrale Konzepte

​
Direct-Message-Unterhaltungen

Alle Direct Messages sind Teil einer Direct-Message-Unterhaltung. Diese Unterhaltungen können Eins-zu-eins- oder Gruppenunterhaltungen sein. Diese Einführung stellt die grundlegenden endpoint bereit, die benötigt werden, um Direct Messages zu erstellen und Ereignisse abzurufen, die mit Direct-Message-Unterhaltungen verknüpft sind. Alle Unterhaltungen haben eine eindeutige dm_conversation_id, und die Ereignisse, aus denen diese Unterhaltung besteht, haben jeweils eine eindeutige dm_event_id.   Die Direct-Message-Lookup-endpoint stellen Methoden zum Abrufen von Ereignissen bereit, die mit Unterhaltungen verknüpft sind. Diese GET endpoint werden verwendet, um die Nachrichten abzurufen, aus denen eine Unterhaltung besteht, und können bei Gruppenunterhaltungen verwendet werden, um nachzuvollziehen, wer Gruppenunterhaltungen beigetreten ist und sie verlassen hat. Diese erste Version der Direct Messages Lookup umfasst drei GET-Methoden:
  • GET /2/dm_conversations/with/:participant_id/dm_events - Ruft Direct-Message-Ereignisse ab, die mit einer Eins-zu-eins-Unterhaltung verknüpft sind. Der Pfadparameter :participant_id ist die numerische User-ID des Kontos, das die Unterhaltung mit dem authentifizierten Benutzer führt, der diese Anfrage stellt.  
  • GET /2/dm_conversations/:dm_conversation_id/dm_events - Ruft Direct-Message-Ereignisse ab, die einer bestimmten Unterhaltungs-ID zugeordnet sind, wie durch den Pfadparameter :dm_conversation_id angegeben. Sowohl Eins-zu-eins- als auch Gruppenunterhaltungs-IDs werden unterstützt.  
  • GET /2/dm_events - Ruft Direct-Message-Ereignisse ab, die dem authentifizierten Benutzer zugeordnet sind, einschließlich Eins-zu-eins- und Gruppenunterhaltungen. Ereignisse bis zu 30 Tage zurück sind verfügbar.  
Diese GET endpoint unterstützen alle das Abrufen von dm_events nach Ereignistyp mit einem event_types Abfrageparameter. Derzeit werden drei Unterhaltungsereignistypen unterstützt:
  • MessageCreate - Wird erstellt, wenn eine neue Direct Message erstellt wird. Dieses Ereignisobjekt kann die Uhrzeit und den Text der Nachricht enthalten, zusammen mit der Konto-ID des Absenders sowie der Unterhaltungs- und Ereignis-ID. 
  • ParticipantsJoin - Wird erstellt, wenn ein neuer Teilnehmer einer Gruppenunterhaltung beitritt. Dieses dm_event-Objekt enthält die ID des beitretenden Teilnehmers sowie die created_at Zeit und die sender_id des „invite“-Ereignisses. 
  • ParticipantsLeave - Wird erstellt, wenn ein Teilnehmer eine Unterhaltung verlässt. Dieses Ereignisobjekt enthält die ID des austretenden Teilnehmers sowie die Uhrzeit des Ereignisses. 
Weitere Informationen finden Sie in den Direct Messages Lookup API-Referenzen.

​
Gemeinsame Konversations- und Ereignis-IDs in v1.1 und v2

Ein wichtiger Aspekt ist, dass Konversations- und Ereignis-IDs in den Versionen v1.1 und v2 der X Platform gemeinsam verwendet werden. Das bedeutet, dass beide Versionen zusammen genutzt werden können. Beispielsweise bieten die Direct Messages v1.1 endpoints Methoden zum Abrufen eines einzelnen Ereignisses und zum Löschen von Ereignissen – Methoden, die in v2 noch nicht verfügbar sind. Da IDs in v1.1 und v2 einheitlich sind, können Sie v1.1-Anfragen anhand von IDs stellen, die von v2 bereitgestellt werden, oder indem Sie auf Konversations-IDs verweisen, die in Konversations-URLs in der X App angezeigt werden.  

​
Direct-Message-Ereignisfelder und -Expansions

Die X API v2 ermöglicht es Nutzern, mit einem Satz von Tools namens fields und expansions genau festzulegen, welche data sie aus der API zurückerhalten möchten. Beispielsweise unterstützen die Direct-Message-Lookup-Endpoints die folgenden dm_events-Felder:
  • id, event_type und text sind die Standardwerte für MessageCreate-Ereignisse.
  • id, event_type und participant_ids sind die Standardwerte für ParticipantsJoin- und ParticipantsLeave-Ereignisse.
  • dm_conversation_id und created_at sind für alle Ereignisse verfügbar.
  • attachments und referenced_tweets sind für MessageCreate-Ereignisse verfügbar.
  • sender_id ist für MessageCreate- und ParticipantsJoin-Ereignisse verfügbar.
  • participant_ids ist für ParticipantsJoin- und ParticipantsLeave-Ereignisse verfügbar.
Zusätzlich unterstützen die Direct-Message-Lookup-Endpoints die folgenden expansions:
  • sender_id – erweitert das User-Objekt der Person, die die Nachricht gesendet oder jemanden zur Unterhaltung eingeladen hat.
  • referenced_tweets.id – erweitert das Post-Objekt, wenn der Direct-Message-Text einen Link zu einem Post enthält.
  • attachments.media_keys – erweitert das Media-Objekt, wenn die Direct Message einen Medienanhang enthält.
  • participant_ids – erweitert das User-Objekt der Person, die einer Gruppenunterhaltung beigetreten ist oder sie verlassen hat.
Da expansions Posts-, Users- und Media-Objekte einschließen, können Sie auch die Abfrageparameter tweet.fields, user.fields und media.fields verwenden. Weitere Informationen finden Sie in unserem Leitfaden zur Verwendung von fields und expansions.

​
Konversationsereignistypen

Nachfolgend finden Sie Beispiel‑JSON‑Objekte für Direct Messages der Ereignistypen MessageCreate, ParticipantsJoin und ParticipantsLeave. Verfügbare dm_event‑Objektfelder: id, text, event_type, dm_conversation_id, created_at, sender_id, attachments, referenced_tweets, participant_ids. Weitere Details zur Auswahl dieser fields in Ihren Anfragen finden Sie im Abschnitt Fields and Expansion. Beispiel für ein MessageCreate‑Ereignis: Wenn alle dm_event‑Felder angegeben sind, sieht die Antwort für eine einfache Text‑Direct Message wie folgt aus: { "text": "Hi everyone.", "sender_id": "944480690", "dm_conversation_id": "1578398451921985538", "id": "1582838499983564806", "event_type": "MessageCreate", "created_at": "2022-10-19T20:58:00.000Z" } Beispiel für ein ParticipantsJoin‑Ereignis: Wenn alle dm_event‑Felder angegeben sind, sieht die Antwort beim Beitritt eines Teilnehmers zu einer Konversation wie folgt aus: { "participant_ids": [ "944480690" ], "sender_id": "17200003", "dm_conversation_id": "1578398451921985538", "id": "1582835469712138240", "event_type": "ParticipantsJoin", "created_at": "2022-10-19T20:45:58.000Z" } Beispiel für ein ParticipantsLeave‑Ereignis: Wenn alle dm_event‑Felder angegeben sind, sieht die Antwort beim Verlassen einer Konversation durch einen Teilnehmer wie folgt aus: { "participant_ids": [ "944480690" ], "dm_conversation_id": "1578398451921985538", "id": "1582838535115067392", "event_type": "ParticipantsLeave", "created_at": "2022-10-19T20:58:09.000Z" }

​
Authentifizierung

Alle X API v2 endpoint erfordern, dass Sie Ihre Anfragen mit einem Satz von Anmeldeinformationen authentifizieren, auch bekannt als Keys und Tokens. Alle Direct Messages sind privat und erfordern eine Benutzerautorisierung, um auf sie zuzugreifen. Diese Direct Message endpoint erfordern die Verwendung von OAuth 2.0 Authorization Flow with PKCE oder 1.0a User Context. Das bedeutet, dass Sie einen Satz von API Keys und Benutzer-Access Tokens verwenden müssen, um eine Anfrage erfolgreich auszuführen. Die Access Tokens müssen dem Benutzer zugeordnet sein, in dessen Auftrag Sie die Anfrage stellen. Wenn Sie einen Satz von Access Tokens für einen anderen Benutzer generieren möchten, muss dieser Ihre App mithilfe des 3-legged OAuth-Flow autorisieren oder authentifizieren. Bitte beachten Sie, dass der OAuth-Benutzerkontext anspruchsvoll sein kann. Wenn Sie mit dieser Authentifizierungsmethode nicht vertraut sind, empfehlen wir die Verwendung einer Library oder eines Tools wie Postman, um Ihre Anfragen korrekt zu authentifizieren. OAuth 2.0 Authorization Code mit PKCE ermöglicht eine präzisere Kontrolle über den Scope einer Anwendung sowie Autorisierungsabläufe über mehrere Geräte hinweg. Mit OAuth 2.0 können Sie spezifische, fein granulare Scopes auswählen, die Ihnen bestimmte Berechtigungen im Namen eines Benutzers gewähren. Die Direct Messages Lookup endpoint erfordern diese Scopes: dm.read, post.read, user.read Um OAuth 2.0 in Ihrer App zu aktivieren, müssen Sie es in den Authentifizierungseinstellungen Ihrer App aktivieren, die im Abschnitt App-Einstellungen des Entwicklerportals zu finden sind.

​
Entwicklerportal, Projects und Developer-Apps

Um einen Satz von Authentifizierungsdaten zu erhalten, die mit den X API v2 endpoints funktionieren, müssen Sie ein genehmigtes Developer-Konto besitzen, innerhalb dieses Kontos ein Project einrichten und innerhalb dieses Projects eine Developer-App erstellen. Anschließend finden Sie Ihre Keys und Tokens in Ihrer Developer-App. 

​
Rate Limits

Täglich stellen viele Tausend Entwickler Anfragen an die X API. Um das enorme Volumen dieser Anfragen zu verwalten, werden für jedes endpoint Rate Limits festgelegt, die die Anzahl der Anfragen begrenzen, die Sie im Namen Ihrer App oder eines authentifizierten Benutzers stellen können.  Die Direct Message Lookup-endpoints unterliegen Rate Limits auf Benutzerebene; das bedeutet, dass der authentifizierte Benutzer, in dessen Namen Sie die Anfrage stellen, mit Ihrer X App nur eine bestimmte Anzahl von Anfragen ausführen kann. Es gibt ein Benutzer-Rate Limit von 300 Anfragen pro 15 Minuten für die GET-Methoden. Diese Rate Limits werden über die GET-endpoints hinweg geteilt.  Diese Endpoints verwenden Paginierung, damit Antworten schnell zurückgegeben werden. In Fällen, in denen mehr Ergebnisse vorliegen, als in einer einzelnen Antwort gesendet werden können (bis zu 100 Ereignisse), müssen Sie paginieren. Verwenden Sie den Parameter max_results, um festzulegen, wie viele Ergebnisse pro Seite zurückgegeben werden, und den Parameter pagination_token, um die nächste Ergebnisseite abzurufen. Weitere Informationen finden Sie in unserem Leitfaden zur Paginierung. Nützliche Tools Hier sind einige nützliche Tools, die wir Ihnen empfehlen zu erkunden, wenn Sie mit den Direct-Messages-Lookup-Endpoints arbeiten:  Postman Postman ist ein hervorragendes Tool, mit dem Sie einen Endpoint testen können. Jede Postman-Anfrage umfasst alle Pfad- und Body-Parameter, damit Sie schnell verstehen, was verfügbar ist. Weitere Informationen zu unseren Postman-Collections finden Sie auf unserer Seite Using Postman.  Codebeispiele Python-Beispielcode für die v2 Direct-Messages-Endpoints ist in unserem Repository X API v2 sample code GitHub verfügbar. Der Ordner „Manage-Direct-Messages“ enthält Beispiele für die POST-Methoden, und der Ordner „Direct-Messages-lookup“ enthält Beispiele für die GET-Methoden. XDev Software Development Kits (SDKs) Diese Bibliotheken werden für die v2 Direct-Messages-Endpoints aktualisiert und sollten bald bereit sein: Bibliotheken von Drittanbietern Es gibt eine wachsende Anzahl von Bibliotheken von Drittanbietern, die von unserer Community entwickelt wurden. Diese Bibliotheken sollen Ihnen den Einstieg erleichtern, und mehrere werden voraussichtlich bald die v2 Direct-Messages-Endpoints unterstützen. Sie können eine Bibliothek, die mit den v2 Endpoints funktioniert, finden, indem Sie nach dem entsprechenden Versions-Tag suchen.
⌘I