Inicio rápido

​

Introducción a los endpoints para gestionar Mensajes Directos

Esta Guía rápida 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 software development kits (SDKs) de X Developer Platform oficiales se actualizarán para admitir estos endpoints de Mensajes Directos.  

Requisitos previos

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

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

​

Pasos para crear solicitudes de búsqueda de Mensajes Directos

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

​

Paso uno: Comience con una herramienta o biblioteca

Para comenzar a trabajar con los endpoints de gestión de Mensajes Directos, utilizaremos la herramienta Postman para simplificar el proceso. Se empleará una colección, creada por XDevelopers, con solicitudes de ejemplo de X API v2 para explorar seis endpoints usados para crear nuevos Mensajes Directos y para listar eventos de conversaciones de Mensajes Directos.

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

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

Añadir X API v2 a 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 preconfigurado cuando ha sido posible. Deberá actualizar algunos ajustes para compartir los detalles de autenticación de su X App.

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, incluidos el envío y la recepción de mensajes, y cuándo los participantes de la conversación se unen y 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 exitosa a este endpoint, utilizaremos OAuth 2.0 Authorization Code Flow with PKCE. Puedes generar un access token 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 “Mange Direct Messages”, selecciona la pestaña “Authorization” y confirma que 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é establecido en Bearer.  

Para configurar y generar un nuevo token:

1. Crea un Token Name, como “DM lookup.”

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

3. Configura tu Callback URL. Debes actualizar tu Callback URL para que coincida exactamente con la Callback URL asociada con tu aplicación en el v2 Dev Portal. Con la X App utilizada en este ejemplo, la Callback URL está configurada en - https://www.example.com. (Ten en cuenta que, dado que 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 Developer Portal Client Secret - Solo lo necesitarás si estás usando un App type que sea un confidential client. Si es así, copia y pega el OAuth 2.0 Client Secret desde el Developer Portal. 

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

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

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

9. Haz clic donde dice “Get New Access Token” y luego en “Authorize app” como parte del proceso “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 cuyo nombre estás intentando 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 a su pestaña “Authorization” y confirma que tengan su Type establecido en “Inherit auth from parent.” 

Ten en cuenta que este token caducará pronto y tendrás que generarlo de nuevo haciendo clic en el botón “Get New Access Token”. Al hacerlo, se iniciará el proceso “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” e introduce el id de la conversación para la que deseas 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 la 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 grupal."
       }
   ],
   "meta": {
       "result_count": 1,
       "next_token": "18LAA5FFPEKJA52G0G00ZZZZ",
       "previous_token": "1BLC45FFPEKJA52G0S00ZZZZ"
   }
}

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

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: Realice su solicitud y revise su respuesta

Una vez que tenga todo configurado, haga clic en el botón “Send” nuevamente y recibirá una respuesta similar a la siguiente. Tenga en cuenta que esta respuesta incluye todos los campos dm_event disponibles.

{
   "data": [
       {
           "text": "hola a los dos, esta es una nueva conversación grupal.",
           "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"
   }
}