Guía rápida

​

Introducción a los endpoints para gestionar Mensajes Directos

Esta guía de inicio rápido le ayudará a realizar su primera solicitud a los endpoints de Mensajes Directos usando Postman, una herramienta para gestionar y realizar solicitudes HTTP. Para obtener más información sobre nuestras colecciones de Postman, visite nuestra guía Uso de Postman.

Visite nuestro repositorio de GitHub X API v2 sample code si desea revisar ejemplos en Python. Además, los kits de desarrollo de software (SDKs) de X Developer Platform oficiales se actualizarán para dar soporte a estos endpoints de Mensajes Directos.  

Requisitos previos

Para completar esta guía, necesitará un conjunto de claves y tokens para autenticar su solicitud. Puede generar estas claves y tokens siguiendo estos pasos:

• Regístrese para obtener una cuenta de desarrollador y reciba la aprobación.
• Cree un Project y una developer App asociada en el Portal de desarrolladores.
• Vaya a la página “Keys and tokens” de su App para generar las credenciales necesarias. Asegúrese de guardar todas las credenciales en un lugar seguro.

​

Pasos para crear solicitudes de consulta de Mensajes Directos

En este ejemplo, en una sola solicitud, crearemos una nueva conversación grupal y añadiremos nuestro primer mensaje a ella. Luego añadiremos un segundo mensaje a la conversación creada.

​

Paso uno: Comience con una herramienta o biblioteca

Para empezar a trabajar con los endpoints para administrar Mensajes Directos, usaremos la herramienta Postman para simplificar el proceso. Se utilizará una colección de solicitudes de ejemplo de X API v2, creada por XDevelopers, para explorar seis endpoints que se usan para crear nuevos Mensajes Directos y para listar eventos de conversaciones de Mensajes Directos.

Aunque gran parte de la colección está precompletada, hay algunos datos que deberá proporcionar según la App de X creada para alojar estas solicitudes de API. Primero, carguemos o actualicemos la colección.

Para cargar la colección de Postman de X API v2 en su entorno, haga clic en el siguiente botón:

Add X API v2 to Postman

Una vez que tenga la colección de X API v2 cargada en Postman, navegue a la carpeta “Manage Direct Messages”. La pestaña Authorization de esta carpeta se ha precompletado donde ha sido posible. Deberá actualizar algunos ajustes para incluir los detalles de Autenticación de su App de X.

Esta carpeta también contiene tres endpoints para crear nuevos Mensajes Directos. Tenga en cuenta que también hay una carpeta “Direct Message lookup” con tres endpoints disponibles para recuperar eventos de conversaciones de Mensajes Directos, incluido el envío y la recepción de mensajes y cuándo los participantes de la conversación se unen o se van.

Dado que la creación de conversaciones grupales es una función nueva de X API v2, este ejemplo se centrará en ello. Trabajaremos con el ejemplo “New group DM and conversation”. Usaremos esta solicitud para crear una conversación grupal de Mensajes Directos.

El siguiente paso es autenticarse con el endpoint.

​

Paso dos: Autentica tu solicitud

Para realizar correctamente una solicitud a la X API, debes verificar que tienes permiso para hacerlo. Para realizar una solicitud correcta a este endpoint, usaremos OAuth 2.0 Authorization Code Flow with PKCE. Puedes generar un token de acceso en Postman. 

Con Postman puedes configurar el método de autenticación a nivel de carpeta o de solicitud. Aquí configuraremos los detalles de autenticación a nivel de carpeta. Navega a la carpeta “Manage Direct Messages”, selecciona la pestaña “Authorization” y confirma que el Type esté establecido en “OAuth 2.0”, y que “Add auth data to” esté en “Request Headers.” En la sección “Current Token”, asegúrate de que “header Prefix” esté configurado en Bearer.  

Para configurar y generar un nuevo token:

1. Crea un nombre para el token, como “DM lookup.”

2. Confirma que Grant Type esté establecido en Authorization Code (with PKCE).

3. Establece tu Callback URL. Deberás actualizar tu Callback URL para que coincida exactamente con la Callback URL asociada a tu aplicación en el v2 Dev Portal. Con la App de X utilizada en este ejemplo, la Callback URL está configurada en - https://www.example.com. (Ten en cuenta que, dado que esto debe coincidir exactamente, https://example.com no funcionaría). 

