Novedades de la API

Superficie conversacional en v1 (WhatsApp, handoff, flujos)

Lo conversacional es núcleo de Met, así que sube a la superficie pública v1 (antes marcado fase 2). Aditivo — no rompe nada de la superficie inicial. 179 → 215 operaciones públicas.

Nuevos scopes:

• conversations:read — leer conversaciones WhatsApp/CRM que Met gestiona (7 ops: listar/leer conversaciones y mensajes, búsqueda, tool-calls).
• handoff:manage — autopilot on/off/pause + marcar leído (3 ops).
• channels:read — estado de canales y broadcasts, sin permiso de envío (3 ops).
• channels:send — envío WhatsApp (buttons/list/location/contact/reaction/reply/template), mensajes a contacto y broadcasts (crear/cancelar/editar/borrar) — 13 ops.

Flujos suben bajo automations: listar/leer y ejecutar/publicar/testear (10 ops).

Curación (importante):

• En Canales se exponen solo los métodos de envío. La configuración/conexión (tokens de WhatsApp, registro de webhook, phones, templates, config de canal) queda interna — nunca sale por SDK.
• El chat crudo (/conversations/:id/messages/stream) sigue interno: la vía pública para *ejecutar/conversar con el Met* es la façade Runs (F1). Aquí solo se exponen las lecturas de conversación.

Deudas de runtime (F1, antes de que esto sea alcanzable — hoy no hay auth por key):

• channels:send exige gating anti-abuso (límites de Meta, anti-spam) antes de estar vivo.
• Los payloads de conversación/mensaje deben curarse (no filtrar campos internos) al cablear los guards.

Runs — ejecución de Mets por API (el plano agéntico)

Llega Runs: ejecutar el Met de tu workspace por API, con memoria opcional y streaming. Es el corazón de "infraestructura agéntica como servicio". Aditivo. 248 → 251 operaciones públicas.

Nuevos endpoints (scopes runs:execute / runs:read):

• POST /workspaces/:id/runs — ejecuta el Met sobre input. Con conversation_id el run tiene memoria; sin él corre en una conversación efímera. stream: true → respuesta SSE con los eventos en vivo.
• GET /runs/:id — estado + salida de un run.
• GET /workspaces/:id/runs — historial paginado (cursor opaco, { data, has_more }).

Esquema público de eventos (estable, versionado): run.started, run.step, run.output, run.completed, run.failed. El run.step es una proyección curada del trace interno — expone tipo de paso, iteración, nombre de tool y actor; nunca prompts internos, inputs crudos de tools, costos de proveedor ni conteos de tokens.

Costo: cada run debita Energía por el mismo ledger de siempre, marcado execution_type='api' y atribuido a la key — el consumo por API aparece separado del chat interno en tu dashboard.

Forma del recurso (convención de recursos nuevos): id opaco run_<ULID> (ordenable por tiempo), object: "run", livemode (false en keys met_test_) y metadata libre.

Nota: el met del body es un hint informativo en v1 — el orquestador del workspace auto-rutea al especialista adecuado (mismo comportamiento que el chat). La gestión curada de Mets individuales llega con la fachada agents.

Integraciones — activar y ejecutar conectores MCP por API

Las integraciones MCP de Met (Shopify, Alegra, etc.) llegan a la API pública. Activa conectores, guarda sus credenciales y ejecuta sus tools desde tu código. Aditivo. 251 → 256 operaciones públicas.

Nuevos endpoints (scopes integrations:read / integrations:manage / integrations:execute):

• GET /workspaces/:id/integrations — catálogo + estado de conexión de cada integración.
• GET /workspaces/:id/integrations/:key/tools — tools disponibles de una integración.
• POST /workspaces/:id/integrations/:key/activate — activa la integración; opcional { credentials } (write-only).
• DELETE /workspaces/:id/integrations/:key — desactiva.
• POST /workspaces/:id/integrations/:key/tools/:tool — ejecuta una tool con el input del schema de la integración.

Reglas del camino público (importantes):

• Credenciales write-only: se guardan pero ningún GET las devuelve, ni enmascaradas. El estado observable es connection_status / last_tested_at.
• Errores del proveedor curados: si el tercero falla, recibes integration_upstream_error genérico — nunca el body crudo del proveedor (que podría traer credenciales o PII). El detalle queda en los logs internos.
• Allowlist opcional por key: una key puede restringirse a ejecutar solo tools específicas (mínimo privilegio para ISVs).
• Integración no activa → integration_not_active (409).

Agents — crear y configurar Mets por API

Cierra el ciclo agéntico: ahora puedes crear y configurar Mets por API, no solo ejecutarlos. Con Runs (ejecutar) + Agents (gestionar) + Skills/Functions/Integraciones (equipar), el Met completo es operable por código. Aditivo. 256 → 263 operaciones públicas.

Nuevos endpoints (scopes agents:read / agents:write):

• GET /workspaces/:id/agents — lista los Mets del workspace.
• POST /workspaces/:id/agents — crea un Met (name, title, mission, instructions).
• GET /agents/:id — detalle.
• PATCH /agents/:id — actualiza nombre, instrucciones, misión o estado (active).
• GET /agents/:id/skills — skills vinculadas al Met.
• POST /agents/:id/skills/:skillId — vincula una skill.
• DELETE /agents/:id/skills/:skillId — desvincula.

Diseño: es una fachada curada sobre el modelo interno de Mets — expone un contrato de "agente" limpio (name/instructions/mission) en vez de los item-endpoints crudos. Las skills se listan sin su prompt interno ni su config de conectores. La gestión fina de prompt (bloques, tools deshabilitadas) y los conectores MCP del Met llegan más adelante.

El ciclo completo por API: crear un Met (agents:write) → colgarle skills (agents:write) y conectores (integrations:manage) → ejecutarlo (runs:execute) → enterarte del resultado por webhook. Eso es infraestructura agéntica como servicio.

Funciones IA, Grupos de Mets, Webhooks entrantes, Recordatorios y Actividad

Cierre de huecos detectados cruzando el menú del producto contra la superficie. Aditivo. 215 → 248 operaciones públicas.

Nuevos scopes:

• functions:read / functions:write — Funciones IA (tools/código del Met): CRUD + link a un Met (8 ops).
• agents:read / agents:write — ahora en uso: Grupos de Mets (7 ops). *(La gestión completa de Mets llega con la fachada agents en F1.)*
• webhooks:manage — gestión de webhooks entrantes: CRUD, mappings, link a flujo, sample, rotate-secret (11 ops).
• events:read — feed de actividad/eventos del workspace (3 ops).
• reminders:read / reminders:write — Recordatorios (4 ops).

Notas de curación:

• POST /webhooks/:id/rotate-secret devuelve el secreto nuevo una sola vez (mismo patrón que crear una key) — es el owner rotando su propio secreto de ingress.
• GET /webhooks/:id/sample devuelve un payload de muestra del propio webhook del workspace.

Todavía interno (a propósito):

• Gestión de Mets (crear/configurar Mets) y sus conectores MCP → llegan con la fachada agents en F1 (los Mets son items; se necesita una superficie curada, no decorar item-endpoints). Es el hueco #1 de la visión agéntica, registrado en el plan.