Pipeline de API: enviar tus grupos de Telegram, buscar grupos por palabra clave, lugar o rúbrica, evaluarlos y conectarlos a una campaña

Índice: Pipelines de API — índice

Objetivo: elegir los grupos de Telegram en los que trabaja una campaña: enviar tus propios grupos por nombre de usuario, encontrar más en el índice abierto por palabra clave, lugar o rúbrica, evaluarlos, conectar grupos o presets de grupos a una campaña y excluir grupos de ella.

Modelo

• Un grupo es una tarjeta telegram_group con handle tgg.<username>. Las tarjetas de grupo pertenecen a Cabi.Chat: cualquier usuario con sesión iniciada puede leerlas y usarlas; nadie las edita. Las llamadas anónimas no ven grupos.
• Un preset es un espacio de grupos; los presets se anidan. Tú eres dueño de presets, nunca de tarjetas de grupo.
• tg_groups de una campaña acepta nonces de grupos, de presets o ambos. Los presets se expanden durante la ejecución a los grupos a los que llega el dueño de la campaña.

A. Enviar tus propios grupos

1. Envía los nombres de usuario. Una llamada crea un preset nuevo y registra cada nombre.

POST /v0/my/telegram_groups
Idempotency-Key: groups-phuket-1
{"title": "Phuket expats", "project": "<project nonce>",
 "telegram_group_handles": ["@example_expats", "https://t.me/example_market", "t.me/+AbCdEf"]}
→ {"workspace": {"nonce": "470350000000000001", "card_type": "workspace", "visibility": "Private", …},
   "handles": [
     {"handle": "t.me/+AbCdEf", "state": "rejected"},
     {"handle": "example_expats", "state": "contained", "nonce": "470350000000000002"},
     {"handle": "example_market", "state": "proposed", "nonce": "470350000000000003"}],
   "proposals_workspace": "470350000000000005"}

• El cuerpo es la creación de un espacio (title, content, project, visibility, …) más telegram_group_handles.
• A los nombres se les quitan espacios, https://, t.me/, @ y la / final, y se pasan a minúsculas; válidos: [a-z0-9_], 4 caracteres o más. Los enlaces de invitación (t.me/+…, t.me/joinchat/…) y t.me/s/… quedan rejected. Los duplicados se unen.
• contained: ya está en el índice y ahora en tu preset; nonce es el grupo.
• proposed: nuevo para Cabi.Chat y en cola de revisión; nonce es la propuesta, no un grupo.
• Cada llamada crea un preset nuevo; para añadir grupos conocidos a un preset existente usa su nonce (paso 3).

2. En segundo plano: revisión (asíncrona). Cabi.Chat revisa cada nombre propuesto: debe ser un grupo público (no un canal de difusión) y no estar marcado como scam. Los que pasan se añaden al índice y a tu preset; los demás no.

3. Mira el resultado.

GET /v0/my/workspaces/470350000000000001?contained_limit=200
→ {"contained": [{"card_type": "telegram_group", "nonce": "…", "title": "Example market", …}], "contained_next_offset": null}

Un nombre: GET /v0/graph/resolve/@tgg.example_market responde en cuanto el grupo está en el índice. Los grupos que pasan la revisión aparecen en tu preset.

Añadir un grupo conocido a cualquiera de tus presets: POST /v0/my/workspaces/{ws}/{group nonce} → 204; quitarlo: DELETE en la misma ruta.

B. Buscar grupos en el índice

Palabra clave:

POST /v0/search/graph
{"query": "phuket", "card_type": "telegram_group", "limit": 20, "page": 1}
→ {"hits": [{"card_type": "telegram_group", "nonce": "…", "handle": "tgg.example_phuket",
            "title": "…", "item_count": 13934, "location": {…}, …}],
   "total_hits": 115, "page": 1, "total_pages": 6}

/v0/search/graph combina palabras clave y significado; /keyword y /vector usan solo una de las dos. query se corta a 200 caracteres.

Lugar. Los filtros aceptan nonces de lugar (tarjetas de rúbrica de tipo place), no geonameids ni códigos ISO:

