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 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 claves y 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.
• Navegue 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 gestionar solicitudes de Mensajes Directos

En este ejemplo, en una sola solicitud crearemos una nueva conversación de grupo 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, usaremos la herramienta Postman para simplificar el proceso. Se utilizará una colección creada por XDev con ejemplos de solicitudes de X API v2 para explorar seis endpoints usados para crear nuevos Mensajes Directos y para listar eventos de conversaciones de Mensajes Directos.

Si bien gran parte de la colección está precompletada, hay algunos detalles que deberá proporcionar basados en 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:

Agregar 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 está precompletada cuando es posible, y puede actualizar algunos ajustes para compartir 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, incluidos el envío y la recepción de mensajes, y cuando los participantes de la conversación se unen y se van. 

Dado que crear conversaciones grupales es una función nueva e interesante 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: Autentique su solicitud

Para realizar correctamente una solicitud a X API, debe verificar que tiene permiso para hacerlo. Para realizar una solicitud exitosa a este endpoint, usaremos OAuth 2.0 Authorization Code Flow with PKCE. Puede generar un token de acceso dentro de Postman. 

Con Postman puede configurar el método de autenticación a nivel de carpeta o a nivel de solicitud. Aquí configuraremos los detalles de autenticación a nivel de carpeta.

Navegue a la carpeta “Manage Direct Messages”, seleccione la pestaña “Authorization” y confirme que el Type esté configurado en “OAuth 2.0” y que “Add auth data to” esté configurado en “Request Headers”. En la sección “Current Token”, asegúrese de que el “header Prefix” esté establecido en Bearer.  

Para configurar y generar un token nuevo:

1. Cree un nombre de token, como “Manage DMs”.

2. Confirme que Grant Type esté configurado en Authorization Code (with PKCE).

3. Establezca su Callback URL. Deberá actualizar su Callback URL para que coincida exactamente con la Callback URL asociada con su 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. (Tenga en cuenta que, dado que esto debe coincidir exactamente, https://example.com no funcionaría). 

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

5. Confirme que Access Token URL esté configurado en https://api.x.com/2/oauth2/token. Client ID - Copie y pegue el OAuth 2.0 client ID desde el Portal de desarrolladores Client Secret - Solo necesitará esto si está utilizando un tipo de App que sea un cliente confidencial. De ser así, copie y pegue el OAuth 2.0 Client Secret desde el Portal de desarrolladores. 

6. Confirme que Scope esté configurado en dm.read, dm.write, tweet.read y users.read.

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

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

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

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

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

Es posible que reciba un mensaje indicando que no ha iniciado sesión en X. Si recibe este error, deberá iniciar sesión en la cuenta de X en nombre de la cual intenta publicar dentro de Postman.

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

Ten en cuenta que este token vencerá pronto y tendrás que 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: Especifica los participantes de la conversación de Mensaje Directo y el contenido del mensaje

Ve a la pestaña “Body” y actualiza el objeto JSON de ejemplo. Establece el atributo participant_ids con las cuentas a las que deseas enviar el Mensaje Directo.

{ "message": {"text": "Hola a ustedes dos, esta es una nueva conversación de grupo."}, "participant_ids": ["944480690","906948460078698496"], "conversation_type": "Group" }

​

Paso cuatro: Realiza tu solicitud y revisa la respuesta

Una vez que tengas todo configurado, haz clic en el botón “Send” y recibirás una respuesta similar al ejemplo que se muestra a continuación. Como recordatorio, si tu token ha expirado desde que lo creaste anteriormente, puedes volver a la pestaña Authorization de la carpeta y hacer clic en “Get New Access Token” para generar un token nuevo.

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582103724607971332"
   }
}

Si el objeto de respuesta “data” contiene un dm_conversation_id y un dm_event_id, has creado correctamente una nueva conversación de Mensajes Directos. Para empezar a consultar los eventos asociados a esta conversación, dirígete a la guía de inicio rápido de búsqueda de Mensajes Directos.

​

Paso cinco: Agregar otro mensaje a esa conversación de grupo

Ahora selecciona el ejemplo “Add DM to conversation” y ve a la pestaña “Params”. En “Path Variables”, actualiza el dm_conversation_id con el ID de la conversación que creaste arriba.

Key	Value
dm_conversation_id	1582103724607971328

Con este ID de conversación, la ruta de la solicitud será: https://api.x.com/2/dm_conversations/1582103724607971328/messages

Además, actualiza la pestaña “Body” con el JSON de la solicitud que contenga el texto del mensaje que deseas enviar:

{
   "text": "Añadiendo un nuevo mensaje a nuestra conversación grupal..."
}

Una vez que tengas todo listo, haz clic en el botón “Send” y recibirás una respuesta similar al siguiente ejemplo:

{
   "data": {
       "dm_conversation_id": "1582103724607971328",
       "dm_event_id": "1582106224379559940"
   }
}