# Instagram

> Maneja tus cuentas de Instagram por la API: leer y responder mensajes privados, gestionar automatizaciones, programar publicaciones y leer sus cifras.

Source: https://docs.whatsetter.com/es/developers/guides/instagram/

La API cubre una cuenta de Instagram de principio a fin, como el dashboard: quién le escribe, qué hacen el agente y las automatizaciones, y lo que publicas. Los mensajes privados funcionan como los de WhatsApp: los lees en `/conversations` y los respondes con `POST /messages`. Messenger, a través de la página de Facebook vinculada a una cuenta, funciona igual con `channel: facebook`.

Cada paso de abajo da una llamada cURL y el nombre de la [herramienta MCP](/es/developers/mcp/) que hace lo mismo desde un asistente IA.

## Endpoints

| Método | Ruta | Scope |
|---|---|---|
| GET | [`/instagram/accounts`](/api-reference/operations/listinstagramaccounts/) | `instagram:read` |
| GET | [`/conversations`](/api-reference/operations/listconversations/) | `conversations:read` |
| POST | [`/messages`](/api-reference/operations/sendmessage/) | `messages:send` |
| GET | [`/instagram/automations`](/api-reference/operations/listinstagramautomations/) | `instagram:read` |
| POST | [`/instagram/automations`](/api-reference/operations/createinstagramautomation/) | `instagram:write` |
| PATCH | [`/instagram/automations/{id}`](/api-reference/operations/updateinstagramautomation/) | `instagram:write` |
| DELETE | [`/instagram/automations/{id}`](/api-reference/operations/deleteinstagramautomation/) | `instagram:write` |
| POST | [`/instagram/posts`](/api-reference/operations/createinstagrampost/) | `instagram:write` |
| GET | [`/instagram/posts`](/api-reference/operations/listinstagramposts/) | `instagram:read` |
| GET | [`/instagram/posts/{id}`](/api-reference/operations/getinstagrampost/) | `instagram:read` |
| GET | [`/instagram/stats`](/api-reference/operations/getinstagramstats/) | `instagram:read` |
| GET | [`/instagram/insights/posts`](/api-reference/operations/listinstagrampostinsights/) | `instagram:read` |

## Antes de empezar

- Instagram debe estar activado en tu espacio y una cuenta conectada desde el dashboard. Si no, las rutas de Instagram responden `403 instagram_not_enabled`.
- La clave necesita `instagram:read` (e `instagram:write` para cambiar algo). Una clave de **Acceso completo** creada antes de estos endpoints no los lleva: crea una nueva ([Autenticación](/es/developers/authentication/)).
- Los mensajes privados no necesitan ningún scope de Instagram: `conversations:read` para leerlos, `messages:send` para responder.

## 1. Encontrar tus cuentas

Cada ruta de Instagram recibe un `account_id`. Con una sola cuenta puedes omitirlo; con varias, es obligatorio.

```bash
curl "https://app.whatsetter.com/api/v1/instagram/accounts" \
  -H "Authorization: Bearer ws_live_…"
```

MCP: `list_instagram_accounts`.

```json
{
  "data": [
    {
      "id": "68f1c2d3e4f5a6b7c8d9e0f1",
      "username": "acme.studio",
      "name": "Acme Studio",
      "status": "connected",
      "grants": { "messages": true, "publish": true, "insights": true },
      "facebook_page": { "name": "Acme Studio", "can_publish": true },
      "agent": { "campaign_id": "instagram-acme-studio-x7k2", "enabled": true, "all_dms": true },
      "triage": { "enabled": true, "answer_collab": false, "answer_support": false, "answer_personal": false },
      "human_pause_hours": 24
    }
  ]
}
```

| Campo | Significado |
|---|---|
| `status` | `connected`, o `needs_reconnect` cuando la conexión caducó: vuelve a conectar la cuenta desde el dashboard. |
| `grants` | Lo que permite la cuenta: mensajes privados, publicación, estadísticas. Una cuenta conectada antes de que se ofreciera la publicación debe volver a conectarse para publicar. |
| `agent` | El agente que responde (`campaign_id`), si está encendido, y si responde a todos los mensajes privados (`all_dms`) o solo a las personas que trajo una automatización. |
| `triage` | Cuando el agente responde a todos los mensajes privados, los que deja de lado: una marca (`answer_collab: false`), un cliente con un problema (`answer_support: false`), los agradecimientos y la charla (`answer_personal: false`). |
| `human_pause_hours` | Cuánto tiempo la respuesta de una persona pone al agente en pausa en un lead. `0` = nunca. |

