Pipeline de API: crear, configurar, iniciar, detener, medir y eliminar una campaña de Telegram de cualquier tipo

Índice: Pipelines de API — índice

Objetivo: crear, configurar, iniciar, detener, medir y eliminar una campaña de Telegram de cualquier tipo. Una campaña es una tarjeta (card_type: "campaign") que hace un trabajo para un proyecto en Telegram, con tus oráculos y en grupos. Todos los tipos comparten una tarjeta, un conjunto de rutas y un ciclo de vida; kind se elige al crear y no cambia.

Tipos

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

Pasos

1. Crear (siempre Paused).

POST /v0/my/campaigns
Idempotency-Key: camp-join-phuket-1
{"title": "Join Phuket chats", "kind": "mtproto_join_chats",
 "project_nonce": "<Pro project>", "tg_groups": ["<preset nonce>"], "oracles": ["<oracle nonce>"]}
→ {"nonce": "470360000000000001", "card_type": "campaign", "kind": "mtproto_join_chats",
   "status": "Paused", "is_active": false,
   "telegram_groups_list": ["<preset nonce>"], "oracles_list": ["<oracle nonce>"],
   "lists": {"telegram_groups": [{…tile…}], "oracles": [{…}], "posts": []}, …}

• title es obligatorio. project_nonce: un proyecto tuyo o sobre el que tienes x.
• Los slots tg_groups, oracles, posts aceptan nonces de tarjetas o de espacios como cadenas (no @handles). Los oráculos requieren x; grupos y publicaciones, r; la tarjeta privada de otra persona se rechaza. Vuelven como *_list (nonces) y lists.* (tiles).
• not_tg_groups: grupos que la campaña omite, como nonces de grupos o de espacios, con las mismas reglas que tg_groups; un espacio omite todos los grupos que contiene. Un grupo que está en ambas listas se omite; una lista vacía no omite nada. Vuelve como not_telegram_groups_list y lists.not_telegram_groups. Todos los tipos la respetan; una campaña de reacciones sin grupos reacciona en todos los grupos de sus oráculos excepto estos. Detalles: Pipeline de API: enviar tus grupos de Telegram, buscar grupos por palabra clave, lugar o rúbrica, evaluarlos y conectarlos a una campaña
• agenda: una agenda intercambiable tuya o que puedes ejecutar (si no, 400).
• workspaces: ["<ws>"] coloca la tarjeta en espacios en los que puedes escribir.
• Conjuntos fijos: speed x_slow | slow | medium | fast | x_fast (por defecto medium); mode linear | magnet; batch_window 15m | 30m | 60m | 3h | 6h | 12h | 24h | 72h; batch_messages 50–2000; reactions 1–16 emojis.

2. Configurar. PATCH /v0/my/campaigns/{nonce} con cualquier campo de creación; un slot en el cuerpo reemplaza toda la lista. Un radar o un AI scout activos recogen en marcha los cambios de palabras clave, exclusiones, grupos, proyecto, auto y lotes.

3. Iniciar.

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

Cada comprobación fallida es un 400 con el motivo: assign this campaign to a project before activating, assigned project not found, project needs an active Pro membership to run campaigns, assign telegram groups before activating, assign oracles before activating, assign posts before activating, announcements require an agenda assigned: …, assign at least one reaction before activating, ai scout requires an agenda assigned.

• Tipos con oráculos (anuncios, unirse, salir, reacciones): si la campaña no puede iniciarse ahora mismo, start responde 400 o {"success": false, "status": "Paused"} y sigue Paused: inténtalo más tarde. Grupos u oráculos que en ejecución no se expanden a nada → Failed.
• Radar y AI scout: 200 con el nuevo status; si la llamada falla, lee la campaña con GET antes de reintentar.

4. Detener. POST …/stop → Paused (un radar conserva su configuración y sus coincidencias). Un 400 significa que no se detuvo: vuelve a llamar a stop.

5. Medir.

GET /v0/my/campaigns/{nonce}/performance
→ {"totals": {"sent": 40, "deleted": 3, "replied": 5, "reacted": 0, "groups": 25, "oracles": 1,
              "joined": 0, "join_pending": 0, "already_member": 0, …, "first_at": "…", "last_at": "…"},
   "timeline": [{"day": "2026-10-08", "sent": 0, "joined": 31, "reacted": 40, …}],
   "groups": [{"username": "example_group", "sent": 3, "deleted": 2, "replied": 0, "join_status": "already_member", …}],
   "join": {"member": 30, "pending": 4, "skipped": 2, "remaining": 0, "oracles": [{…, "flooded_until": null}]}}

GET /v0/my/campaigns/{nonce}/sends?page=1&limit=50
→ {"rows": [{"username": "example_group", "message_id": 17552, "oracle": "…", "post": "…",
             "sent_at": "…", "deleted_at": null, "replied_at": "…", "replies": 2}], "total": 40, "has_more": true, …}

Los resultados de un radar son coincidencias y salas en la bandeja de entrada, no envíos. Visitas a la página de destino por campaña: GET /v0/my/console/traffic/campaign?campaign=. Cabi.Chat Inbox — Leads

6. Eliminar. Detenla primero y luego DELETE /v0/my/campaigns/{nonce}.

Estados: Active, Paused, Completed, Cancelled, Failed. Cuando el proyecto pierde Pro, sus campañas activas se pausan.

Actividad de un oráculo

Lo que un oráculo hizo en todas las campañas (solo el dueño; si no, 404):

• GET /v0/my/oracles/{nonce}/performance: la misma forma que el rendimiento de una campaña, para este oráculo.
• GET /v0/my/oracles/{nonce}/campaigns → {"rows": [{"campaign": "…", "title": "…", "kind": "mtproto_announcements", "sent": 40, "replied": 5, "joined": 0, "join_pending": 0, "join_banned": 0, "join_dead": 0, "join_flood": 0, "already_member": 0, "left": 0, "reacted": 0, "groups": 25, "first_at": "…", "last_at": "…"}]}: una fila por campaña, la más reciente primero, como máximo 100.
• Sus grupos y publicaciones enviadas: GET /v0/my/oracles/{nonce} → groups_workspace, sent_posts_workspace; léelos con GET /v0/my/workspaces/{ws}?contained_limit=30.

Estados de membresía en estos informes: joined, join_pending (la solicitud espera a los admins), join_banned, join_dead (el grupo ya no existe), join_skipped, join_flood (Telegram pidió esperar), join_limit (la cuenta alcanzó un límite de Telegram para unirse), already_member, left, leave_failed, not_member.

En segundo plano

• El radar y el AI scout no necesitan un oráculo tuyo para leer grupos; los demás tipos actúan a través de tus oráculos.
• Las ejecuciones de IA (primeros mensajes de un radar, lotes del AI scout, respuestas a réplicas de anuncios) son uso de IA; su coste aparece en tu gasto de IA: Pipeline de API: ver tu gasto en IA. Precios: link

Reglas (quién puede hacer qué)

GET /v0/my/campaigns lista solo las campañas tuyas. Compartir una con un enlace (derechos, grant_ttl, quién puede reclamar): índice, «Compartir con enlaces»; cuando termina una concesión w, la campaña se pausa salvo que otra concesión w vigente la sostenga. Grafo de Cabi.Chat — Políticas de tarjetas

Superficie de la API