Saltar al contenido principal
Los endpoints de Mensajes Directos v2 introducen las conversaciones y los eventos de conversación como objetos fundamentales de la X API, y diferencian entre conversaciones 1-1 y de grupo. Las conversaciones 1-1 siempre tienen dos, y solo dos, participantes, mientras que las conversaciones de grupo pueden tener dos o más y membresías que pueden cambiar.    Esta página contiene información sobre varias herramientas y conceptos clave que debes conocer al integrar los endpoints de consulta de Mensajes Directos en tu sistema. Hemos dividido la página en dos secciones:

​
Conceptos clave

​
Conversaciones de Mensajes Directos

Todos los Mensajes Directos forman parte de una conversación de Mensajes Directos. Estas conversaciones pueden ser uno a uno o de grupo. Este lanzamiento proporciona los endpoints fundamentales necesarios para crear Mensajes Directos y recuperar eventos asociados con conversaciones de Mensajes Directos. Todas las conversaciones tienen un dm_conversation_id único, y todos los eventos que conforman esa conversación tienen un dm_event_id único.   Los endpoints de consulta de Mensajes Directos ofrecen métodos para recuperar eventos asociados con conversaciones. Estos endpoints GET se usan para recuperar los mensajes que conforman una conversación y, en conversaciones de grupo, pueden utilizarse para saber quién se ha unido y quién ha salido de las conversaciones de grupo. Esta versión inicial de la consulta de Mensajes Directos incluye tres métodos GET:
  • GET /2/dm_conversations/with/:participant_id/dm_events - Recupera eventos de Mensajes Directos asociados con una conversación uno a uno. El parámetro de ruta :participant_id es el ID de usuario numérico de la cuenta que mantiene la conversación con el usuario autenticado que realiza esta solicitud.  
  • GET /2/dm_conversations/:dm_conversation_id/dm_events - Recupera eventos de Mensajes Directos asociados con un ID de conversación específico, según lo indicado por el parámetro de ruta :dm_conversation_id. Se admiten IDs de conversaciones tanto uno a uno como de grupo.  
  • GET /2/dm_events - Recupera eventos de Mensajes Directos asociados con el usuario autenticado, incluidas conversaciones tanto uno a uno como de grupo. Hay eventos disponibles de hasta hace 30 días.  
Todos estos endpoints GET admiten la recuperación de dm_events por tipo de evento mediante el parámetro de consulta event_types. Actualmente, se admiten tres tipos de eventos de conversación:
  • MessageCreate - Se crea cuando se envía un nuevo Mensaje Directo. Este objeto de evento puede incluir la hora y el texto del mensaje, junto con el ID de la cuenta de quien envió el mensaje, y los IDs de la conversación y del evento. 
  • ParticipantsJoin - Se crea cuando un nuevo participante se une a una conversación de grupo. Este objeto dm_event incluye el ID del participante que se une, junto con la marca de tiempo created_at y el sender_id del evento “invite”. 
  • ParticipantsLeave - Se crea cuando un participante abandona una conversación. Este objeto de evento incluye el ID del participante que se va, junto con la hora del evento. 
Para obtener más información, consulta las Referencias de la API de consulta de Mensajes Directos.

​
IDs de conversación y de evento compartidos entre v1.1 y v2

Un concepto importante es que los IDs de conversación y de evento se comparten entre las versiones v1.1 y v2 de la plataforma de X. Esto significa que ambas versiones pueden usarse conjuntamente. Por ejemplo, los endpoints de Direct Messages v1.1 ofrecen métodos para obtener un único evento y para eliminar eventos, métodos que aún no están disponibles en v2. Dado que los IDs son comunes entre v1.1 y v2, puedes realizar solicitudes de v1.1 basándote en IDs proporcionados por v2, o haciendo referencia a los IDs de conversación que se muestran en las URL de las conversaciones en la aplicación de X.  

​
Campos y expansions de eventos de Mensajes Directos

X API v2 permite seleccionar exactamente qué data se desea obtener de la API mediante un conjunto de herramientas llamadas fields y expansions. Por ejemplo, los endpoints de consulta de Mensajes Directos admiten los siguientes campos de dm_events:
  • id, event_type y text son los valores predeterminados para los eventos MessageCreate.
  • id, event_type y participant_ids son los valores predeterminados para los eventos ParticipantsJoin y ParticipantsLeave.
  • dm_conversation_id y created_at están disponibles para todos los eventos.
  • attachments y referenced_tweets están disponibles para eventos de tipo MessageCreate.
  • sender_id está disponible para los eventos MessageCreate y ParticipantsJoin.
  • participant_ids está disponible para los eventos ParticipantsJoin y ParticipantsLeave.
Además, los endpoints de consulta de Mensajes Directos admiten las siguientes expansions:
  • sender_id - Expande el objeto User asociado con quien envió el mensaje o quien invitó a alguien a la conversación.
  • referenced_tweets.id - Expande el objeto Post si el texto del Mensaje Directo incluye un enlace a un Post.
  • attachments.media_keys - Expande el objeto Media si el Mensaje Directo incluye un archivo multimedia adjunto.
  • participant_ids - Expande el objeto User asociado con quien se unió o abandonó una conversación grupal.
Dado que las expansions incluyen objetos Post, User y Media, también puede usar los parámetros de consulta tweet.fields, user.fields y media.fields. Consulte nuestra guía sobre cómo usar fields y expansions para más información.

​
Tipos de eventos de conversación