## 2. Leer los mensajes privados

La bandeja de entrada cubre WhatsApp, Instagram y Messenger. Pide las conversaciones de Instagram que te esperan:

```bash
curl "https://app.whatsetter.com/api/v1/conversations?channel=instagram&needs_reply=true" \
  -H "Authorization: Bearer ws_live_…"
```

MCP: `list_conversations`, luego `get_conversation_messages` para un hilo.

Cada conversación dice su `channel`, el usuario de la persona (`ig_username`), el `account_id`, si el agente la responde ahora (`agent_active`, y `agent_paused_until` tras la respuesta de una persona), si espera una respuesta (`needs_reply`: la vista **Pendientes** del dashboard) y, cuando el agente responde a todos los mensajes privados, lo que leyó la clasificación en el último mensaje (`triage_verdict`). `triage=collab` o `triage=support` lista los mensajes que el agente te dejó. El detalle en [Conversaciones](/es/developers/guides/conversations/).

## 3. Responder

La misma llamada que en WhatsApp, con el `lead_id` del lead:

```bash
curl -X POST "https://app.whatsetter.com/api/v1/messages" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5b7e1c2a-9d3f-4a8b-b6c1-0e2f3a4b5c6d" \
  -d '{"lead_id":"66f1a2b3c4d5e6f7a8b9c0d1","text":"¡Gracias por tu mensaje! Aquí tienes los precios."}'
```

MCP: `send_message`.

- Solo en las **24 horas** que siguen al último mensaje de la persona (la regla de Meta). Después: `409 messaging_window_closed` con `window_closes_at`, no se envía nada.
- 1000 caracteres en Instagram, 2000 en Messenger.
- Como una respuesta escrita en la bandeja de entrada, pone al agente en pausa en este lead durante `human_pause_hours`. Para quedarte el hilo del todo, [`POST /leads/{id}/handoff`](/es/developers/guides/leads/); para devolverlo, `POST /leads/{id}/resume`.

