Quickstart

Esta guía te muestra cómo conectarte a filtered stream para recibir Posts casi en tiempo real que coincidan con tus reglas de filtrado.

Requisitos previosAntes de comenzar, necesitarás:

Una cuenta de desarrollador
El Bearer Token de tu App (que se encuentra en la Developer Console en “Keys and tokens”)

Crea una regla de filtrado

Las reglas definen qué Posts recibir. Usa operadores para hacer coincidir palabras clave, hashtags, usuarios y más.Regla de ejemplo: coincide con Posts que contengan “cat” con imágenes:

cat has:images

Construir una regla

Aprende la sintaxis y los operadores de las reglas

Añade la regla a tu stream

Añade tu regla usando el endpoint de reglas. Incluye un tag para identificar qué regla coincidió con cada Post:

cURL

curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "add": [
      {"value": "cat has:images", "tag": "cats with images"}
    ]
  }'

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Añade una regla al filtered stream
response = client.filtered_stream.add_rules(
    add=[{"value": "cat has:images", "tag": "cats with images"}]
)

for rule in response.data:
    print(f"Rule added: {rule.id} - {rule.value}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Añade una regla al filtered stream
const response = await client.filteredStream.addRules({
  add: [{ value: "cat has:images", tag: "cats with images" }],
});

response.data?.forEach((rule) => {
  console.log(`Rule added: ${rule.id} - ${rule.value}`);
});

Respuesta:

{
  "data": [
    {
      "id": "1273026480692322304",
      "value": "cat has:images",
      "tag": "cats with images"
    }
  ],
  "meta": {
    "sent": "2024-01-15T10:30:00.000Z",
    "summary": {
      "created": 1,
      "not_created": 0,
      "valid": 1,
      "invalid": 0
    }
  }
}

Verifica tus reglas

Lista todas las reglas activas para confirmar que tu regla fue añadida:

cURL

curl "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Obtén todas las reglas activas
response = client.filtered_stream.get_rules()

for rule in response.data:
    print(f"Active rule: {rule.id} - {rule.value}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Obtén todas las reglas activas
const response = await client.filteredStream.getRules();

response.data?.forEach((rule) => {
  console.log(`Active rule: ${rule.id} - ${rule.value}`);
});

Conéctate al stream

Abre una conexión persistente para recibir Posts coincidentes:

cURL

curl "https://api.x.com/2/tweets/search/stream?\
tweet.fields=created_at,author_id&\
expansions=author_id&\
user.fields=username" \
  -H "Authorization: Bearer $BEARER_TOKEN"

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Conéctate al filtered stream
for post in client.filtered_stream.stream(
    tweet_fields=["created_at", "author_id"],
    expansions=["author_id"],
    user_fields=["username"]
):
    print(f"New post: {post.data.text}")
    print(f"Matching rules: {post.matching_rules}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Conéctate al filtered stream
const stream = client.filteredStream.stream({
  tweetFields: ["created_at", "author_id"],
  expansions: ["author_id"],
  userFields: ["username"],
});

for await (const post of stream) {
  console.log(`New post: ${post.data?.text}`);
  console.log(`Matching rules: ${post.matching_rules}`);
}

Procesa los Posts entrantes

Los Posts coincidentes se transmiten como objetos JSON:

{
  "data": {
    "id": "1234567890",
    "text": "Look at this cute cat! 🐱",
    "author_id": "9876543210",
    "created_at": "2024-01-15T10:35:00.000Z",
    "edit_history_tweet_ids": ["1234567890"]
  },
  "includes": {
    "users": [
      {
        "id": "9876543210",
        "username": "catperson"
      }
    ]
  },
  "matching_rules": [
    {
      "id": "1273026480692322304",
      "tag": "cats with images"
    }
  ]
}

El array matching_rules muestra qué reglas coincidieron con el Post, usando las etiquetas que definiste.

Elimina reglas (opcional)

Elimina reglas por su ID:

cURL

curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \
  -H "Authorization: Bearer $BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "delete": {
      "ids": ["1273026480692322304"]
    }
  }'

from xdk import Client

client = Client(bearer_token="YOUR_BEARER_TOKEN")

# Elimina reglas por ID
response = client.filtered_stream.delete_rules(
    delete={"ids": ["1273026480692322304"]}
)
print(f"Deleted: {response.meta.summary.deleted}")

import { Client } from "@xdevplatform/xdk";

const client = new Client({ bearerToken: "YOUR_BEARER_TOKEN" });

// Elimina reglas por ID
const response = await client.filteredStream.deleteRules({
  delete: { ids: ["1273026480692322304"] },
});
console.log(`Deleted: ${response.meta?.summary?.deleted}`);

Gestionar tu conexión

Señales de keep-alive

El stream envía líneas en blanco (\r\n) cada 20 segundos. Si no recibes datos o un keep-alive durante 20 segundos, vuelve a conectarte.

Desconectarse

Presiona Ctrl+C para cerrar la conexión o cierra la ventana de tu terminal.

Límites de conexión

Solo se permite una conexión por App. Abrir una nueva conexión cerrará cualquier conexión existente.

Próximos pasos

Construir una regla

Aprende la sintaxis de las reglas

Referencia de operadores

Todos los operadores disponibles

Manejo de desconexiones

Reconéctate de forma controlada

Referencia de la API

Documentación completa del endpoint

Getting Started

Products

Fundamentals

Partners & Customers

Resources

Quickstart

Construir una regla

Gestionar tu conexión

Próximos pasos

Construir una regla

Referencia de operadores

Manejo de desconexiones

Referencia de la API

Construir una regla

​Gestionar tu conexión

​Próximos pasos

Construir una regla

Referencia de operadores

Manejo de desconexiones

Referencia de la API

Gestionar tu conexión

Próximos pasos