1. GET /v0/search/geo/cities?q=phuket → {"geonameid": 1151254, "name": "Phuket", "country_iso": "TH", …}
2. GET /v0/graph/resolve/@rub.geo-1151254 → {"card_type": "rubric", "nonce": "<place nonce>", "kind": "place"}. Un país es @rub.geo-<iso lowercase> (código ISO en minúsculas), p. ej. @rub.geo-th.
3. {"query": "", "card_type": "telegram_group", "filters": {"locations": ["<place nonce>"], "exclude_terms": ["rent"]}}

locations y places_in coinciden con el lugar y todo lo que contiene. Los nonces de lugar van solo ahí; dentro de rubrics no coinciden con nada.

Rúbrica: "filters": {"rubrics": [["<rubric nonce>"]]}; los arrays internos son OR, el externo AND; rubrics_not excluye. Buscar una rúbrica: {"query": "dating", "card_type": "rubric", "filters": {"kind": "tag"}}.

Dentro de un preset: añade "workspace": "<preset nonce>".

Claves de filtro permitidas: rubrics, rubrics_not, rubrics_in, locations, places_in, tags_in, project, preference_countries, preference_city {nonce, lat, lon}, radius_km, roots_only, kind, card_type, exclude_terms; cualquier otra → 400 unknown filter: <key>.

El número de miembros y las valoraciones están en la vista general de cada grupo (abajo). Los grupos añadidos hace poco se encuentran mejor por palabra clave.

Evaluar un grupo:

GET /v0/graph/telegram_groups/@tgg.example_phuket/overview
→ {"tile": {…}, "username": "example_phuket", "members_count": 13934,
   "stats": {"spam": 10.4, "density": 13.8, "openness": 60.9, "moderation": 17.0,
             "audience": 58.1, "pace": 34.0, "msgs_per_day": 221.5, "sample": 200, "rated_at": "…"},
   "mine": {"totals": {"sent": 0, "deleted": 0, "replied": 0, "joined": 0, …}, "timeline": […], "campaigns": […], "replies": […]}}

Las valoraciones van de 0 a 100; stats es null hasta que el grupo se valora. mine es tu propio historial en ese grupo. La página del grupo sin estadísticas: GET /v0/graph/telegram_groups/{nonce | @tgg.<username>}.

Presets listos (GET /v0/graph/workspaces/{ident}?contained_limit=&contained_offset=): @ws.tgg.geo-<geonameid>.2026-09-12 (p. ej. @ws.tgg.geo-1151254.2026-09-12, Phuket) y @ws.tgg.iab-<topic>.2026-09-12 (p. ej. @ws.tgg.iab-travel.2026-09-12): instantáneas del 2026-09-12.

Listas que se actualizan solas. Algunas listas públicas de grupos las mantiene Cabi.Chat de forma automática y cambian por sí solas, por ejemplo grupos con mucho spam o grupos donde se borran muchos mensajes. Llevan la rúbrica «Auto-maintained» (encuéntrala con {"query": "Auto-maintained", "card_type": "rubric"} y luego busca espacios con esa rúbrica). Úsalas como presets, por ejemplo en not_tg_groups para que una campaña no entre en esos grupos.

C. Poner grupos en una campaña

PATCH /v0/my/campaigns/<campaign nonce>
{"tg_groups": ["<preset nonce>", "<group nonce>"]}

• La lista reemplaza todo el slot. Las entradas son nonces numéricos como cadenas (no @handles). La tarjeta privada de otra persona → 400 tg_groups: card <n> not found or not available to you.
• La respuesta devuelve el slot como telegram_groups_list (nonces) y lists.telegram_groups (tiles).
• Conecta grupos que ya estén en el índice; los que siguen en revisión entran en tu preset cuando la pasan. Tipos y ciclo de vida: Pipeline de API: crear, configurar, iniciar, detener, medir y eliminar una campaña de Telegram de cualquier tipo

Excluir grupos. not_tg_groups lista los grupos que la campaña omite; acepta las mismas entradas que tg_groups. Sirve para quitar algunos grupos de un preset listo:

PATCH /v0/my/campaigns/<campaign nonce>
{"tg_groups": ["<preset nonce>"], "not_tg_groups": ["<group nonce>", "<other preset nonce>"]}

• Un grupo que está en ambas listas se omite; un preset en la lista de exclusión omite todos sus grupos.
• [] no omite nada y borra las exclusiones anteriores; si no envías el campo, la lista queda como estaba.
• Vuelve como not_telegram_groups_list (nonces) y lists.not_telegram_groups (tiles).

Superficie de la API