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 uno a uno y conversaciones de grupo. Las conversaciones uno a uno siempre tienen dos, y solo dos, participantes, mientras que las conversaciones de grupo pueden tener dos o más participantes y membresías que pueden cambiar.    Esta página contiene información sobre varias herramientas y conceptos clave que debe tener en cuenta al integrar los endpoints de Manage Direct Messages 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 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 los eventos que conforman esa conversación también tienen un dm_event_id único.   Los endpoints de Manage Direct Message proporcionan tres métodos POST para crear nuevos mensajes y añadirlos a conversaciones:
  • POST /2/dm_conversations/with/:participant_id/messages - Crea un Mensaje Directo individual (uno a uno). Este método añade el mensaje a una conversación individual existente o crea una nueva. El parámetro de ruta :participant_id es el User ID de la cuenta que recibe el mensaje.  Este es un ejemplo de cuerpo de solicitud JSON para enviar un Mensaje Directo individual:
{
   "text": "Hola, solo tú. Esto aparecerá como una nueva conversación si nunca hemos intercambiado mensajes, o se añadirá a nuestro hilo existente. "
}
  • POST /2/dm_conversations - Crea una nueva conversación de grupo y añade un Mensaje Directo. Estas solicitudes requieren una lista de participantes de la conversación. Ten en cuenta que puedes crear varias conversaciones con la misma lista de participantes. Estas solicitudes siempre devolverán un nuevo id de conversación. A continuación se muestra un ejemplo de cuerpo de solicitud JSON para crear una nueva conversación de grupo y añadir un Mensaje Directo. Ten en cuenta que esto requiere un campo “conversation_type” y que debe establecerse en “Group” (sensibles a mayúsculas y minúsculas).
{
   "message": {"text": "Hola a ustedes dos, esta es una nueva conversación grupal."},
   "participant_ids": ["944480690","906948460078698496"],
   "conversation_type": "Group"
}
  • POST /2/dm_conversations/:dm_conversation_id/messages - Crea un Mensaje Directo y lo añade a una conversación existente. El parámetro de ruta :dm_conversation_id es el id de la conversación a la que se añadirá el mensaje. Este método puede usarse para añadir un mensaje tanto a conversaciones uno a uno como a conversaciones grupales. A continuación se muestra un ejemplo de cuerpo de solicitud JSON para enviar un Mensaje Directo tanto a conversaciones uno a uno como a conversaciones grupales:
{
   "text": "Aquí tienes un nuevo mensaje."
}
Estos métodos POST permiten adjuntar una única pieza de contenido multimedia. Los cuerpos de las solicitudes POST deben incluir uno o ambos campos “text” y “attachments”. El atributo “text” es obligatorio si no se incluye el campo “attachments”, y el campo “attachments” es obligatorio si no se incluye el campo “text”. Consulte la siguiente sección para obtener más información. Para obtener más información, consulte las referencias de la API de gestión de Mensajes Directos.

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

Un concepto importante es que los id 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 Mensajes Directos de v1.1 ofrecen métodos para recuperar un solo evento y para eliminar eventos. Estos métodos aún no están disponibles en v2. Dado que los id son comunes entre v1.1 y v2, puede realizar solicitudes a v1.1 basadas en id proporcionados por v2, o bien hacer referencia a los id de conversación que se muestran en las URL de conversación en la aplicación de X.  

​
Inclusión de archivos multimedia y referencia a Posts

Todos los endpoints de Manage Direct Message admiten adjuntar un elemento multimedia (foto, video o GIF). Adjuntar contenido multimedia requiere un id de medios generado por el endpoint v1.1 Upload media. El usuario autenticado que envía el Direct Message también debe haber cargado el contenido multimedia. Una vez cargado, el contenido multimedia estará disponible durante 24 horas para incluirlo en el mensaje. Para ilustrar cómo incluir contenido multimedia, a continuación se muestra un ejemplo de cuerpo de una solicitud JSON: 
{
 "text": "Aquí tienes una foto...",
 "attachments": [{"media_id": "1583157113245011970}]
}
El evento MessageCreate resultante incluirá los siguientes metadatos: 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
Los Posts también se pueden añadir incluyendo la URL del Post en el texto del mensaje. Para ilustrar cómo incluir Posts en los mensajes, a continuación se muestra un ejemplo de cuerpo de la solicitud en JSON: 
{
 "text": "Aquí está el Tweet del que estaba hablando: https://x.com/SnowBotDev/status/1580559079470145536"
}
El evento MessageCreate resultante incluirá los siguientes metadatos: 
{
    "referenced_tweets": [
        {
            "id": "1580559079470145536"
        }
    ]
}

​
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 Key y Access Tokens de usuario para realizar una solicitud correctamente. Los Access Tokens deben estar asociados con el usuario en cuyo nombre realizas la solicitud. Si deseas generar un conjunto de Access Tokens para otro usuario, este debe autorizar o autenticar tu App usando el flujo de OAuth de 3 fases. Ten en cuenta que el user context de OAuth puede ser complejo de usar. Si no estás familiarizado con este método de autenticación, te recomendamos usar una library o una herramienta como Postman para autenticar correctamente tus solicitudes.  OAuth 2.0 Authorization Code with PKCE permite un mayor control sobre el 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.write, dm.read, tweet.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, debe contar con una cuenta de desarrollador aprobada, configurar un Project dentro de esa cuenta y crear una App de desarrollador dentro de ese Project. Luego podrá encontrar sus keys and tokens dentro de su 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 imponen límites de velocidad en cada endpoint que restringen la cantidad de solicitudes que puedes realizar en nombre de tu App o en nombre de un usuario autenticado. Los endpoints de Manage Direct Message tienen límites de velocidad tanto a nivel de usuario como a nivel de X App. Esto significa que el usuario autenticado en cuyo nombre realizas la solicitud solo puede enviar una cierta cantidad de mensajes con tu X App. Además, existe un límite diario sobre cuántos Mensajes Directos puede enviar tu X App. Hay un límite de velocidad por usuario de 200 solicitudes/mensajes por 15 minutos para los métodos POST. Los usuarios también están limitados a 1000 Mensajes Directos por 24 horas. Además, las X Apps tienen un límite de 15000 mensajes por 24 horas. Estos límites de velocidad se comparten entre los endpoints POST. Herramientas útiles Aquí tienes algunas herramientas útiles que te animamos a explorar mientras trabajas con los endpoints de consulta de Mensajes Directos: Postman Postman es una excelente herramienta que puedes usar 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é está disponible para ti. Para obtener más información sobre nuestras colecciones de Postman, visita nuestra página Using Postman. Código de muestra El código de muestra en Python para los endpoints de Mensajes Directos de v2 está disponible en nuestro repositorio 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 de v2 y deberían estar listas pronto: Bibliotecas de terceros Existe 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 ofrezcan soporte para los endpoints de Mensajes Directos de v2 pronto. Puedes encontrar una biblioteca que funcione con los endpoints de v2 buscando la etiqueta de versión adecuada.
⌘I