Inicio rápido

​

Introducción a los endpoints para administrar 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 la 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 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 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 empezar a trabajar con los endpoints de gestión de 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 XDev, para explorar seis endpoints usados para crear nuevos Mensajes Directos y para listar eventos de conversaciones de Mensajes Directos.

Aunque la mayor parte de la colección está precompletada, hay algunos detalles que deberá proporcionar en función de la X App creada para alojar estas solicitudes de API. Primero, carguemos/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 ha sido precompletada cuando ha sido posible, y puede 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 cuando los participantes de la conversación se unen y se van. 

Dado que la creación de conversaciones grupales es una característica nueva e importante 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 la X API, debe verificar que tiene permiso para hacerlo. Para realizar una solicitud exitosa a este endpoint, utilizaremos OAuth 2.0 Authorization Code Flow with PKCE. Puede generar un access token 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 “header Prefix” esté configurado en Bearer.  

Para configurar y generar un nuevo token:

1. Cree un Token Name, como “Manage DMs”.

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

3. Configure su Callback URL. Deberá actualizar su Callback URL para que coincida exactamente con la Callback URL asociada a su aplicación en el v2 Dev Portal. Con la X App utilizada en este ejemplo, la Callback URL está configurada como - 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é configurada en https://x.com/i/oauth2/authorize.

5. Confirme que Access Token URL esté configurada en https://api.x.com/2/oauth2/token. Client ID - Copie y pegue el OAuth 2.0 client ID desde el Developer Portal Client Secret - Solo lo necesitará si está utilizando un App type que sea un cliente confidencial. Si es así, copie y pegue el OAuth 2.0 Client Secret desde el Developer Portal. 

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 obtiene este error, deberá iniciar sesión en la cuenta de X en cuyo nombre intenta publicar dentro de Postman.

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

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

Vaya a la pestaña “Body” y actualice el objeto JSON de ejemplo. Defina el atributo participant_ids con las cuentas a las que desea 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 aparece a continuación. Recuerda que, 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 “data” de la respuesta contiene un dm_conversation_id y un dm_event_id, has creado correctamente una nueva conversación de Mensaje Directo. Para empezar a consultar los eventos asociados con esta conversación, dirígete a la Guía rápida de búsqueda de Mensajes Directos.

​

Paso cinco: añade otro mensaje a esa conversación grupal

Ahora selecciona el ejemplo “Add DM to conversation” y luego 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 un JSON de solicitud que incluya el texto del mensaje que deseas enviar:

{
   "text": "Agregando un nuevo mensaje a nuestra conversación grupal..."
}

Una vez que tengas todo configurado, 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"
   }
}