# Chatia · Instrucciones para Agentes IA

> **Cómo usar este archivo**: pegá esta URL en Claude Code, Cursor,
> Codex, ChatGPT GPTs, AI agents que estés construyendo:
> `https://www.chatia.pro/AGENTS.md`
>
> Tu agente IA externo carga este archivo como contexto y queda con
> total autonomía para crear, publicar y embeber agentes Chatia para
> tus users.
>
> Versión: 0.2 · última revisión: mayo 2026

---

## Quién sos

Sos un agente IA con la tarea de **crear agentes Chatia para tus users**
en automático. Chatia es un SaaS LATAM que despliega agentes de IA
conversacionales en webchat + WhatsApp + Instagram + Messenger +
Telegram en menos de 5 minutos.

Cuando el user te pide "creame un agente para mi negocio", ejecutás el
flow completo: confirmar API key → inferir vertical → elegir tools →
redactar prompt → llamar al endpoint → devolver los links listos.

---

## Reglas duras (NUNCA romper)

1. **NO inventes endpoints**. La spec autoritativa está en
   `https://www.chatia.pro/SKILL.md`. Solo usás endpoints que aparecen
   ahí o en `https://www.chatia.pro/api/developers/events/catalog` (live).

2. **NO compongas URLs manualmente**. El response de
   `POST /api/developers/agents` ya trae `chat_url`, `dashboard_url`,
   `widget_snippet` y `wordpress_plugin_url` absolutos — devolvélos al
   user copy-paste sin tocar.

3. **NO pidas la API key plain text al user en el chat**. Pedile que la
   cargue como variable de entorno `CHATIA_API_KEY`. Si no la tiene,
   guialo a `/dashboard/developers` para crearla.

4. **NO uses `instagram_business_*` scopes** para Facebook Login. Para
   IG, Chatia usa `instagram_*` (legacy en nombre, vigentes en uso). Si
   no entendés esto, no es asunto tuyo — el cliente conecta IG desde el
   dashboard via OAuth, vos no manejás auth de canales.

5. **NUNCA expongas el `WEBHOOK_SECRET`** del cliente en logs ni
   responses. Solo se usa para verificar firmas con HMAC.

6. **Respetá rate limits**: 30/min `POST /agents`, 120/min `POST /events`,
   20/min `POST /webhooks/:id/test`. Implementá backoff exponencial
   ante 429.

---

## Setup que el user necesita (1 vez)

1. **Cuenta gratis** en `https://www.chatia.pro/register` — $3 USD welcome credit.
2. **API key** en `https://www.chatia.pro/dashboard/developers` — copiar
   inmediatamente, solo se muestra una vez.
3. **Variable de entorno**: `export CHATIA_API_KEY=chatia_...`.

Si el user dice "no tengo cuenta", devolvé estas 2 URLs como tarea
concreta y esperá. NO sigas hasta que tenga la key.

---

## Receta canónica: crear + publicar + embeber

```bash
curl -X POST https://www.chatia.pro/api/developers/agents \
  -H "Authorization: Bearer $CHATIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Soporte Cliente",
    "description": "Atiende FAQs, captura leads, escala a humano.",
    "system_prompt": "Sos un agente de soporte. Tono cálido, profesional. Si no podés resolver, capturá el lead y derivá.",
    "first_message": "¡Hola! ¿En qué puedo ayudarte?",
    "tools": ["capture_lead", "send_whatsapp_handoff", "send_nps_survey"],
    "publish": true
  }'
```

**Response trae 4 campos para devolver al user copy-paste**:

```json
{
  "id": 42,
  "chat_url":             "https://www.chatia.pro/chat/soporte-cliente-42",
  "dashboard_url":        "https://www.chatia.pro/dashboard/agents/42",
  "widget_snippet":       "<script src=\"https://www.chatia.pro/widget.js?slug=soporte-cliente-42\" defer></script>",
  "wordpress_plugin_url": "https://www.chatia.pro/wordpress",
  "tools": ["capture_lead", "send_whatsapp_handoff", "send_nps_survey"]
}
```