Más detalles en [Mensajes](/es/developers/guides/messages/#instagram-y-messenger).

## 4. Gestionar las automatizaciones

Una automatización responde a un comentario (en todas las publicaciones, en las que publiques a partir de ahora, o en algunas), a una respuesta a una historia, a una mención en historia o a un mensaje privado con una de sus palabras: una respuesta pública bajo el comentario, un mensaje privado (con una tarjeta de enlace, tras un «sígueme primero» opcional), y luego el agente sigue la conversación.

```bash
curl -X POST "https://app.whatsetter.com/api/v1/instagram/automations" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "68f1c2d3e4f5a6b7c8d9e0f1",
    "name": "Guía del comprador",
    "trigger": { "on": "comment", "posts": "next", "keywords": ["GUIA"] },
    "public_replies": ["Te lo mando por privado 👀"],
    "dm_message": "Aquí tienes la guía 👇",
    "link": { "url": "https://example.com/guia", "label": "La guía" }
  }'
```

MCP: `create_instagram_automation`, `list_instagram_automations`, `update_instagram_automation`, `delete_instagram_automation`.

- Se crea **apagada**. Revísala y luego enciéndela con `PATCH /instagram/automations/{id}` y `{"active": true}`. Una automatización encendida escribe a personas reales.
- `trigger.posts`: `"all"`, `"next"` (cada publicación publicada después de crear la automatización) o una lista de ids de medios de Instagram. `trigger.any_word: true` salta con cada comentario.
- Encenderla junto a una automatización activa que vigila las mismas publicaciones con las mismas palabras responde `409 automation_conflict`, con la que estorba en `conflict`: un comentario solo dispara una automatización.
- Cada automatización se lee con sus cifras: `stats.fired`, `stats.dms_sent`, `stats.link_clicks`, `stats.last_fired_at`.
- Lo que el editor del dashboard ajusta además de estos campos (textos en rotación, petición de e-mail, pasos escritos, seguimiento) se conserva cuando cambias una automatización aquí.

## 5. Programar una publicación

```bash
curl -X POST "https://app.whatsetter.com/api/v1/instagram/posts" \
  -H "Authorization: Bearer ws_live_…" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "image",
    "caption": "Nuevo piso en Madrid. Comenta GUIA para la guía del comprador.",
    "media": [{ "type": "image", "url": "https://cdn.example.com/listing.jpg" }],
    "publish_at": "2027-01-12T17:00:00Z",
    "automation": { "keyword": "GUIA", "message": "Aquí tienes la guía 👇" }
  }'
```

MCP: `schedule_instagram_post`, luego `get_scheduled_instagram_post` para seguirla. `get_instagram_best_times` da los próximos buenos momentos.

- Publica **públicamente**. Sin `publish_at`, sale en un minuto. Los medios son URL https públicas que Instagram descarga al publicar.
- Síguela con `GET /instagram/posts/{id}`: `status`, `permalink` una vez publicada, y su copia en la página de Facebook con `facebook: true`.
- `mode: "remind"` no publica nada: un miembro de tu equipo recibe un recordatorio para publicarla desde la app de Instagram (`remind_member_id`, si no el miembro que creó la clave), y luego la publicación se encuentra y se vincula.
- 50 publicaciones en espera por cuenta como máximo por la API: después, `409 too_many_planned`.
- `GET /instagram/posts` se recorre con `cursor`, como las demás listas.

## 6. Leer las cifras

```bash
curl "https://app.whatsetter.com/api/v1/instagram/stats?days=30&tz=Europe/Madrid" \
  -H "Authorization: Bearer ws_live_…"
```

MCP: `get_instagram_stats`, y `list_instagram_posts` para las vistas y el embudo de cada publicación.

`/instagram/stats` dice lo que hicieron las automatizaciones en 7, 30 o 90 días, frente al periodo anterior: comentarios, mensajes privados enviados, personas que respondieron, enlaces enviados y abiertos, e-mails captados, leads calificados. En `totals`, `by_day`, `by_automation` y `by_post`, cada vez separados entre `instagram` y `facebook` (la copia de las automatizaciones en la página). `/instagram/insights/posts` da las vistas de cada publicación frente a la media de la cuenta, hasta las citas que trajo.

## Errores que encontrarás

| HTTP | `code` | Cuándo |
|---|---|---|
| 403 | `insufficient_scope` | La clave no tiene `instagram:read` o `instagram:write`. Una clave antigua de **Acceso completo**: crea una nueva. |
| 403 | `instagram_not_enabled` | Instagram no está activado en el espacio. |
| 404 | `not_found` | Cuenta, publicación o automatización desconocida, o de otro espacio. |
| 409 | `messaging_window_closed` | Más de 24 horas desde el último mensaje de la persona. Mira `window_closes_at`. |
| 409 | `recipient_unreachable` | La persona no recibe mensajes de la cuenta ahora mismo (la bloqueó, o desactivó sus mensajes). |
| 409 | `automation_conflict` | Una automatización activa ya vigila las mismas publicaciones con las mismas palabras. Mira `conflict`. |
| 409 | `instagram_reconnect_required` | La cuenta debe volver a conectarse desde el dashboard. |
| 409 | `too_many_planned` | Ya hay 50 publicaciones esperando en la cuenta. |
| 409 | `post_already_started`, `post_already_published` | La publicación ya salió o está en camino: ya no puede cambiar. |
| 422 | `validation_error` | Un campo que falta o es incorrecto; el mensaje dice cuál. `account_id` es obligatorio con varias cuentas. |
| 422 | `no_reminder_recipient` | `mode: "remind"` y nadie del espacio a quien avisar: pasa `remind_member_id`. |

## Relacionado

- [Conversaciones](/es/developers/guides/conversations/)
- [Mensajes](/es/developers/guides/messages/)
- [Leads: pasar una conversación a una persona](/es/developers/guides/leads/)
- [Servidor MCP](/es/developers/mcp/)
- [Autenticación y permisos](/es/developers/authentication/)
