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 establecen una distinción entre conversaciones 1-1 y conversaciones 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 debe conocer al integrar los endpoints de consulta de Mensajes Directos en su 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 individuales (uno a uno) o grupales. Esta versión inicial 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 los eventos que componen esa conversación tienen un dm_event_id único.   Los endpoints de consulta de Mensajes Directos proporcionan métodos para recuperar eventos asociados con conversaciones. Estos endpoints GET se usan para recuperar los mensajes que conforman una conversación y, en el caso de las conversaciones grupales, pueden usarse 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 individual. 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 individuales como grupales.  
  • GET /2/dm_events - Recupera eventos de Mensajes Directos asociados con el usuario autenticado, incluidas las conversaciones tanto individuales como grupales. Hay eventos disponibles de hasta hace 30 días.  
Todos estos endpoints GET admiten recuperar 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 que lo envió y los IDs de la conversación y del evento. 
  • ParticipantsJoin - Se crea cuando un nuevo participante se une a una conversación grupal. Este objeto dm_event incluye el ID del participante que se une, junto con el campo created_at y el sender_id del evento “invite”. 
  • ParticipantsLeave - Se crea cuando un participante sale de una conversación. Este objeto de evento incluye el ID del participante que sale, junto con la hora del evento. 
Para obtener más información, consulta las Referencias de la API de consulta de Mensajes Directos.

​
id de conversación y de evento compartidas entre v1.1 y v2

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

​
Campos y expansions de eventos de Mensaje Directo

La X API v2 permite a los usuarios seleccionar exactamente qué data desean que devuelva la API utilizando 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 eventos de MessageCreate. 
  • id, event_type y participant_ids son los valores predeterminados para eventos de 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 MessageCreate. 
  • sender_id está disponible para eventos de MessageCreate y ParticipantsJoin. 
  • participant_ids está disponible para eventos de ParticipantsJoin y ParticipantsLeave. 
Además, los endpoints de consulta de Mensajes Directos admiten las siguientes expansions:
  • sender_id - Expande el objeto de usuario asociado con quien envió el mensaje o quien invitó a alguien a la conversación. 
  • referenced_tweets.id - Expande el Objeto de 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 adjunto multimedia. 
  • participant_ids - Expande el objeto de usuario asociado con quien se unió o salió de una conversación grupal.
Dado que las expansions incluyen objetos de Posts, Users y Media, también puede utilizar los parámetros de consulta de la solicitud tweet.fields, user.fields y media.fields. Consulte nuestra guía sobre cómo usar fields y expansions para obtener 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 campos en tus solicitudes. Ejemplo de evento MessageCreate: Con todos los campos 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 campos de dm_event especificados, esta es la respuesta cuando un participante 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 campos de dm_event especificados, esta es la respuesta cuando un participante 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 keys and 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 OAuth 2.0 Authorization Flow with PKCE o 1.0a User Context, lo que significa que debes usar un conjunto de API Keys y Access Tokens de usuario para realizar una solicitud correctamente. Los Access Tokens deben estar asociados con el usuario en cuyo nombre estás realizando la solicitud. Si deseas generar un conjunto de Access Tokens para otro usuario, ese usuario debe autorizar o autenticar tu App utilizando el flujo de OAuth de 3 fases. 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 los flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir scopes específicos y granulares que te otorgan permisos concretos en nombre de un usuario. Los endpoints de consulta de Mensajes Directos requieren estos scopes: 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, Projects y Apps de desarrollador

Para obtener un conjunto de credenciales de autenticación que funcionen con los endpoints de la X API v2, debes tener una cuenta de desarrollador aprobada, configurar un Project dentro de esa cuenta y crear una App de desarrollador dentro de ese Project. Luego podrás encontrar tus keys and tokens dentro de tu App de desarrollador. 

​
Límites de velocidad

Cada día, muchos miles de desarrolladores realizan solicitudes a la X API. Para ayudar a gestionar el gran volumen de estas solicitudes, se aplican límites de velocidad 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 velocidad a nivel de usuario, lo que significa que el usuario autenticado en cuyo nombre realizas la solicitud solo puede hacer una cierta cantidad de solicitudes con tu X App. Existe un límite de velocidad de 300 solicitudes por 15 minutos para los métodos GET. Estos límites de velocidad se comparten entre los endpoints GET.  Estos endpoints utilizan paginación para que las respuestas se devuelvan rápidamente. Cuando haya más resultados de los que se pueden enviar en una sola respuesta (hasta 100 eventos), deberá paginar. Use el parámetro max_results para indicar cuántos resultados se devolverán por página y el parámetro pagination_token para obtener la siguiente página de resultados. Puede obtener más información en nuestra guía de paginación. Herramientas útiles Aquí tiene algunas herramientas útiles que le recomendamos explorar mientras trabaja con los endpoints de consulta de Mensajes Directos:  Postman Postman es una excelente herramienta que puede usar para probar un endpoint. Cada solicitud de Postman incluye todos los parámetros de ruta y de cuerpo para ayudarle a entender rápidamente qué está disponible. Para obtener más información sobre nuestras colecciones de Postman, visite nuestra página Uso de Postman.  Ejemplos de código El código de muestra en Python para los endpoints de Mensajes Directos de v2 está disponible en nuestro repositorio de Código de muestra de X API v2 en 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. Kits de Desarrollo de Software (SDK) de XDev Estas bibliotecas se están actualizando para los endpoints de Mensajes Directos de 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 ayudarle a empezar, y se espera que varias admitan pronto los endpoints de Mensajes Directos de v2. Puede encontrar una biblioteca que funcione con los endpoints de v2 buscando la etiqueta de versión correspondiente.
⌘I