Objetos

Os formatos referenciados acima, campo a campo. Os tipos são informais: string[] é um array de strings, A | null pode estar ausente.

Envelope

Presente em todo evento, no stream, em GET /v1/events e nas entregas por webhook.

Campo	Tipo	Significado
`v`	int	Versão do envelope. `1` hoje
`t`	string	Tipo do evento, conforme a tabela abaixo
`op`	create \| update \| delete	`create`, `update` (enriquecimento do mesmo id) ou `delete`
`id`	string	Identidade estável. Deduplique por ele
`ts`	int (ms)	Quando aconteceu no X, em ms desde a época Unix. O X não informa quando um perfil mudou, quando alguém foi seguido ou deixou de ser seguido, quando chegou um seguidor verificado nem quando uma publicação foi apagada: nesses eventos é quando detectamos
`sid`	string	Posição no stream para replay; presente no stream e no histórico
`target.id`	string	Id numérico no X da conta monitorada (para `search.match`, do autor da publicação)
`target.screen_name`	string	Nome de usuário da conta monitorada
`target.name`	string	O nome de exibição da conta
`d`	object	Payload específico do tipo

Payload de tweet

O d de tweet.create, tweet.reply, tweet.retweet e tweet.quote, e a base de search.match.

Campo	Tipo	Significado
`tweet_id`	string	O id da publicação, como string
`kind`	tweet \| reply \| retweet \| quote	Que tipo de publicação é
`text`	string	Texto completo (incluindo publicações longas)
`lang`	string \| null	Idioma detectado pelo X
`author`	User	A conta que publicou, como User completo — o mesmo objeto do autor de um `search.match`: nome de usuário, nome, bio, avatar, banner, contadores, verificação, localização, link e data de entrada. Num primeiro frame enxuto é a conta como lida pela última vez; o `update` a traz como lida junto com a publicação
`reply_to`	Brief+ \| null	Para respostas: a publicação respondida — um Brief mais `screen_name`, `tweet_id` e `user_id` do seu autor
`retweet_of`	Brief \| null	Para republicações: a publicação original
`quoted`	Brief \| null	Para citações: a publicação citada
`media`	string[]	URLs de imagem simples, uma por item de mídia
`media_items`	Media[]	Cada item de mídia com tipo, variantes de vídeo e dimensões
`urls`	string[]	Links expandidos na publicação
`article`	Article \| null	Em posts que apontam para um artigo do X: o artigo
`counts`	{reply, rt, like, quote, bookmark}	Contagens de respostas, republicações, curtidas, citações e itens salvos no momento em que lemos
`views`	int \| null	Contagem de visualizações, quando o X a expõe
`url`	string	Link canônico da publicação
`full`	bool	`false` em um primeiro frame `create` enxuto; `true` quando o evento traz a publicação inteira
`kind_final`	bool	`true` quando `kind` está definido. `false` apenas em um primeiro frame enxuto cujo `kind` é `tweet`: a publicação ainda pode se revelar uma citação, e o `update` do mesmo `id` resolve
`kind_was`	tweet \| null (update only)	Só no `update` que define o tipo de uma publicação, e só quando o primeiro frame dizia outra coisa: o tipo que esse frame tinha (`tweet` para uma publicação que se revelou uma citação)
`edit_of`	Brief \| null	Em `tweet.edit`: a versão que esta substitui (o id, e o texto e o autor quando os tínhamos)

Brief (resumo)

Uma publicação compacta embutida em outro evento: o original de uma republicação, a publicação citada, a publicação respondida ou uma publicação fixada.

Campo	Tipo	Significado
`id`	string	Id da publicação
`user`	string	Nome de usuário do autor
`name`	string	Nome de exibição do autor
`user_id`	string	Id numérico do autor
`text`	string	Texto completo
`media`	string[]	URLs de imagem simples
`media_items`	Media[]	Itens de mídia com tipo e variantes de vídeo
`created_ms`	int	Quando foi publicada, em ms desde a época Unix
`url`	string	Link da publicação

Mídia (Media)

Uma imagem, vídeo ou GIF. Vídeos trazem o MP4 de maior bitrate que conseguimos encontrar; url é o quadro de capa.

Campo	Tipo	Significado
`type`	photo \| video \| animated_gif	Tipo de mídia
`url`	string	URL da imagem, ou o quadro de capa de um vídeo
`expanded_url`	string	A página de mídia da publicação no X
`video_url`	string (video)	URL do MP4, maior bitrate disponível
`bitrate`	int (video)	Bitrate desse MP4
`duration_ms`	int (video)	Duração do vídeo
`width`	int	Largura original em pixels
`height`	int	Altura original em pixels

Artigo (Article)

Um artigo do X (post de formato longo) para o qual um post aponta. O primeiro frame traz title e preview; text é null até que o update com o mesmo id entregue o artigo completo.

Campo	Tipo	Significado
`id`	string	Id do artigo
`title`	string	Título
`preview`	string	As primeiras linhas do artigo
`text`	string \| null	Texto completo, com parágrafos separados por linhas em branco; `null` no primeiro frame
`cover`	string \| null	URL da imagem de capa
`images`	string[]	Imagens dentro do artigo
`url`	string	Link para o artigo no X

