Agentes de código y MCP

export HEYSTEFF_API_KEY=sk_live_...

npm install -g @heysteff/cli
heysteff login

Vas a integrar este proyecto con heysteff, una plataforma de mensajería (WhatsApp, Instagram, Messenger, SMS y correo) con API REST.

Contexto
- Workspace de heysteff: <nombre de tu workspace> (slug: <slug>)
- API: https://app.heysteff.com/api/v1, con el header Authorization: Bearer $HEYSTEFF_API_KEY.
- La API key ya está en la variable de entorno HEYSTEFF_API_KEY. Nunca la escribas en el código, en un archivo del repositorio ni en esta conversación.
- Documentación para agentes: https://app.heysteff.com/api/v1/llms-full.txt (léela antes de escribir código), la especificación https://app.heysteff.com/api/v1/openapi.json y las reglas de https://developers.heysteff.com/AGENTS.md.
- SDK de TypeScript: @heysteff/sdk. CLI: @heysteff/cli (comando heysteff).

Qué necesito
1. Revisa el repositorio: lenguaje, framework, cómo se manejan las variables de entorno y si ya hay algo de mensajería.
2. Propón el paso mínimo para mandar un WhatsApp real y recibir la respuesta en este proyecto. Espera mi visto bueno antes de implementarlo.
3. Para enviar, usa POST /v1/messages (en TypeScript, heysteff.messages.send) con un header Idempotency-Key.
4. Para recibir, crea un endpoint para el webhook message:received: verifica la firma X-Heysteff-Signature sobre el cuerpo crudo, deduplica por X-Heysteff-Delivery-Id y responde 2xx enseguida. El secreto del webhook va en HEYSTEFF_WEBHOOK_SECRET.
5. Para probar el webhook en local, usa heysteff webhooks trigger http://localhost:<puerto>/<ruta> --secret <secreto>.
6. Si la key empieza con sk_test_, todo sale por el sandbox de heysteff y solo puedes escribirle a los teléfonos unidos al sandbox.

No inventes endpoints ni campos: si algo no está en llms-full.txt, dímelo.

Quiero conectar mi propio agente de IA a heysteff para que atienda a los clientes de mi negocio por WhatsApp y los demás canales conectados. Actúa como mi ingeniero de integración y avanza paso a paso.

Contexto
- Workspace de heysteff: <nombre de tu workspace> (slug: <slug>)
- API: https://app.heysteff.com/api/v1, con el header Authorization: Bearer $HEYSTEFF_API_KEY.
- La API key ya está en la variable de entorno HEYSTEFF_API_KEY. Nunca la escribas en el código, en un archivo del repositorio ni en esta conversación.
- Documentación para agentes: https://app.heysteff.com/api/v1/llms-full.txt (léela antes de escribir código), la especificación https://app.heysteff.com/api/v1/openapi.json y las reglas de https://developers.heysteff.com/AGENTS.md.
- SDK de TypeScript: @heysteff/sdk. CLI: @heysteff/cli (comando heysteff).

Antes de escribir código
1. Pregúntame qué hace mi negocio, qué debe resolver el agente solo y en qué casos tiene que entrar una persona del equipo.
2. Verifica el acceso con heysteff whoami (o GET /v1/conversations?limit=1). Nunca me pidas que pegue una API key ni un secreto en esta conversación: si falta, dime cómo dejarlo en la variable de entorno.
3. Revisa si ya hay un canal conectado con heysteff conversations list --limit 5. Si no hay, recomiéndame conectar WhatsApp en el panel (Configuración → Canales) o probar primero con el sandbox y una key sk_test_.
4. Revisa el repositorio y recomiéndame el setup mínimo. Espera mi visto bueno.

La integración
- Un endpoint para el webhook message:received: verifica X-Heysteff-Signature sobre el cuerpo crudo, deduplica por X-Heysteff-Delivery-Id, responde 2xx de inmediato y procesa en segundo plano.
- El webhook ya trae a quién responder (channel, external_user_id y channel_connection_id) y bot_paused. Si bot_paused es true, una persona tiene la conversación: no respondas. Lee el historial con GET /v1/conversations/{id}/messages.
- Pasa el historial y mis instrucciones a mi modelo y responde con POST /v1/messages (heysteff.messages.send), con un Idempotency-Key derivado del mensaje recibido para no responder dos veces.
- Las instrucciones del agente van en un archivo del repositorio, no dentro del código: qué hace el negocio, el tono, qué puede y qué no puede prometer, y cuándo pasar a una persona.
- Traspaso a una persona: cuando el agente no sepa o no deba seguir, que le diga al cliente que lo atiende alguien del equipo y llame a POST /v1/conversations/{id}/escalate (heysteff.conversations.escalate) con el motivo en reason. Eso pausa el bot, abre el caso en la bandeja y avisa a mi equipo; desde ahí los avisos llegan con bot_paused en true. Cuando el equipo termina, la conversación vuelve con POST /v1/conversations/{id}/bot y paused en false, o con POST /v1/conversations/{id}/resolve. No guardes ese estado de tu lado: consúltalo con GET /v1/conversations/{id}. La key necesita conversations:write.
- Si el agente de heysteff está encendido (Agente → Perfil en el panel), apágalo antes de activar el tuyo, o responderán los dos.

Pruebas
- Prueba primero con mi propia conversación: le escribo al número desde mi teléfono (o usa heysteff webhooks trigger en local) y revisamos la respuesta.
- No respondas a clientes reales sin mi permiso explícito: deja la respuesta limitada a mi teléfono de prueba hasta que te diga que la active para todos.

No inventes endpoints ni campos: si algo no está en llms-full.txt, dímelo.

/plugin marketplace add heysteff-com/agent-plugins
/plugin install heysteff@heysteff

npx skills add heysteff-com/agent-skills

mkdir -p ~/.claude/skills/heysteff && curl -fsSL https://developers.heysteff.com/skills/heysteff/SKILL.md -o ~/.claude/skills/heysteff/SKILL.md

claude mcp add --transport http heysteff "https://mcp.heysteff.com/mcp"

codex mcp add heysteff --url "https://mcp.heysteff.com/mcp"
codex mcp login heysteff

{
  "mcpServers": {
    "heysteff": {
      "url": "https://mcp.heysteff.com/mcp"
    }
  }
}