A continuación se muestran objetos JSON de ejemplo para los tipos de evento de Mensaje Directo MessageCreate, ParticipantsJoin y ParticipantsLeave. Campos disponibles del objeto dm_event: id, text, event_type, dm_conversation_id, created_at, sender_id, attachments, referenced_tweets, participant_ids. Consulta la sección Fields and Expansion para más detalles sobre cómo seleccionar estos fields en tus solicitudes. Ejemplo de evento MessageCreate: Con todos los fields de dm_event especificados, esta es la respuesta para un Mensaje Directo de texto simple: { "text": "Hi everyone.", "sender_id": "944480690", "dm_conversation_id": "1578398451921985538", "id": "1582838499983564806", "event_type": "MessageCreate", "created_at": "2022-10-19T20:58:00.000Z" } Ejemplo de evento ParticipantsJoin: Con todos los fields de dm_event especificados, esta es la respuesta para un participante que se une a una conversación: { "participant_ids": [ "944480690" ], "sender_id": "17200003", "dm_conversation_id": "1578398451921985538", "id": "1582835469712138240", "event_type": "ParticipantsJoin", "created_at": "2022-10-19T20:45:58.000Z" } Ejemplo de evento ParticipantsLeave: Con todos los fields de dm_event especificados, esta es la respuesta para un participante que abandona una conversación: { "participant_ids": [ "944480690" ], "dm_conversation_id": "1578398451921985538", "id": "1582838535115067392", "event_type": "ParticipantsLeave", "created_at": "2022-10-19T20:58:09.000Z" }

​
Autenticación

Todos los endpoints de X API v2 requieren que autentiques tus solicitudes con un conjunto de credenciales, también conocidas como claves y tokens. Todos los Mensajes Directos son privados y requieren autorización del usuario para acceder a ellos. Estos endpoints de Mensajes Directos requieren el uso de Código de autorización de OAuth 2.0 con PKCE o User Context 1.0a, lo que significa que debes usar un conjunto de claves de API y tokens de acceso de usuario para realizar una solicitud correctamente. Los tokens de acceso deben estar asociados con el usuario en cuyo nombre realizas la solicitud. Si deseas generar un conjunto de tokens de acceso para otro usuario, ese usuario debe autorizar o autenticar tu App mediante el flujo de OAuth de 3 etapas. Ten en cuenta que el contexto de usuario de OAuth puede ser complejo de usar. Si no estás familiarizado con este método de autenticación, te recomendamos usar una biblioteca o una herramienta como Postman para autenticar correctamente tus solicitudes. OAuth 2.0 Authorization Code with PKCE permite un mayor control sobre el alcance (scope) de una aplicación y flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir ámbitos granulares que te otorgan permisos específicos en nombre de un usuario. Los endpoints de consulta de Mensajes Directos requieren estos ámbitos: dm.read, post.read, user.read Para habilitar OAuth 2.0 en tu App, debes activarlo en la configuración de autenticación de tu App, ubicada en la sección de configuración del Portal de desarrolladores.

​
Portal de desarrolladores, Proyectos y Apps de desarrollador

Para obtener un conjunto de credenciales de autenticación que funcionen con los endpoints de la X API v2, debe contar con una cuenta de desarrollador aprobada, configurar un Proyecto dentro de esa cuenta y crear una App de desarrollador dentro de ese Proyecto. Luego podrá encontrar sus claves y tokens en su App de desarrollador. 

​
Límites de uso

Cada día, miles de desarrolladores realizan solicitudes a la X API. Para gestionar el gran volumen de solicitudes, se aplican límites de uso a cada endpoint que restringen la cantidad de solicitudes que puedes realizar en nombre de tu App o de un usuario autenticado. Los endpoints de consulta de Mensajes Directos tienen límites de uso a nivel de usuario, lo que significa que el usuario autenticado en cuyo nombre realizas la solicitud solo puede realizar un número determinado de solicitudes con tu App de X. Existe un límite de 300 solicitudes por usuario cada 15 minutos para los métodos GET. Estos límites se comparten entre los endpoints GET.  Estos endpoints utilizan paginación para que las respuestas se devuelvan rápidamente. En los casos en que haya más resultados de los que se pueden enviar en una sola respuesta (hasta 100 eventos), tendrás que paginar. Usa el parámetro max_results para especificar cuántos resultados se devolverán por página y el parámetro pagination_token para obtener la siguiente página de resultados. Puedes obtener más información en nuestra guía de paginación. Herramientas útiles A continuación encontrarás algunas herramientas útiles que te recomendamos explorar mientras trabajas con los endpoints de consulta de Mensajes Directos: Postman Postman es una excelente herramienta para probar un endpoint. Cada solicitud de Postman incluye todos los parámetros de ruta y de cuerpo para ayudarte a comprender rápidamente qué tienes disponible. Para obtener más información sobre nuestras colecciones de Postman, visita nuestra página Uso de Postman. Ejemplos de código El código de ejemplo en Python para los endpoints de Mensajes Directos v2 está disponible en nuestro repositorio de X API v2 sample code GitHub. La carpeta “Manage-Direct-Messages” contiene ejemplos para los métodos POST y la carpeta “Direct-Messages-lookup” contiene ejemplos para los métodos GET. XDev Software Development Kits (SDKs) Estas bibliotecas se están actualizando para los endpoints de Mensajes Directos v2 y deberían estar listas pronto: Bibliotecas de terceros Hay un número creciente de bibliotecas de terceros desarrolladas por nuestra comunidad. Estas bibliotecas están diseñadas para ayudarte a comenzar, y se espera que varias admitan pronto los endpoints de Mensajes Directos v2. Puedes encontrar una que funcione con los endpoints v2 buscando la etiqueta de versión correspondiente.