Ir al contenido
Dashboard

Guías por recurso

Instagram

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.

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
  • 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).
  • Los mensajes privados no necesitan ningún scope de Instagram: conversations:read para leerlos, messages:send para responder.

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

Terminal window
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.

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

Terminal window
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.

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

Terminal window
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; para devolverlo, POST /leads/{id}/resume.

Más detalles en Mensajes.

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.

Terminal window
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í.
Terminal window
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.
Terminal window
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.

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.