Guía de integración

Conceptos clave y prácticas recomendadas para integrar endpoints de consulta de MD

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

shellscript

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"

---

​

Paginación

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

cURL

shellscript

# 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"

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