Guía de inicio rápido de la X Activity API para transmitir eventos

Esta guía explica cómo suscribirse y recibir eventos usando los endpoints de la X Activity API. Generalmente hay 3 pasos involucrados:

Identificar el User ID del usuario cuyos eventos quieres filtrar
Crear una suscripción para el tipo de evento que quieres filtrar para ese usuario
Recibir los eventos mediante webhook o una conexión HTTP persistente de streaming

Requisitos previosAntes de comenzar, necesitarás:

Una cuenta de desarrollador con una App aprobada
El Bearer Token de tu App

Obtener IDs de usuario

Antes de crear suscripciones, necesitarás conocer el user ID de la cuenta que deseas filtrar. En este ejemplo, usaremos el handle XDevelopers. Puedes buscar user IDs de varias formas, incluyendo: Buscar el ID de un usuario por username:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"

Obtener tu propio user ID:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/users/me

Ambos endpoints devuelven información del usuario incluyendo el campo id, que puedes usar en los filtros de suscripción. A continuación se muestra un ejemplo de respuesta JSON:

{
    "data": {
        "id": "2244994945",
        "name": "Developers",
        "username": "XDevelopers"
    }
}

Crear una suscripción

El siguiente paso es crear una suscripción. En este ejemplo, nos suscribiremos a las actualizaciones de biografía de XDevelopers. Para ello, pasaremos el user_id y el event_type en el cuerpo JSON. En este caso, el event_type es profile.update.bio. Pasaremos el user ID de X Developers: 2244994945, y un tag opcional:

{
  "event_type": "profile.update.bio",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopers' bio updates"
}

Usaremos nuestro bearer token (del portal de desarrolladores) para la autorización. El bearer token de solo aplicación funciona para eventos públicos como este. Algunos eventos son privados y requieren autenticación con contexto de usuario (OAuth 2.0) — consulta Privacidad de eventos y autenticación para más detalles.

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions \
  -X POST \
  -d '{
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "2244994945"
    },
    "tag": "Xdevelopers' bio updates"
  }'

Si la solicitud es exitosa, tu suscripción se creará:

profile.update.bio

{
  "data":[
    {
      "created_at":"2025-10-09T16:35:08.000Z",
      "event_type":"profile.update.bio",
      "filter":{
        "user_id":"2244994945"
      },
      "subscription_id":"1976325569252868096",
      "tag": "Xdevelopers' bio updates",
      "updated_at":"2025-10-09T16:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 1
  }
}

Recibir los eventos

Una vez creada la suscripción, podemos recibir los eventos a través de webhooks o de un stream HTTP persistente. En este ejemplo, abriremos el stream HTTP persistente:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" https://api.x.com/2/activity/stream

Cuando la cuenta Xdevelopers actualice su biografía de perfil, el evento se entregará a través del stream:

profile.update.bio

{
  "data": {
    "filter": {
      "user_id": "2244994945"
    },
    "event_type": "profile.update.bio",
    "tag": "Xdevelopers' bio updates",
    "payload": {
      "before": "Mars & Cars",
      "after": "Mars, Cars & AI"
    }
  }
}

Gestión de suscripciones

La X Activity API proporciona endpoints para gestionar tus suscripciones mediante operaciones CRUD estándar.

Crear suscripción

Crea una nueva suscripción para recibir eventos:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X POST \
  https://api.x.com/2/activity/subscriptions \
  -d '{
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "123456789"
    },
    "tag": "my bio updates",
    "webhook_id": "1976325569252868099"
  }'

El campo tag es opcional. Se puede usar para ayudar a identificar los eventos en la entrega.
El campo webhook_id también es opcional. Consulta nuestra documentación de webhooks para ayuda con la configuración de un webhook. Si se especifica un webhook_id, el evento se entregará al webhook proporcionado, además del stream si está abierto.

Respuesta:

profile.update.bio

{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-09T16:35:08.000Z",
    "tag": "my bio updates",
    "webhook_id": "1976325569252868099"
  }
}

Listar suscripciones

Recupera todas las suscripciones activas de tu aplicación:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions

Respuesta:

profile.update.bio

{
  "data": [
    {
      "subscription_id": "1976325569252868096",
      "event_type": "profile.update.bio",
      "filter": {
        "user_id": "123456789"
      },
      "created_at": "2025-10-09T16:35:08.000Z",
      "updated_at": "2025-10-10T03:50:59.000Z"
    },
    {
      "subscription_id": "1976325569252868097",
      "event_type": "profile.update.profile_picture",
      "filter": {
        "user_id": "987654321"
      },
      "created_at": "2025-10-08T14:35:08.000Z",
      "updated_at": "2025-10-08T14:35:08.000Z"
    }
  ],
  "meta": {
    "total_subscriptions": 2
  }
}

Eliminar suscripción

Elimina una suscripción:

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096

Respuesta:

{
  "data": {
    "deleted": true
  },
  "meta": {
    "total_subscriptions": 0
  }
}

total_subscriptions muestra el número restante de suscripciones asociadas a tu app tras la operación de eliminación.

Actualizar suscripción

El endpoint PUT te permite actualizar el método de entrega o el tag de una suscripción. Actualizar el filter o el event_type requiere eliminar la suscripción existente y agregar una nueva.

curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X PUT \
  https://api.x.com/2/activity/subscriptions/1976325569252868096 \
  -d '{
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  }'

Respuesta:

profile.update.bio

{
  "data": {
    "subscription_id": "1976325569252868096",
    "event_type": "profile.update.bio",
    "filter": {
      "user_id": "123456789"
    },
    "created_at": "2025-10-09T16:35:08.000Z",
    "updated_at": "2025-10-10T17:10:58.000Z",
    "tag": "my new tag",
    "webhook_id": "192846273860294839"
  },
  "meta": {
    "total_subscriptions": 1
  }
}

Próximos pasos

Payloads de eventos

JSON de ejemplo para cada tipo de evento de activity

Referencia de la API

Documentación completa del endpoint

Webhooks

Configura la entrega mediante webhook

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Guía de inicio rápido de la X Activity API para transmitir eventos

Obtener IDs de usuario

Crear una suscripción

Recibir los eventos

Gestión de suscripciones

Crear suscripción

Listar suscripciones

Eliminar suscripción

Actualizar suscripción

Próximos pasos

Payloads de eventos

Referencia de la API

Webhooks

​Obtener IDs de usuario

​Crear una suscripción

​Recibir los eventos

​Gestión de suscripciones

​Crear suscripción

​Listar suscripciones

​Eliminar suscripción

​Actualizar suscripción

​Próximos pasos

Payloads de eventos

Referencia de la API

Webhooks

Obtener IDs de usuario

Crear una suscripción

Recibir los eventos

Gestión de suscripciones

Crear suscripción

Listar suscripciones

Eliminar suscripción

Actualizar suscripción

Próximos pasos