Guía de integración

Conceptos clave y prácticas recomendadas para el envío de Mensajes Directos

Esta guía cubre los conceptos clave que necesitas para integrar los endpoints para administrar los Mensajes Directos en tu aplicación.

---

Autenticación

Los endpoints de Mensajes Directos requieren autenticación de usuario:

Método	Descripción
OAuth 2.0 Authorization Code with PKCE	Recomendado
OAuth 1.0a User Context	Compatibilidad heredada

La autenticación App-Only no está admitida. Todos los mensajes directos son privados.

Scopes requeridos (OAuth 2.0)

Scope	Requerido para
dm.write	Enviar y eliminar mensajes
dm.read	Requerido junto con dm.write
tweet.read	Requerido con los scopes de DM
users.read	Requerido con los scopes de DM

---

Descripción general de los endpoints

Método	Endpoint	Descripción
POST	/2/dm_conversations/with/:participant_id/messages	Enviar un mensaje uno a uno
POST	/2/dm_conversations	Crear una conversación de grupo
POST	/2/dm_conversations/:dm_conversation_id/messages	Agregar un mensaje a la conversación
DELETE	/2/dm_events/:event_id	Eliminar un mensaje

---

Enviar mensajes

Mensaje uno a uno

Envía un mensaje a un usuario específico. Crea una nueva conversación si aún no existe ninguna:

cURL

shellscript

curl -X POST "https://api.x.com/2/dm_conversations/with/9876543210/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "¡Hola!"}'

Conversación de grupo

Crea un nuevo grupo y envía el primer mensaje:

cURL

shellscript

curl -X POST "https://api.x.com/2/dm_conversations" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_type": "Group",
    "participant_ids": ["944480690", "906948460078698496"],
    "message": {"text": "¡Bienvenido a nuestro grupo!"}
  }'

El campo conversation_type debe configurarse en "Group" (distingue entre mayúsculas y minúsculas).

Agregar a una conversación existente

Envía un mensaje a cualquier conversación en la que participes:

cURL

shellscript

curl -X POST "https://api.x.com/2/dm_conversations/1582103724607971328/messages" \
  -H "Authorization: Bearer $USER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"text": "Another message"}'

---

Archivos multimedia adjuntos

Adjunta un archivo multimedia (foto, video o GIF) por mensaje.

1. Subir contenido multimedia

   Usa el endpoint Media Upload para subir tu archivo y obtener un media_id.

2. Incluir en el mensaje

   {
     "text": "¡Mira esta imagen!",
     "attachments": [{"media_id": "1583157113245011970"}]
   }
   

• El usuario autenticado debe haber subido el archivo multimedia
• El archivo multimedia estará disponible durante 24 horas después de haberse subido
• Solo se admite un archivo adjunto por mensaje

---

Compartir publicaciones

Incluye una Publicación en tu mensaje añadiendo la URL de la Publicación al texto:

{
  "text": "Have you seen this? https://x.com/XDevelopers/status/1580559079470145536"
}

La respuesta incluirá un campo referenced_tweets con el ID de la Publicación.

---

Requisitos de los mensajes

Campo	Obligatorio	Notas
text	Sí*	Obligatorio si no hay archivos adjuntos
attachments	Sí*	Obligatorio si no hay texto

*Se debe proporcionar al menos uno de text o attachments.

---

Compatibilidad de id con v1.1

Los id de conversación y de eventos se comparten entre los endpoints de v1.1 y v2. Esto permite flujos de trabajo híbridos:

• Crear mensajes con v2
• Eliminar mensajes con v1.1 (aún no disponible en v2)
• Hacer referencia a id de conversación desde URL de x.com

---

Manejo de errores

Estado	Error	Solución
400	Solicitud no válida	Comprueba el formato del cuerpo de la solicitud
401	No autorizado	Comprueba el token de acceso
403	Acceso denegado	Comprueba los scopes y los permisos del usuario
429	Demasiadas solicitudes	Espera y vuelve a intentarlo

Problemas comunes

No se puede enviar al usuario

Es posible que el destinatario tenga una configuración de MD que impida recibir mensajes de usuarios desconocidos o que te haya bloqueado.

Error al adjuntar el contenido multimedia

Asegúrate de que el contenido multimedia fue cargado por el mismo usuario autenticado y tenga menos de 24 horas de antigüedad.

Error al crear el grupo

Verifica que todos los id de participantes sean válidos y que los usuarios permitan recibir invitaciones a MD grupales.

---

Próximos pasos

Inicio rápido

Envía tu primer mensaje directo (DM)

Búsqueda de DM

Recupera conversaciones de DM

Carga de medios

Sube archivos multimedia para adjuntarlos

Referencia de la API

Documentación completa del endpoint