4. Confirma que Auth URL esté establecida en https://x.com/i/oauth2/authorize

5. Confirma que Access Token URL esté establecida en https://api.x.com/2/oauth2/token.Client ID - Copia y pega el OAuth 2.0 client ID desde el Portal de desarrolladores Client Secret - Solo lo necesitarás si estás usando un tipo de App que sea un cliente confidencial. Si es así, copia y pega el OAuth 2.0 Client Secret desde el Portal de desarrolladores. 

6. Confirma que Scope esté configurado en dm.read dm.write tweet.read users.read.

7. Confirma que State esté configurado en “state.”

8. Confirma que Client Authentication esté configurado en Send as Basic Auth header.

9. Haz clic en “Get New Access Token” y luego en “Authorize app” como parte del proceso de “Sign-in with X”.

10. Haz clic en el botón “Proceed” y luego en “Use Token” para generar un token. 

11. Haz clic en el botón “Save” para guardar estos detalles de configuración.

Es posible que recibas un mensaje indicando que no has iniciado sesión en X. Si recibes este error, deberás iniciar sesión en la cuenta de X en nombre de la cual intentas publicar dentro de Postman.

Ahora que estos detalles de OAuth 2.0 se han configurado a nivel de carpeta, navega a cada uno de los ejemplos y su pestaña “Authorization” y confirma que tienen su Type establecido en “Inherit auth from parent.” 

Ten en cuenta que este token caducará pronto y deberás regenerarlo haciendo clic en el botón “Get New Access Token”. Al hacerlo, se iniciará el proceso de “Sign-in with X” y se generará un token nuevo para realizar solicitudes.

​

Paso tres: Recuperar eventos de conversaciones de Mensajes Directos

Al recuperar eventos de conversaciones de Mensajes Directos con este endpoint, debes especificar un id de conversación. El id de conversación forma parte de la ruta del endpoint: https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events

En Postman, ve a la pestaña “Params” y escribe el id de la conversación para la que quieres recuperar eventos en la sección “Path Variables”.

La configuración sería:

Key	Value
dm_conversation_id	1228393702244134912

Con esta conversación especificada, la ruta resultante pasa a ser https://api.x.com/2/dm_conversations/1582103724607971328/dm_events

Si haces clic en el botón “Send”, recibirás en tu respuesta los campos predeterminados del objeto de Mensaje Directo: id, text y event_type. También habrá un objeto “meta” con el número de resultados, junto con tokens de paginación para recuperar más eventos si están disponibles.

{
   "data": [
       {
           "event_type": "MessageCreate",
           "id": "1580705921830768647",
           "text": "hola a los dos, esta es una nueva conversación de grupo."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

Si desea recibir campos adicionales, deberá especificarlos en su solicitud con los parámetros fields y/o expansions.

Para este ejercicio, solicitaremos conjuntos adicionales de campos del objeto dm_event:

1. Los campos predeterminados del objeto de Mensaje Directo: id, text y event_type.

2. Campos adicionales del objeto de Mensaje Directo: dm_conversation_id, created_at, sender_id, attachments, participant_ids, referenced_tweets

En Postman, vaya a la pestaña “Params” y agregue el siguiente par clave:valor a la tabla “Query Params”:

Key	Value
dm_event.fields	dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

Ahora debería ver la siguiente URL junto al botón “Send”:

https://api.x.com/2/dm_conversations/:dm_conversation_id/dm_events?dm_event.fields=id,text,event_type,dm_conversation_id,created_at,sender_id,attachments,participant_ids,referenced_tweets

​

Paso cuatro: Realiza tu solicitud y revisa tu respuesta

Una vez que tengas todo configurado, vuelve a hacer clic en el botón “Send” y recibirás una respuesta similar a la que se muestra a continuación. Ten en cuenta que esta respuesta incluye todos los campos disponibles de dm_event.

{
   "data": [
       {
           "text": "hola a ustedes dos, esta es una nueva conversación de grupo.",
           "id": "1580705921830768647",
           "dm_conversation_id": "1580705921830768643",
           "event_type": "MessageCreate",
           "sender_id": "17200003",
           "created_at": "2022-10-13T23:43:54.000Z"
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}