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

# Introdução

> Transmita eventos em tempo real da atividade do usuário no X (Posts, curtidas, follows, mutes, blocks, DMs, menções e atualizações de perfil) via webhooks.

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

O grupo de endpoints X Activity API (XAA) permite que desenvolvedores acessem eventos de atividade que acontecem na Plataforma X.

Um desenvolvedor pode assinar eventos do seu interesse, como `profile.update.bio`, `post.create`, `post.delete` etc., e filtrar pelo User ID cujos eventos deseja receber. Os eventos correspondentes a esse User ID serão entregues ao seu app com latência inferior a um segundo.

## Mecanismos de entrega

Atualmente, a X Activity API oferece suporte aos seguintes mecanismos de entrega para enviar eventos ao seu app:

* Stream HTTP persistente
* [Webhook](/x-api/webhooks/introduction)

## Tipos de evento suportados

Atualmente, a X Activity API oferece suporte aos seguintes tipos de evento, organizados por categoria. Para ver um JSON de exemplo de cada tipo, consulte [Payloads de eventos](/x-api/activity/event-payloads).

### Eventos de Post

Os eventos de Post são acionados quando um usuário cria ou exclui um Post.

| Nome do evento        | Descrição                                                       | Filtros   |
| --------------------- | --------------------------------------------------------------- | --------- |
| `post.create`         | Disparado quando um usuário cria um Post                        | `user_id` |
| `post.delete`         | Disparado quando um usuário exclui um Post                      | `user_id` |
| `post.mention.create` | Disparado quando alguém @menciona o usuário filtrado em um Post | `user_id` |

<Note>
  **Eventos de Post via XAA vs Filtered Stream:** A X Activity API oferece suporte aos eventos `post.create` e `post.delete`. Assine por `user_id` para receber notificações em tempo real quando os usuários criarem ou excluírem Posts.

  Se você precisa de filtragem direcionada por palavras-chave, lógica booleana, segmentação geográfica, filtros de idioma ou qualquer um dos outros operadores que o Filtered Stream suporta, use o endpoint [Filtered Stream](/x-api/posts/filtered-stream/introduction) em vez disso.
</Note>

### Eventos de curtida

Os eventos de curtida são acionados quando um usuário curte um Post ou quando um dos Posts do próprio usuário é curtido.

| Nome do evento | Descrição                                                                | Filtros                |
| -------------- | ------------------------------------------------------------------------ | ---------------------- |
| `like.create`  | Disparado quando um usuário curte um Post ou um dos seus Posts é curtido | `user_id`, `direction` |

