Guia de início rápido da X Activity API para streaming de eventos

Este guia explica como se inscrever e receber eventos usando os endpoints da X Activity API. Geralmente há 3 etapas envolvidas:

Identifique o User ID do usuário cujos eventos você deseja filtrar
Crie uma inscrição para o tipo de evento que deseja filtrar para esse usuário
Receba os eventos usando webhook ou conexão persistente de stream HTTP

Pré-requisitosAntes de começar, você precisará de:

Uma conta de desenvolvedor com um App aprovado
O Bearer Token do seu App

Obtendo IDs de usuário

Antes de criar inscrições, você precisará conhecer o user ID da conta na qual deseja filtrar. Neste exemplo, usaremos o handle XDevelopers. Você pode consultar user IDs de várias maneiras, incluindo: Consultar o ID de um usuário pelo username:

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

Obter seu próprio user ID:

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

Ambos os endpoints retornam informações do usuário incluindo o campo id, que você pode usar em filtros de inscrição. Um exemplo de resposta JSON é mostrado abaixo:

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

Criando uma inscrição

O próximo passo é criar uma inscrição. Neste exemplo, vamos nos inscrever nas atualizações de bio da XDevelopers. Para isso, passaremos o user_id e event_type no corpo JSON. Neste caso, o event_type é profile.update.bio. Passaremos o user ID da X Developer: 2244994945, e uma tag opcional:

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

Usaremos nosso bearer token (do developer portal) para autorização. O app-only bearer token funciona para eventos públicos como este. Alguns eventos são privados e exigem autenticação user-context (OAuth 2.0) — consulte Privacidade de eventos e autenticação para detalhes.

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"
  }'

Após uma requisição bem-sucedida, sua inscrição será criada:

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
  }
}

Recebendo os eventos

Depois de criarmos a inscrição, podemos receber os eventos via webhooks ou por um stream HTTP persistente. Neste exemplo, abriremos o stream HTTP persistente:

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

Quando a conta Xdevelopers atualizar a bio do perfil, o evento será entregue por meio do 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"
    }
  }
}

Gerenciamento de inscrições

A X Activity API fornece endpoints para gerenciar suas inscrições por meio de operações CRUD padrão.

Criar inscrição

Crie uma nova inscrição para receber 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"
  }'

O campo tag é opcional. Pode ser usado para ajudar a identificar eventos na entrega.
O campo webhook_id também é opcional. Consulte nossos documentos de webhook para ajuda na configuração de um webhook. Se um webhook_id for especificado, o evento será entregue ao webhook fornecido, além do stream, caso esteja aberto.

Resposta:

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 inscrições

Recupere todas as inscrições ativas do seu aplicativo:

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

Resposta:

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
  }
}

Excluir inscrição

Remova uma inscrição:

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

Resposta:

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

total_subscriptions mostra o número restante de inscrições associadas ao seu app após a operação de exclusão.

Atualizar inscrição

O endpoint PUT permite atualizar o método de entrega ou a tag de uma inscrição. Atualizar o filter ou o event_type requer excluir a inscrição existente e adicionar uma nova.

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"
  }'

Resposta:

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 passos

Payloads de eventos

JSON de exemplo para cada tipo de evento de activity

Referência da API

Documentação completa dos endpoints

Webhooks

Configure a entrega via webhook

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Guia de início rápido da X Activity API para streaming de eventos

Obtendo IDs de usuário

Criando uma inscrição

Recebendo os eventos

Gerenciamento de inscrições

Criar inscrição

Listar inscrições

Excluir inscrição

Atualizar inscrição

Próximos passos

Payloads de eventos

Referência da API

Webhooks

​Obtendo IDs de usuário

​Criando uma inscrição

​Recebendo os eventos

​Gerenciamento de inscrições

​Criar inscrição

​Listar inscrições

​Excluir inscrição

​Atualizar inscrição

​Próximos passos

Payloads de eventos

Referência da API

Webhooks

Obtendo IDs de usuário

Criando uma inscrição

Recebendo os eventos

Gerenciamento de inscrições

Criar inscrição

Listar inscrições

Excluir inscrição

Atualizar inscrição

Próximos passos