Zum Hauptinhalt springen
Die Direct Messages-endpoints v2 führen Unterhaltungen und Unterhaltungsereignisse als zentrale X API-Objekte ein und unterscheiden zwischen Eins-zu-eins- und Gruppenunterhaltungen. Eins-zu-eins-Unterhaltungen haben stets zwei, und nur zwei, Teilnehmende, während Gruppenunterhaltungen zwei oder mehr Teilnehmende 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 Manage Direct Messages-endpoints in Ihr System integrieren. Wir haben die Seite in zwei Abschnitte unterteilt: Schlüsselkonzepte

​
Direct-Message-Unterhaltungen

Alle Direct Messages sind Teil einer Direct-Message-Unterhaltung. Diese Unterhaltungen können Eins-zu-eins- oder Gruppenunterhaltungen sein. Dieser Launch stellt die grundlegenden endpoint(s) 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 Manage Direct Message endpoint(s) bieten drei POST-Methoden, um neue Nachrichten zu erstellen und sie Unterhaltungen hinzuzufügen:
  • POST /2/dm_conversations/with/:participant_id/messages - Erstellt eine Eins-zu-eins-Direct Message. Diese Methode fügt die Nachricht entweder einer bestehenden Eins-zu-eins-Unterhaltung hinzu oder erstellt eine neue. Der Pfadparameter :participant_id ist die User-ID des Kontos, das die Nachricht erhält.  Hier ist ein Beispiel für einen JSON-Request-Body zum Senden einer Eins-zu-eins-Direct Message:
{
   "text": "Hallo, nur an dich. Dies wird als neue Unterhaltung angezeigt, falls wir uns noch nie geschrieben haben, oder wird zu unserem bestehenden Thread hinzugefügt. "
}
  • POST /2/dm_conversations - Erstellt eine neue Gruppenkonversation und fügt ihr eine Direct Message hinzu. Diese Anfragen erfordern eine Liste der Konversationsteilnehmenden. Beachten Sie, dass Sie mehrere Konversationen mit derselben Teilnehmendenliste erstellen können. Diese Anfragen liefern stets eine neue Konversations-ID. Unten finden Sie ein Beispiel für einen JSON-Anfragetext zum Erstellen einer neuen Gruppenkonversation und zum Hinzufügen einer Direct Message. Beachten Sie, dass hierfür ein Feld “conversation_type” erforderlich ist und dieses auf “Group” gesetzt sein muss (Groß-/Kleinschreibung beachten).
{
   "message": {"text": "Hallo an euch beide, dies ist eine neue Gruppenunterhaltung."},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - Erstellt eine Direct Message und fügt sie einer bestehenden Unterhaltung hinzu. Der Pfadparameter :dm_conversation_id ist die ID der Unterhaltung, der die Nachricht hinzugefügt wird. Diese Methode kann verwendet werden, um einer Eins-zu-eins- oder Gruppenunterhaltung eine Nachricht hinzuzufügen. Hier ist ein Beispiel für einen JSON-Anfragetext, um eine Direct Message an Eins-zu-eins- und Gruppenunterhaltungen zu senden:
{
   "text": "Hier ist eine neue Nachricht."
}
Diese POST-Methoden unterstützen das Anhängen eines einzelnen Mediums. POST-Anfragetexte müssen entweder „text“, „attachments“ oder beide Felder enthalten. Das Attribut „text“ ist erforderlich, wenn das Feld „attachments“ nicht enthalten ist, und das Feld „attachments“ ist erforderlich, wenn das Feld „text“ nicht enthalten ist. Weitere Informationen finden Sie im nächsten Abschnitt. Weitere Informationen finden Sie in den API-Referenzen zu Direct Messages verwalten.

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

Ein wichtiges Konzept 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. Diese Methoden sind in v2 noch nicht verfügbar. Da IDs in v1.1 und v2 identisch sind, können Sie v1.1-Anfragen anhand von in v2 bereitgestellten IDs stellen oder Konversations-IDs verwenden, die in Konversations-URLs in der X App angezeigt werden.  

​
Einbinden von Medienanhängen und Verweisen auf Posts

Die Manage-Direct-Message-endpoints unterstützen das Anhängen eines einzelnen Mediums (Foto, Video oder GIF). Das Anhängen von Medien erfordert eine Medien-id, die vom v1.1-endpoint Upload media generiert wurde. Der authentifizierte Nutzer, der die Direct Message postet, muss das Medium ebenfalls hochgeladen haben. Nach dem Upload steht das Medium 24 Stunden lang zur Einbindung in die Nachricht zur Verfügung. Zur Veranschaulichung, wie Medien eingebunden werden, folgt ein Beispiel für einen JSON-Anfragetext: 
{
 "text": "Hier ist ein Foto...",
 "attachments": [{"media_id": "1583157113245011970}]
}
Das resultierende MessageCreate-Ereignis enthält die folgenden metadata: 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
Posts können auch eingebunden werden, indem die Post-URL in den Nachrichtentext eingefügt wird. Zur Veranschaulichung, wie Posts in Nachrichten eingebunden werden können, folgt ein Beispiel für einen JSON-Anfragetext: 
{
 "text": "Hier ist der Tweet, über den ich gesprochen habe: https://x.com/SnowBotDev/status/1580559079470145536"
}
Das resultierende MessageCreate-Ereignis enthält die folgenden metadata: 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
Authentifizierung

Alle X API v2 endpoints erfordern, dass Sie Ihre Anfragen mit einem Satz von Anmeldedaten authentifizieren, auch bekannt als Keys und Tokens. Alle Direct Messages sind privat und erfordern eine Benutzerautorisierung, um darauf zuzugreifen.  Diese Direct Message endpoints 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 erfolgreiche Anfrage zu stellen. Die Access Tokens müssen dem Benutzer zugeordnet sein, in dessen Auftrag Sie anfragen. 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 mitunter knifflig 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 bessere Kontrolle über den Umfang (Scope) einer Anwendung und über Autorisierungsabläufe auf mehreren Geräten. OAuth 2.0 erlaubt Ihnen, spezifische, fein granulare Scopes auszuwählen, die Ihnen bestimmte Berechtigungen im Namen eines Benutzers geben. Die Direct Messages Lookup endpoints erfordern diese Scopes: dm.write, dm.read, tweet.read, user.read. Um OAuth 2.0 in Ihrer App zu aktivieren, müssen Sie es in den Authentifizierungseinstellungen Ihrer App im Bereich App-Einstellungen des Entwicklerportals aktivieren.

​
Entwicklerportal, Projects und Developer-Apps

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

​
Rate Limits

Täglich senden viele Tausend Entwickler Anfragen an die X API. Um das enorme Volumen dieser Anfragen zu bewältigen, werden für jedes endpoint Rate Limits festgelegt, die die Anzahl der Anfragen beschränken, die Sie im Namen Ihrer App oder eines authentifizierten Nutzers stellen können.  Die Manage Direct Message endpoints unterliegen Rate Limits sowohl auf Nutzer- als auch auf X App-Ebene. Das bedeutet, dass der authentifizierte Nutzer, in dessen Namen Sie die Anfrage stellen, mit Ihrer X App nur eine bestimmte Anzahl von Nachrichten senden kann. Zusätzlich gibt es ein tägliches Limit dafür, wie viele Direct Messages von Ihrer X App gesendet werden können.  Es gibt ein Nutzer-Rate Limit von 200 Anfragen/Nachrichten pro 15 Minuten für die POST-Methoden. Nutzer sind außerdem auf 1000 Direct Messages pro 24 Stunden begrenzt. Zusätzlich haben X Apps ein Limit von 15000 Nachrichten pro 24 Stunden. Diese Rate Limits werden über die POST endpoints hinweg geteilt.  Hilfreiche Tools Hier sind einige hilfreiche Tools, die wir Ihnen empfehlen zu erkunden, während Sie mit den Direct Messages Lookup endpoints arbeiten:  Postman Postman ist ein leistungsfähiges Tool, mit dem Sie ein endpoint testen können. Jede Postman-Anfrage umfasst sämtliche Pfad- und Body-Parameter, damit Sie schnell verstehen, was verfügbar ist. Um mehr über unsere Postman-Collections zu erfahren, besuchen Sie bitte unsere 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 finden, die mit den v2 endpoints funktioniert, indem Sie nach dem passenden Versions-Tag suchen.
⌘I