Tu mensaje al user debería verse así:

> Listo, creé tu agente **Soporte Cliente**.
> - **Probalo en vivo**: https://www.chatia.pro/chat/soporte-cliente-42
> - **Editar prompt / branding**: https://www.chatia.pro/dashboard/agents/42
> - **Pegá esto en tu sitio HTML** antes de `</body>`:
>   ```html
>   <script src="https://www.chatia.pro/widget.js?slug=soporte-cliente-42" defer></script>
>   ```
> - **¿Tu sitio es WordPress?** Bajá el plugin (~7 KB) en https://www.chatia.pro/wordpress

---

## Inferir el vertical y elegir tools

Inferí qué hace el negocio del user de su descripción y mapeá a un
tool-set. Si no podés inferir con confianza, preguntá una sola pregunta
acotada antes de crear el agente.

| Vertical | Tools default |
|---|---|
| Ventas / E-commerce | `capture_lead`, `send_whatsapp_handoff`, `update_lead_status`, `add_lead_note` |
| Soporte / FAQ | `query_knowledge`, `send_whatsapp_handoff`, `send_nps_survey` |
| Turnos / Agenda (clínicas, peluquerías, consultorías) | `create_calendar_event`, `list_availability`, `cancel_appointment`, `reschedule_appointment`, `capture_lead` |
| Recruitment / RRHH | `register_candidate`, `score_candidate`, `flag_for_review`, `send_email` |
| Mixto / no claro | combiná las primeras 4-5 más comunes y dejá lugar a iteración |

El catálogo vivo de tools está en
`GET https://www.chatia.pro/api/developers/skills`. Si el user pide algo
que no calza con las nativas, hay 2 opciones:

- **`http_request`** — tool nativa que pega HTTP a un endpoint custom del
  user. Útil para integraciones one-off.
- **Composio toolkits** — el dueño del agente conecta Gmail, Sheets,
  Calendar, Slack, Notion, HubSpot, Stripe (y +1000 apps) via OAuth desde
  el dashboard. NO se conectan via API, vos no las tocás.

---

## Redactar system_prompt y first_message

**system_prompt** debe ser:
- 2-4 oraciones (no un wall of text).
- En español rioplatense neutro (a menos que el user pida otra variante).
- Definir: rol, tono, cuándo capturar lead, cuándo escalar a humano.
- Sin "como modelo de IA" ni meta-referencias.

**first_message** debe ser:
- 1 saludo natural (≤ 15 palabras).
- Termina en pregunta o invitación abierta a que el user empiece a tipear.
- NO incluir el nombre del bot ("Soy Sofia, te puedo ayudar...") salvo que
  el negocio tenga branding fuerte de bot named.

Ejemplos buenos:

```
system_prompt: "Sos el asistente de la Clínica Dental Sonrisa. Atendés
consultas sobre tratamientos, agendás turnos en el calendar, y derivás
casos urgentes a un humano via WhatsApp. Sé empático y claro."

first_message: "¡Hola! ¿Querés sacar un turno o tenés una consulta?"
```

Ejemplo malo:

```
system_prompt: "Como agente de IA de la Clínica Dental Sonrisa, estoy
aquí para ayudarte..." [meta-referencia + relleno]

first_message: "¡Bienvenido al asistente virtual de la Clínica Dental
Sonrisa! Soy Sofia, tu asistente personal..." [demasiado largo]
```

---

## Canales adicionales (NO se conectan por API)

Si el user menciona "WhatsApp", "Instagram", "Messenger", "Telegram",
"Gmail", "Calendar", explicale que esos canales se conectan **desde el
dashboard del agente** con OAuth, no por API:

```
https://www.chatia.pro/dashboard/agents/{id}#integrations
```

Cada canal es 1 click → autorizar → listo. **No intentes conectarlos
desde tu código** — Chatia maneja todo el flujo OAuth y refresh de tokens
internamente.

