> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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. Referência para a X API v2 standard tier cobrindo activity.

export const Button = ({href, children}) => {
  return <div className="not-prose">
    <a href={href}>
      <button className="x-btn">
        <span>{children}</span>
        <svg width="3" height="24" viewBox="0 -9 3 24" class="h-6 rotate-0 overflow-visible"><path d="M0 0L3 3L0 6" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"></path></svg>
      </button>
    </a>
  </div>;
};

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

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

<Note>
  **Pré-requisitos**

  Antes de começar, você precisará de:

  * Uma [conta de desenvolvedor](https://developer.x.com/en/portal/petition/essential/basic-info) com um App aprovado
  * O [Bearer Token](/resources/fundamentals/authentication) do seu App
</Note>

***

## 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:**

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" "https://api.x.com/2/users/by/username/xdevelopers"
```

**Obter seu próprio user ID:**

```bash theme={null}
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:

```json theme={null}
{
    "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:

```json theme={null}
{
  "event_type": "profile.update.bio",
  "filter": {
    "user_id": "2244994945"
  },
  "tag": "Xdevelopers' bio updates"
}
```

Usaremos nosso [bearer token](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#bearer-token-also-known-as-app-only) (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)](https://docs.x.com/fundamentals/authentication/oauth-2-0/overview#oauth-2-0-authorization-code-flow-with-pkce) — consulte [Privacidade de eventos e autenticação](/x-api/activity/introduction#event-privacy-and-authentication) para detalhes.

```bash theme={null}
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:

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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](https://docs.x.com/x-api/webhooks/introduction) ou por um stream HTTP persistente. Neste exemplo, abriremos o stream HTTP persistente:

```bash theme={null}
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:

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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:

```bash theme={null}
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"
  }'
```

<Note>
  * 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](https://docs.x.com/x-api/webhooks/introduction) 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.
</Note>

**Resposta:**

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  https://api.x.com/2/activity/subscriptions
```

**Resposta:**

```json title="profile.update.bio" expandable lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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:

```bash theme={null}
curl -H "Authorization: Bearer YOUR_BEARER_TOKEN" \
  -X DELETE \
  https://api.x.com/2/activity/subscriptions/1976325569252868096
```

**Resposta:**

```json theme={null}
{
  "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.

```bash theme={null}
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:**

```json title="profile.update.bio" lines wrap icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Payloads de eventos" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-brackets.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=ed2428e77bab43e57800e1a590e982fa" href="/x-api/activity/event-payloads" width="24" height="24" data-path="icons/xds/icon-brackets.svg">
    JSON de exemplo para cada tipo de evento de activity
  </Card>

  <Card title="Referência da API" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-code.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=488e23401b19225b89acc0136d242219" href="/x-api/activity/activity-stream" width="24" height="24" data-path="icons/xds/icon-code.svg">
    Documentação completa dos endpoints
  </Card>

  <Card title="Webhooks" icon="webhook" href="/x-api/webhooks/introduction">
    Configure a entrega via webhook
  </Card>
</CardGroup>