Guía de integración

Esta guía cubre los conceptos clave que necesitas para integrar los endpoints de consulta de Mensajes Directos en tu aplicación.

Autenticación

Los endpoints de MD (Mensajes Directos) requieren autenticación de usuario para acceder a conversaciones privadas:

Método	Descripción
OAuth 2.0 Authorization Code with PKCE	Recomendado
OAuth 1.0a User Context	Soporte heredado

La autenticación App-Only no se admite. Todos los mensajes directos son privados.

Permisos requeridos (OAuth 2.0)

Permiso	Requerido para
`dm.read`	Lectura de eventos de mensajes directos (MD)
`tweet.read`	Requerido junto con dm.read
`users.read`	Requerido junto con dm.read

Tipos de conversación

Uno a uno

Siempre tiene exactamente dos participantes. Formato de id de la conversación: {smaller_user_id}-{larger_user_id}

Grupo

Dos o más participantes. La lista de miembros puede cambiar con el tiempo.

Tipos de eventos

Evento	Descripción	Campos clave
`MessageCreate`	Se envió un mensaje	`text`, `sender_id`
`ParticipantsJoin`	Un usuario se unió al grupo	`participant_ids`, `sender_id`
`ParticipantsLeave`	Un usuario abandonó el grupo	`participant_ids`

Ejemplos de eventos

MessageCreate

{
  "id": "1582838499983564806",
  "event_type": "MessageCreate",
  "text": "Hola a todos.",
  "sender_id": "944480690",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:00.000Z"
}

ParticipantsJoin

{
  "id": "1582835469712138240",
  "event_type": "ParticipantsJoin",
  "participant_ids": ["944480690"],
  "sender_id": "17200003",
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:45:58.000Z"
}

ParticipantsLeave

{
  "id": "1582838535115067392",
  "event_type": "ParticipantsLeave",
  "participant_ids": ["944480690"],
  "dm_conversation_id": "1578398451921985538",
  "created_at": "2022-10-19T20:58:09.000Z"
}

Campos y expansions

Campos predeterminados

Tipo de evento	Campos predeterminados
MessageCreate	`id`, `event_type`, `text`
ParticipantsJoin/Leave	`id`, `event_type`, `participant_ids`

Campos disponibles

Campo	Descripción	Eventos
`dm_conversation_id`	ID de la conversación	Todos
`created_at`	Marca de tiempo del evento	Todos
`sender_id`	Quién envió/invitó	MessageCreate, Join
`attachments`	Archivos multimedia adjuntos	MessageCreate
`referenced_tweets`	Publicaciones compartidas	MessageCreate

Expansions disponibles

Expansión	Devuelve
`sender_id`	Objeto de usuario del remitente
`participant_ids`	Objetos de usuario de los participantes
`attachments.media_keys`	Objetos de medios
`referenced_tweets.id`	Objetos de Publicación

Ejemplo con expansions

cURL

curl "https://api.x.com/2/dm_events?\
dm_event.fields=created_at,sender_id,attachments&\
expansions=sender_id,attachments.media_keys&\
user.fields=username,profile_image_url&\
media.fields=url,type" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# Obtener eventos de DM con expansions
for page in client.dm_events.list(
    dm_event_fields=["created_at", "sender_id", "attachments"],
    expansions=["sender_id", "attachments.media_keys"],
    user_fields=["username", "profile_image_url"],
    media_fields=["url", "type"],
    max_results=100
):
    for event in page.data:
        print(f"Event: {event.event_type} - {event.text}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

const paginator = client.dmEvents.list({
  dmEventFields: ["created_at", "sender_id", "attachments"],
  expansions: ["sender_id", "attachments.media_keys"],
  userFields: ["username", "profile_image_url"],
  mediaFields: ["url", "type"],
  maxResults: 100,
});

for await (const page of paginator) {
  page.data?.forEach((event) => {
    console.log(`Event: ${event.event_type} - ${event.text}`);
  });
}

Paginación

Los eventos de MD (mensajes directos) se devuelven en orden cronológico inverso (los más recientes primero):

cURL

# Primera solicitud
curl "https://api.x.com/2/dm_events?max_results=100" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

# Solicitud posterior con token de paginación
curl "https://api.x.com/2/dm_events?max_results=100&pagination_token=NEXT_TOKEN" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_USER_ACCESS_TOKEN")

# El SDK maneja la paginación automáticamente
all_events = []

for page in client.dm_events.list(max_results=100):
    if page.data:
        all_events.extend(page.data)

print(f"Se encontraron {len(all_events)} eventos de MD")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ accessToken: "YOUR_USER_ACCESS_TOKEN" });

async function getAllDMEvents() {
  const allEvents = [];

  // El SDK maneja la paginación automáticamente
  const paginator = client.dmEvents.list({ maxResults: 100 });

  for await (const page of paginator) {
    if (page.data) {
      allEvents.push(...page.data);
    }
  }

  return allEvents;
}

// Uso
const events = await getAllDMEvents();
console.log(`Se encontraron ${events.length} eventos de MD`);

Están disponibles eventos de hasta 30 días de antigüedad.

Compatibilidad de id con v1.1

Los id de conversación y de evento se comparten entre los endpoints de v1.1 y v2. Esto significa que puedes:

Usar v2 para obtener eventos y luego usar v1.1 para eliminar mensajes específicos
Hacer referencia a id de conversación desde URL de x.com en solicitudes a la API

Próximos pasos

Inicio rápido

Realiza tu primera solicitud de consulta de MD

Enviar MD

Envía mensajes directos

Referencia de la API

Documentación completa del endpoint

Código de ejemplo

Ejemplos de código funcional

Descripción general

Publicaciones

Usuarios

Mensajes directos

Me gusta

Listas

Spaces

Comunidades

Notas de la comunidad

Tendencias

Noticias

Contenido multimedia

Actividad en X

Uso

Conexiones de streaming

Cumplimiento

Enterprise v2

Flujos de Me gusta

GNIP 2.0

Guía de integración

Autenticación

Permisos requeridos (OAuth 2.0)

Tipos de conversación

Uno a uno

Grupo

Tipos de eventos

Ejemplos de eventos

Campos y expansions

Campos predeterminados

Campos disponibles

Expansions disponibles

Ejemplo con expansions

Compatibilidad de id con v1.1

Próximos pasos

Inicio rápido

Enviar MD

Referencia de la API

Código de ejemplo