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 distinguen entre conversaciones uno a uno y 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 debes conocer al integrar los endpoints de Manage Direct Messages 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 grupales. Este lanzamiento proporciona los endpoints fundamentales necesarios para crear Mensajes Directos y recuperar eventos asociados con las conversaciones de Mensajes Directos. Todas las conversaciones tienen un dm_conversation_id único, y los eventos que componen esa conversación tienen cada uno un dm_event_id único.   Los endpoints de Manage Direct Message ofrecen tres métodos POST para crear nuevos mensajes y agregarlos a conversaciones:
  • POST /2/dm_conversations/with/:participant_id/messages - Crea un Mensaje Directo uno a uno. Este método agrega el mensaje a una conversación uno a uno existente o crea una nueva. El parámetro de ruta :participant_id es el User ID de la cuenta que recibe el mensaje.  A continuación se muestra un ejemplo de cuerpo de solicitud JSON para enviar un Mensaje Directo uno a uno:
{
   "text": "Hola, solo tú. Esto aparecerá como una conversación nueva si nunca nos hemos enviado mensajes, o se agregará 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” (distingue 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 utilizarse para añadir un mensaje tanto a conversaciones uno a uno como a conversaciones de grupo. 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 de grupo:
{
   "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 el campo “text”, el campo “attachments” o ambos. 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”. Consulta la siguiente sección para obtener más información. Para obtener más información, consulta las referencias de la API Manage Direct Messages.

​
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 utilizarse conjuntamente. Por ejemplo, los endpoints de Direct Messages v1.1 ofrecen métodos para obtener un único 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 aparecen en las URL de conversación en la aplicación de X.  

​
Inclusión de contenido multimedia y referencia a Posts

Todos los endpoints de Manage Direct Message permiten adjuntar una pieza de contenido multimedia (foto, video o GIF). Adjuntar contenido multimedia requiere un media ID generado por el endpoint v1.1 Upload media. El usuario autenticado que envía el Mensaje Directo también debe haber subido el contenido multimedia. Una vez subido, 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 del cuerpo de una solicitud JSON: 
{
 "text": "Aquí tienes una foto...",
 "attachments": [{"media_id": "1583157113245011970}]
}
El evento MessageCreate resultante incluirá los metadatos siguientes: 
{
    "attachments": {
        "media_keys": [
            "5_1583157113245011970"
        ]
    }
}
Los Posts también pueden incluirse 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 hablaba: https://x.com/SnowBotDev/status/1580559079470145536"
}
El evento MessageCreate resultante incluirá los metadatos siguientes: 
{
    "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 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 OAuth 2.0 Authorization Flow with PKCE o 1.0a User Context, 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 estás realizando la solicitud. Si quieres generar un conjunto de tokens de acceso para otro usuario, este debe autorizar o autenticar tu App mediante el flujo OAuth con 3 participantes. Ten en cuenta que el contexto de usuario de OAuth puede ser complejo de utilizar. 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 de una aplicación y los flujos de autorización en múltiples dispositivos. OAuth 2.0 te permite elegir alcances granulares específicos, que te otorgan permisos concretos en nombre de un usuario. Los endpoints de consulta de Mensajes Directos requieren estos alcances: 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 de la App 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 X API v2, debes tener una cuenta de desarrollador aprobada, configurar un Proyecto dentro de esa cuenta y crear una App de desarrollador dentro de ese Proyecto. Luego podrás encontrar tus claves y tokens en tu App de desarrollador. 

​
Límites de uso

Cada día, miles de desarrolladores realizan solicitudes a la X API. Para gestionar el elevado volumen de estas 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 en nombre de un usuario autenticado. Los endpoints de Manage Direct Message tienen límites de uso tanto a nivel de usuario como a nivel de App de X. Esto significa que el usuario autenticado en cuyo nombre realizas la solicitud solo puede enviar una determinada cantidad de mensajes con tu App de X. Además, existe un límite diario respecto de cuántos Mensajes Directos puede enviar tu App de X. Existe un límite de 200 solicitudes/mensajes por cada 15 minutos para los métodos POST. Los usuarios también están limitados a 1000 Mensajes Directos por cada 24 horas. Además, las Apps de X tienen un límite de 15000 mensajes por cada 24 horas. Estos límites se comparten entre los endpoints POST. Herramientas útiles Aquí tienes algunas herramientas útiles que te recomendamos 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 obtener más información sobre nuestras colecciones de Postman, visita nuestra página Using Postman. Ejemplos de código El código de ejemplo en Python para los endpoints de Mensajes Directos 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. Kits de desarrollo de software (SDK) de XDev Estas bibliotecas se están actualizando para los endpoints de Mensajes Directos 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 admitan pronto los endpoints de Mensajes Directos v2. Puedes encontrar una biblioteca que funcione con los endpoints v2 buscando la etiqueta de versión correspondiente.