Payload de exclusão

O d de tweet.delete. Só é enviado para uma publicação que havíamos visto e que agora sumiu. Seu ts é quando a remoção foi detectada; o horário da própria publicação está no frame create anterior.

Campo	Tipo	Significado
`tweet_id`	string	O id da publicação excluída
`url`	string	Onde ela costumava estar

Payload de alteração de perfil

O d de todo evento profile.*. Para estes, op é update.

Campo	Tipo	Significado
`field`	string	Qual campo do perfil mudou; a mesma palavra que vem depois de `profile.` no tipo
`old`	any	O valor anterior
`new`	any	O novo valor
`tweet`	Brief (pinned only)	Para `profile.pinned`: a publicação recém-fixada
`old_tweet`	Brief (pinned only)	Para `profile.pinned`: a publicação fixada anteriormente, se a tínhamos

Payload de seguir

O d de follow.add, follow.remove e followers.verified.add.

Campo	Tipo	Significado
`user`	User	A outra conta, como um User completo

Carga de status da conta

O d de account.status. Um status é active, protected (publicações visíveis só para seguidores aprovados), suspended (pelo X) ou unavailable (desativada, excluída ou não visível por outro motivo). ts é quando detectamos a mudança.

Campo	Tipo	Significado
`old`	active \| protected \| suspended \| unavailable	O status anterior
`new`	active \| protected \| suspended \| unavailable	O status atual
`reason`	string \| null	O texto do X, quando houver (por exemplo `Suspended`)

Usuário (User)

Um perfil de conta completo, como embutido nos eventos de seguir e em search.match.

Campo	Tipo	Significado
`id`	string	Id numérico
`screen_name`	string	Nome de usuário
`name`	string	Nome de exibição
`bio`	string	Texto da bio
`avatar`	string	URL da imagem de avatar
`banner`	string \| null	URL da imagem de banner
`followers`	int	Contagem de seguidores
`following`	int	Contagem de seguindo
`tweets`	int	Contagem de publicações
`location`	string	Localização em texto livre
`url`	string \| null	Link do perfil expandido
`verified`	bool	Tem selo de verificação
`verified_type`	string \| null	`blue`, `business`, `government` ou `null`
`protected`	bool	Publicações visíveis apenas para seguidores aprovados
`created_at`	string (ISO-8601)	Quando a conta foi criada
`category`	string \| null	Categoria profissional, se a conta definiu uma

Payload de correspondência de busca

O d de search.match: um payload de tweet mais três campos sobre a correspondência. O target do envelope é o autor da publicação, que não precisa ser uma das suas contas monitoradas.

Campo	Tipo	Significado
`keyword.id`	int	Id da palavra-chave que correspondeu
`keyword.query`	string	A busca dela
`keyword.label`	string \| null	O rótulo dela, se você definiu um
`author`	User	O perfil completo do autor
`author_is_target`	bool	`true` se o autor também é uma conta monitorada neste sistema
`…`	TweetPayload	Todos os campos do payload de tweet

Conta monitorada

Uma conta que você monitora, como esta chave a vê.

Campo	Tipo	Significado
`id`	string	Id numérico no X. Nunca muda: indexe seus dados por ele
`screen_name`	string	O nome de usuário atual. Pode mudar; `profile.screen_name` avisa você
`name`	string	Nome de exibição
`previous_screen_names`	string[]	Nomes de usuário que a conta teve antes, o mais recente primeiro. Cada um ainda a identifica em `/v1/monitor/targets/{target}`
`push_ready`	bool	Todos os tipos de evento que você assina para esta conta estão sendo coletados em tempo real. `false` não retém nada: a conta é monitorada desde o momento em que é assinada e seus eventos são entregues conforme são coletados, então não espere por esta flag para tratá-los
`last_push_at`	datetime \| null	Última vez que um evento em tempo real chegou para ela
`last_poll_at`	datetime \| null	Última vez que sua linha do tempo foi lida
`state`	"subscribed"	Sempre `subscribed` aqui; resoluções pendentes têm seu próprio formato
`event_types`	string[]	Os tipos de evento entregues para esta conta; vazio significa todos os que sua chave permite
`event_types_all`	bool	`true` quando `event_types` está vazio

Conta monitorada pendente

O que GET /v1/monitor/targets/{target} retorna enquanto uma conta que você pediu ainda está sendo resolvida.

Campo	Tipo	Significado
`screen_name`	string \| null	O nome de usuário que você pediu, se pediu por nome
`user_id`	string \| null	O id de usuário que você pediu, se pediu por id
`state`	"queued"	Sempre `queued`
`queued_at`	int (unix s)	Quando você pediu
`event_types`	string[]	Os tipos de evento escolhidos, aplicados assim que for resolvida
`event_types_all`	bool	`true` quando `event_types` está vazio

Palavra-chave

Uma busca que você observa na busca do X.

