Pipeline de API: escuchar grupos de Telegram para encontrar a quien te necesita: crear y ajustar un radar, trabajar sus coincidencias y hacer el primer contacto (borrador, envío, outreach automático)

Índice: Pipelines de API — índice

Objetivo: oír a las personas que en grupos de Telegram piden lo que ofrece tu proyecto, reunir sus mensajes como coincidencias, ajustar el radar y hacer el primer contacto: un borrador que apruebas tú, o outreach automático de tu oráculo.

Ciclo de vida común a todos los tipos: Pipeline de API: crear, configurar, iniciar, detener, medir y eliminar una campaña de Telegram de cualquier tipo. Grupos: Pipeline de API: enviar tus grupos de Telegram, buscar grupos por palabra clave, lugar o rúbrica, evaluarlos y conectarlos a una campaña. Un radar gratuito de 7 días para un proyecto nuevo: Pipeline de API: recibir un radar inicial gratuito de 7 días para tu proyecto y seguir sus coincidencias

Cómo funciona

Palabras → significado → contacto.

Pasos

1. Crear (Paused).

POST /v0/my/campaigns
Idempotency-Key: radar-nails-la-1
{"title": "Nail masters LA", "project_nonce": "<Pro project>",
 "keyword_groups": [["manicure", "pedicure", "nails"], ["looking for", "need", "recommend"]],
 "not_groups": [["vacancy", "hiring"]],
 "tg_groups": ["<preset nonce>"]}
→ {"nonce": "470370000000000001", "card_type": "campaign", "kind": "mtproto_radar",
   "status": "Paused", "is_outreach_enabled": false, "is_auto_enabled": false,
   "keyword_groups": […], "not_groups": […], "telegram_groups_list": ["<preset nonce>"], …}

kind es mtproto_radar por defecto. La respuesta trae también campos de otros tipos (speed, reactions, batch_*); ignóralos.

2. Iniciar.

POST /v0/my/campaigns/470370000000000001/start
→ {"success": true, "status": "Active", "is_active": true}

El primer inicio crea los espacios del radar y los comparte contigo: Matches (read), Canonical (read + write); después GET /v0/my/campaigns/{nonce} muestra matches_workspace y canonical_matches_workspace (y evicted_matches_workspace tras la primera exclusión). 400 típicos: project needs an active Pro membership to run campaigns, outreach requires oracles assigned, outreach requires an agenda assigned.

3. Leer coincidencias, las más nuevas primero.

GET /v0/my/workspaces/<matches_workspace>?contained_limit=200&contained_offset=0
→ {"contained": [{"card_type": "post", "nonce": "470370000000000101", "snippet": "…",
                  "source_url": "https://t.me/example_group/17552", "created_at": "…", …}],
   "contained_next_offset": 200, …}

Una coincidencia completa (autor, grupo): GET /v0/graph/posts/{nonce} → author_username, source_group, source_group_username, expires_at. Buscar dentro de las coincidencias: POST /v0/search/graph/keyword {"query": "gel", "card_type": "post", "workspace": "<matches_workspace>"}.

4. Ajustar.

5. Primer contacto (opcional). Activa outreach: PATCH {"oracles": ["<oracle or team workspace>"], "agenda": "<swappable agenda>", "is_outreach_enabled": true}.

Una coincidencia cada vez (solo el dueño):

POST /v0/my/campaigns/{nonce}/matches/{post}/draft
{"instructions": "mention the free first consultation"}
→ {"text": "…", "target_username": "…", "oracle_nonce": "…", "model": "…"}

POST /v0/my/campaigns/{nonce}/matches/{post}/outreach
{"text": "<the text you approved>"}
→ {"ok": true}

Cada una puede tardar un par de minutos; si falla, vuelve a intentarlo. 400 típicos: outreach is not enabled on this radar, no oracle available: …, all candidates already outreached for this project, no human outreach candidate in post.

Automático: marca 5 o más como canónicas y luego PATCH {"is_auto_enabled": true}.

6. Seguir los resultados. Las conversaciones son salas en tu bandeja de entrada: Pipeline de API: supervisar las conversaciones de tus oráculos: desactivar o activar el oyente, cerrar un handoff, fijar la agenda de una sala, pedir al oráculo que continúe. performance y sends cuentan publicaciones en grupos, así que en un radar se quedan en cero.

7. Detener, eliminar, compartir. POST …/stop pausa (configuración y coincidencias se conservan); detén antes de DELETE. Compártelo con un enlace (índice, «Compartir con enlaces»): r deja a quien lo reclama leer configuración y estado; w, además, editar palabras clave e iniciar / detener. Matches, Canonical y Evicted son espacios que Cabi.Chat comparte contigo: tu enlace no llega a ellos.

8. De dónde vienen tus coincidencias. Los grupos en los que tu radar oye coincidencias, ordenados: primero los de más coincidencias, luego los de más autores distintos.

GET /v0/my/campaigns/{nonce}/source_groups?days=14&limit=50
→ {"campaign": "470370000000000001", "days": 14,
   "groups": [{"nonce": "…", "handle": "tgg.example_group", "title": "…", "members": 13934,
               "matches": 41, "authors": 29, "last_seen": "…"}, …]}

Reglas

Superficie de la API

Endpoint Para qué FE IA / oráculo
POST /v0/my/campaigns Crear el radar sí sí
GET /v0/my/campaigns, GET /v0/my/campaigns/{nonce} Lista; configuración, estado, espacios sí sí
PATCH /v0/my/campaigns/{nonce} Palabras clave, exclusiones, grupos, oráculos, agenda, outreach, auto sí sí
POST /v0/my/campaigns/{nonce}/start, /stop Iniciar / pausar sí sí
GET /v0/my/workspaces/{matches_workspace} Leer coincidencias sí sí
GET /v0/graph/posts/{nonce} Detalle de una coincidencia: autor, grupo sí sí
POST /v0/search/graph/keyword con workspace Buscar dentro de las coincidencias sí sí
POST / DELETE /v0/my/workspaces/{canonical}/{post} Marcar / desmarcar como canónica sí sí
POST /v0/my/campaigns/{nonce}/matches/evict Excluir coincidencias (negativas) sí (Excluir) sí
POST /v0/my/campaigns/{nonce}/matches/sweep Excluir lo que ahora descartan las exclusiones sí sí
POST /v0/my/campaigns/{nonce}/matches/{post}/draft El oráculo redacta un primer mensaje sí (Borrador de contacto) la IA propia del usuario
POST /v0/my/campaigns/{nonce}/matches/{post}/outreach Enviar el texto aprobado sí (Enviar) la IA propia del usuario
DELETE /v0/my/campaigns/{nonce} Eliminar (detener antes) sí rara vez
POST /v0/my/links, GET /v0/my/links/{link}/grants Compartir el radar; quién lo tiene sí sí
GET /v0/my/campaigns/{nonce}/source_groups Grupos de donde vienen las coincidencias, ordenados no sí
POST /v0/my/campaigns/{nonce}/source_groups/workspace Guardar ese ranking como espacio no tu token

Mentioned