Excepción: WhatsApp via Kapso. El user pega su Kapso API key en
`/dashboard/agents/{id}#channels`. Tampoco se hace por la API de Chatia.

---

## Webhooks: para que el user reciba eventos

Si el user quiere conectar el agente a su CRM, mandar mails al capturar
leads, o reaccionar a ventas, configurás webhooks:

```bash
curl -X POST https://www.chatia.pro/api/developers/webhooks \
  -H "Authorization: Bearer $CHATIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mi CRM",
    "url": "https://miempresa.com/chatia-webhook",
    "events": ["agent.lead.captured", "agent.sale.confirmed"]
  }'
```

Eventos disponibles (27 totales — catálogo vivo en
`GET /api/developers/events/catalog`):

| Grupo | Eventos |
|---|---|
| lifecycle | `agent.created`, `agent.published`, `agent.branding.updated` |
| conversation | `agent.message.created`, `agent.reply.created`, `agent.lead.captured`, `agent.tool.called`, `agent.handoff.requested` |
| whatsapp | `agent.message.delivered/read/failed`, `agent.outbound.skipped_24h_window`, `agent.phone_number.quality_changed/banned` |
| sales | `agent.sale.started`, `agent.sale.updated`, `agent.sale.confirmed` |
| clients | `client.created/updated/removed/password_reset`, `client.branding.updated`, `client.agent_grant.added/removed` |
| team | `client.team_member.added/removed` |
| portal | `portal.branding.updated` |

Si pasás `events: []` recibís todos. Verificá la firma con HMAC SHA256
sobre `${timestamp}.${rawBody}` usando el `secret` del webhook (lo ves en
el dashboard al crear, después queda enmascarado).

---

## Errores comunes y cómo manejarlos

| HTTP | Detail | Causa | Acción |
|---|---|---|---|
| 401 | Missing/Invalid API key | header ausente o key revocada | guiar al user a regenerar key en dashboard |
| 402 | insufficient_balance | welcome credit gastado | guiar a `/billing` para agregar tarjeta |
| 403 | agents_limit_reached | plan free + 1 agente ya creado | borrar agente o subir plan |
| 422 | validation error | tools no existen, body mal armado | verificar con `/api/developers/skills` |
| 429 | rate_limit | excediste el límite | leer `Retry-After` + backoff exponencial |
| 5xx | internal | bug de Chatia | retry con backoff 1, 2, 4, 8, 16s |

---

## Checklist autónomo (seguir en orden)

Cuando el user te pide "creame un agente Chatia para X":

- [ ] **Confirmar `CHATIA_API_KEY`** está disponible. Si no, redirigir a `/dashboard/developers`.
- [ ] **Inferir vertical** (ventas / soporte / turnos / RRHH / mixto).
- [ ] **Elegir tools** del mapping vertical de arriba.
- [ ] **Redactar `system_prompt`** 2-4 oraciones natural en español.
- [ ] **Redactar `first_message`** saludo natural ≤15 palabras.
- [ ] **Llamar `POST /api/developers/agents`** con `publish: true`.
- [ ] **Devolver los 4 links** del response (chat, dashboard, widget, wordpress).
- [ ] **Si user mencionó canales adicionales** → explicar OAuth en `/dashboard/agents/{id}#integrations`.
- [ ] **Si user tiene sitio (WP/Shopify/Wix)** → mostrar snippet adecuado.
- [ ] **Si user quiere CRM/notif** → guiar setup de webhooks.
- [ ] **(Opcional)** Sugerir cargar Knowledge base si hay docs / FAQs.

---

## Recursos

- **Docs interactivas**: https://www.chatia.pro/docs/api
- **Skill completo (más detalle)**: https://www.chatia.pro/SKILL.md
- **Catálogo de tools (live)**: `GET /api/developers/skills`
- **Catálogo de eventos (live)**: `GET /api/developers/events/catalog`
- **Integraciones disponibles**: https://www.chatia.pro/integrations
- **Plugin WordPress**: https://www.chatia.pro/wordpress
- **Soporte / contacto**: https://www.chatia.pro/contact