Campo	Tipo	Significado
`id`	int	Id numérico; use-o para excluir
`query`	string	A busca, na sintaxe de busca do X
`label`	string \| null	Seu rótulo, ecoado em toda correspondência
`active`	bool	`false` se o operador a pausou
`hits`	int	Correspondências entregues até agora
`last_hit_at`	datetime \| null	Última correspondência
`last_run_at`	datetime \| null	Última pesquisa

Conta

O que GET /v1/account retorna sobre a chave que você usou.

Campo	Tipo	Significado
`name`	string	O nome da chave, conforme emitida
`plan`	string	Predefinição do plano
`key_id`	string	Id curto da chave, seguro para citar em pedidos de suporte
`scopes`	string[]	Escopos que a chave possui
`event_types`	string[]	Lista de tipos de evento permitidos para toda a chave, gerida por nós; vazia significa todos
`event_types_all`	bool	`true` quando o filtro está vazio
`limits.max_targets`	int	Limite de contas monitoradas
`limits.max_conns`	int	Limite de WebSockets simultâneos
`limits.max_keywords`	int	Limite de palavras-chave
`limits.requests_per_minute`	int	Orçamento de requisições por minuto
`usage.targets`	int	Contas monitoradas no momento
`usage.keywords`	int	Palavras-chave observadas no momento

Webhook

O que GET /v1/account/webhook retorna.

Campo	Tipo	Significado
`url`	string \| null	O endpoint registrado
`stats`	{ok, http_`…}`	Contadores de entrega: `ok`, e um `http_<code>` para cada status de falha visto

Campo	Tipo	Significado
`count`	int	Itens nesta página
`has_more`	bool	Se existe outra página
`next_cursor`	string \| null	Passe de volta como `?cursor=`; `null` no fim

Resultado do lote

Uma entrada por item enviado a POST /v1/monitor/targets:batch, na mesma ordem.

Campo	Tipo	Significado
`index`	int	Posição do item na sua requisição
`status`	int	O status HTTP que o endpoint de item único teria retornado
`data`	object (on success)	O corpo de resposta do item único, em caso de sucesso
`error`	{code, message, details?} (on failure)	O objeto de erro habitual, em caso de falha

Perfil (leitura)

O que GET /v1/users/{screen_name}, /v1/users/by-id/{user_id} e /v1/users/batch retornam por conta.

Campo	Tipo	Significado
`id`	string	Id numérico
`name`	string	Nome de exibição
`screen_name`	string	Nome de usuário
`bio`	string	Texto da bio
`location`	string	Localização em texto livre
`url`	string \| null	Link do perfil
`avatar`	string	URL da imagem de avatar
`banner`	string \| null	URL da imagem de banner
`pinned`	string \| null	Id da publicação fixada
`verified`	bool	Tem selo de verificação
`protected`	bool	Publicações visíveis apenas para seguidores aprovados
`followers`	int	Contagem de seguidores
`following`	int	Contagem de seguindo
`tweets`	int	Contagem de publicações

Tweet (leitura)

Uma publicação como retornada pelos endpoints de leitura. As mesmas informações do payload de tweet, no formato mais plano que nosso parser produz.

Campo	Tipo	Significado
`id`	int	Id da publicação, numérico
`created_ms`	int	Quando foi publicada, em ms desde a época Unix
`user_id`	int	Id numérico do autor
`user`	string	Nome de usuário do autor
`name`	string	Nome de exibição do autor
`text`	string	Texto completo
`lang`	string \| null	Idioma detectado pelo X
`reply_to`	string \| null	Nome de usuário respondido
`reply_to_status_id`	string \| null	Id da publicação respondida
`reply_to_user_id`	string \| null	Id da conta respondida
`conversation_id`	string	Id da publicação raiz do thread
`is_rt`	bool	É uma republicação
`rt_of`	Brief \| null	O original, para republicações
`is_quote`	bool	Cita outra publicação
`quoted`	Brief \| null	A publicação citada
`media`	string[]	URLs de imagem simples
`media_items`	Media[]	Itens de mídia com tipo e variantes de vídeo
`urls`	string[]	Links expandidos
`views`	int \| null	Contagem de visualizações
`counts`	{reply, rt, like, quote, bookmark}	Contagens de respostas, republicações, curtidas, citações e itens salvos
`article`	Article \| null	O artigo do X para o qual a publicação aponta, se houver (título, prévia, capa, imagens; o texto completo está em `GET /v1/tweets/{tweet_id}/article`)
`edit_of`	int \| null	Numa versão editada: o id da primeira versão; caso contrário, `null`
`edit_ids`	int[]	Os ids de todas as versões, a mais antiga primeiro; uma publicação nunca editada lista só a si mesma
`source`	string \| null	O cliente usado para publicar, como o X informa (um link HTML, por exemplo `Twitter for iPhone`)

Referência de usuário

O formato compacto usado nas leituras de listas de seguidores.

Campo	Tipo	Significado
`id`	string	Id numérico
`screen_name`	string	Nome de usuário
`name`	string	Nome de exibição