<Note>
  **Filtro de direção:** O evento `like.create` suporta um filtro `direction` opcional definido como `outbound` ou `inbound`. Use `outbound` para curtidas feitas pelo usuário e `inbound` para curtidas recebidas pelos Posts do usuário. Se nenhuma `direction` for especificada, tanto os eventos de curtida de entrada quanto os de saída serão entregues.

  **Evento privado:** `like.create` é um evento privado e requer autenticação no contexto do usuário (OAuth 2.0). Consulte [Privacidade e autenticação de eventos](#event-privacy-and-authentication) abaixo.
</Note>

### Eventos de seguir

Os eventos de seguir são acionados quando o usuário filtrado segue outro usuário ou é seguido por outro usuário.

| Nome do evento    | Descrição                                                 | Filtros   |
| ----------------- | --------------------------------------------------------- | --------- |
| `follow.follow`   | Disparado quando um usuário segue outro usuário           | `user_id` |
| `follow.unfollow` | Disparado quando um usuário deixa de seguir outro usuário | `user_id` |

### Eventos de perfil

Os eventos de perfil são acionados quando um usuário faz alterações nas informações do seu perfil.

| Nome do evento                   | Descrição                                                        | Filtros   |
| -------------------------------- | ---------------------------------------------------------------- | --------- |
| `profile.update.bio`             | Disparado quando um usuário atualiza a bio do seu perfil         | `user_id` |
| `profile.update.profile_picture` | Disparado quando um usuário atualiza a foto do seu perfil        | `user_id` |
| `profile.update.banner_picture`  | Disparado quando um usuário atualiza o banner do seu perfil      | `user_id` |
| `profile.update.screenname`      | Disparado quando um usuário atualiza o nome de exibição          | `user_id` |
| `profile.update.handle`          | Disparado quando um usuário atualiza o seu handle                | `user_id` |
| `profile.update.geo`             | Disparado quando um usuário atualiza a localização do seu perfil | `user_id` |
| `profile.update.url`             | Disparado quando um usuário atualiza a URL do site do seu perfil | `user_id` |
| `profile.update.verified_badge`  | Disparado quando um usuário atualiza o seu selo verificado       | `user_id` |
| `profile.update.affiliate_badge` | Disparado quando um usuário atualiza o seu selo de afiliado      | `user_id` |

### Eventos de chat

Os eventos de chat referem-se à nova camada de mensagens criptografadas, ou XChat.

| Nome do evento           | Descrição                                                               | Filtros   |
| ------------------------ | ----------------------------------------------------------------------- | --------- |
| `chat.received`          | Disparado quando um usuário recebe uma mensagem direta criptografada    | `user_id` |
| `chat.sent`              | Disparado quando um usuário envia uma mensagem direta criptografada     | `user_id` |
| `chat.conversation_join` | Disparado quando um usuário entra em uma conversa de chat criptografada | `user_id` |

### Eventos de DM legados

Os eventos de DM legados referem-se ao sistema de DM legado, sem criptografia.

| Nome do evento       | Descrição                                                                                                          | Filtros   |
| -------------------- | ------------------------------------------------------------------------------------------------------------------ | --------- |
| `dm.received`        | Disparado quando um usuário recebe uma mensagem direta não criptografada                                           | `user_id` |
| `dm.sent`            | Disparado quando um usuário envia uma mensagem direta não criptografada                                            | `user_id` |
| `dm.read`            | Disparado quando um usuário lê a mensagem de DM não criptografada do usuário filtrado, ou "confirmação de leitura" | `user_id` |
| `dm.indicate_typing` | Disparado quando um usuário está digitando uma mensagem para o usuário filtrado                                    | `user_id` |

### Eventos de notícias

Os eventos de notícias fornecem atualizações sobre tópicos em alta e manchetes selecionados pelo Grok.

| Nome do evento | Descrição                                           | Filtros   |
| -------------- | --------------------------------------------------- | --------- |
| `news.new`     | Novas tendências e manchetes selecionadas pelo Grok | `keyword` |

<Note>
  **Apenas Enterprise:** O evento `news.new` está disponível somente para contas nos níveis Enterprise e Partner no momento.
</Note>

### Eventos de Spaces

Os eventos de Spaces são acionados quando um usuário inicia ou encerra um Space.

| Nome do evento | Descrição                                    | Filtros   |
| -------------- | -------------------------------------------- | --------- |
| `spaces.start` | Disparado quando um usuário inicia um Space  | `user_id` |
| `spaces.end`   | Disparado quando um usuário encerra um Space | `user_id` |

### Eventos de silenciamento

Os eventos de silenciamento são acionados quando o usuário filtrado silencia ou dessilencia outro usuário.

| Nome do evento | Descrição                                             | Filtros   |
| -------------- | ----------------------------------------------------- | --------- |
| `mute.mute`    | Disparado quando um usuário silencia outro usuário    | `user_id` |
| `mute.unmute`  | Disparado quando um usuário dessilencia outro usuário | `user_id` |

<Note>
  **Eventos privados:** Os eventos de silenciamento são privados e requerem autenticação no contexto do usuário (OAuth 2.0) com o escopo `mute.read`. O filtro `user_id` corresponde ao usuário que executa a ação de silenciar ou dessilenciar — você não pode assinar notificações sobre um usuário *sendo* silenciado. Consulte [Privacidade e autenticação de eventos](#event-privacy-and-authentication) abaixo.
</Note>

### Eventos de bloqueio

Os eventos de bloqueio são acionados quando o usuário filtrado bloqueia ou desbloqueia outro usuário.

| Nome do evento  | Descrição                                             | Filtros   |
| --------------- | ----------------------------------------------------- | --------- |
| `block.block`   | Disparado quando um usuário bloqueia outro usuário    | `user_id` |
| `block.unblock` | Disparado quando um usuário desbloqueia outro usuário | `user_id` |

<Note>
  **Eventos privados:** Os eventos de bloqueio são privados e requerem autenticação no contexto do usuário (OAuth 2.0) com o escopo `block.read`. O filtro `user_id` corresponde ao usuário que executa a ação de bloquear ou desbloquear — você não pode assinar notificações sobre um usuário *sendo* bloqueado. Consulte [Privacidade e autenticação de eventos](#event-privacy-and-authentication) abaixo.
</Note>

Em versões futuras, a XAA será expandida para oferecer suporte a tipos de evento adicionais, incluindo interações sociais, engajamento com conteúdo, recursos de monetização e muito mais. Continuaremos atualizando nossa documentação à medida que novos tipos de evento se tornarem disponíveis.

## Privacidade e autenticação de eventos

A X Activity API distingue entre **eventos públicos** e **eventos privados**, em paridade com o app do X, conforme explicado abaixo.

### Eventos públicos

Os eventos públicos são atividades que uma conta de usuário pública realiza publicamente e que são visíveis a todos os usuários do X. Esses eventos são visíveis a todos os usuários na plataforma X e não exigem autenticação OAuth do usuário para serem visualizados.

**Eventos públicos atuais:**

* Atualizações de perfil (bio, foto, banner, localização, URL, alterações de nome de usuário)
* Criação de Post (`post.create`) e exclusão (`post.delete`)

Para esses eventos públicos, você pode criar assinaturas especificando o user ID no seu filtro e recebê-los via XAA.

### Eventos privados

Os eventos privados são atividades que exigem consentimento explícito do usuário por meio de autenticação OAuth. Um usuário precisa autenticar-se via X e conceder permissão explícita a um app de desenvolvedor para acessar esses eventos.

**Eventos privados atuais:**

* Curtidas (`like.create`)
* Chat criptografado recebido (`chat.received`)
* Chat criptografado enviado (`chat.sent`)
* DM recebido (`dm.received`)
* DM enviado (`dm.sent`)
* DM lido (`dm.read`)
* Indicador de digitação de DM (`dm.indicate_typing`)
* Menções em Posts (`post.mention.create`)
* Silenciamentos (`mute.mute`, `mute.unmute`) — requer o escopo `mute.read`
* Bloqueios (`block.block`, `block.unblock`) — requer o escopo `block.read`

**Requisitos de autenticação para eventos privados:**

* O usuário precisa autenticar a sua aplicação via OAuth 2.0
* A sua aplicação precisa obter os escopos OAuth apropriados
* O usuário precisa conceder explicitamente permissão para que o seu app acesse esses eventos
* Assinaturas para eventos privados só podem ser criadas para usuários que autorizaram a sua aplicação

## Limites de assinatura

A X Activity API tem diferentes limites de assinatura com base no nível da sua conta:

| Nível do pacote | Máximo de assinaturas |
| --------------- | --------------------- |
| Self-serve      | 1.500                 |
| Enterprise      | 75.000                |
| Partner         | 150.000               |

## Endpoints

| Método | Endpoint                                                                           | Descrição                        |
| :----- | :--------------------------------------------------------------------------------- | :------------------------------- |
| GET    | [`/2/activity/stream`](/x-api/activity/activity-stream)                            | Conectar ao stream de atividades |
| POST   | [`/2/activity/subscriptions`](/x-api/activity/create-x-activity-subscription)      | Criar uma assinatura             |
| GET    | [`/2/activity/subscriptions`](/x-api/activity/get-x-activity-subscriptions)        | Listar assinaturas               |
| PUT    | [`/2/activity/subscriptions/:id`](/x-api/activity/update-x-activity-subscription)  | Atualizar uma assinatura         |
| DELETE | [`/2/activity/subscriptions/:id`](/x-api/activity/deletes-x-activity-subscription) | Excluir uma assinatura           |

<Note>
  **Configuração da conta**

  Para acessar esses endpoints, você precisará de:

  * Uma [conta de desenvolvedor](https://developer.x.com/en/portal/petition/essential/basic-info) aprovada.
  * Autenticar-se usando as chaves e os tokens de um [App de desenvolvedor](/fundamentals/developer-apps) que esteja localizado dentro de um Project.

  Saiba mais sobre como obter acesso aos endpoints da X API v2 em nosso [guia de introdução](/x-api/getting-started/getting-access).
</Note>

<div className="flex gap-3">
  <Button href="/x-api/activity/quickstart">
    Início rápido
  </Button>

  <Button href="/x-api/activity/event-payloads">
    Payloads de eventos
  </Button>
</div>