Guías por recurso
Maneja tus cuentas de Instagram por la API: leer y responder mensajes privados, gestionar automatizaciones, programar publicaciones y leer sus cifras.
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 que hace lo mismo desde un asistente IA.
Endpoints
Sección titulada «Endpoints»| Método | Ruta | Scope |
|---|---|---|
| GET | /instagram/accounts |
instagram:read |
| GET | /conversations |
conversations:read |
| POST | /messages |
messages:send |
| GET | /instagram/automations |
instagram:read |
| POST | /instagram/automations |
instagram:write |
| PATCH | /instagram/automations/{id} |
instagram:write |
| DELETE | /instagram/automations/{id} |
instagram:write |
| POST | /instagram/posts |
instagram:write |
| GET | /instagram/posts |
instagram:read |
| GET | /instagram/posts/{id} |
instagram:read |
| GET | /instagram/stats |
instagram:read |
| GET | /instagram/insights/posts |
instagram:read |
Antes de empezar
Sección titulada «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(einstagram:writepara cambiar algo). Una clave de Acceso completo creada antes de estos endpoints no los lleva: crea una nueva (Autenticación). - Los mensajes privados no necesitan ningún scope de Instagram:
conversations:readpara leerlos,messages:sendpara responder.
1. Encontrar tus cuentas
Sección titulada «1. Encontrar tus cuentas»Cada ruta de Instagram recibe un account_id. Con una sola cuenta puedes omitirlo; con varias, es obligatorio.
curl "https://app.whatsetter.com/api/v1/instagram/accounts" \ -H "Authorization: Bearer ws_live_…"MCP: list_instagram_accounts.
{ "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
Sección titulada «2. Leer los mensajes privados»La bandeja de entrada cubre WhatsApp, Instagram y Messenger. Pide las conversaciones de Instagram que te esperan:
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.
3. Responder
Sección titulada «3. Responder»La misma llamada que en WhatsApp, con el lead_id del lead:
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_closedconwindow_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; para devolverlo,POST /leads/{id}/resume.
Más detalles en Mensajes.
4. Gestionar las automatizaciones
Sección titulada «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.
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: truesalta 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 enconflict: 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
Sección titulada «5. Programar una publicación»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,permalinkuna vez publicada, y su copia en la página de Facebook confacebook: 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/postsse recorre concursor, como las demás listas.
6. Leer las cifras
Sección titulada «6. Leer las cifras»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
Sección titulada «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. |