# Conectar Instagram

> Cómo vincular una cuenta profesional de Instagram para Direct, comentarios y menciones.

## Requisitos

- Una cuenta **profesional** de Instagram (empresa o creador). Si no se libera ninguna cuenta en el inicio de sesión, la conexión se rechaza con [`instagram_account_not_professional`](/es/errors#instagram_account_not_professional).
- No hace falta una Página de Facebook.
- Quien inicia sesión debe administrar la cuenta en Instagram.
- En la cuenta, activa **Configuración → Mensajes y respuestas a historias → Controles de mensajes → Herramientas conectadas → Permitir acceso a los mensajes**. Sin eso Direct no funciona (consulta [Acceso a Direct desactivado](#acceso-a-direct-desactivado)).

## Permisos

Messajo solo pide los permisos de la [API de Instagram con Inicio de sesión con Facebook para Empresas](https://developers.facebook.com/documentation/instagram-platform/overview):

| Permiso | Para qué | Obligatorio |
|---|---|---|
| `instagram_basic` | Leer el perfil y el contenido de la cuenta | sí |
| `instagram_manage_messages` | Recibir y enviar mensajes por Direct | sí |
| `instagram_manage_comments` | Listar, responder, ocultar y borrar comentarios; respuesta privada; menciones | no |
| `instagram_content_publish` | [Publicar](/es/connect/instagram-content/#publicar) fotos, videos, carruseles, Reels e historias | no |
| `instagram_manage_insights` | Leer las [estadísticas](/es/connect/instagram-content/#estadísticas) de la cuenta y de cada publicación | no |

Sin uno de los dos obligatorios la conexión no se crea ([`signup_scope_mismatch`](/es/errors#signup_scope_mismatch)). Los demás se pueden desmarcar en la pantalla de Instagram: la cuenta se conecta, la página de la conexión muestra **Permisos que faltan** y la función responde `403` [`instagram_scope_missing`](/es/errors#instagram_scope_missing), con el permiso en `details[0].message`, hasta que reconectes.

## Paso a paso

1. Abre **Conexiones → Conectar Instagram**. El panel navega a la página de Meta (Inicio de sesión con Facebook para Empresas), sin ventana emergente y funcionando en el celular.
2. Entra, elige la(s) cuenta(s) de Instagram a las que Messajo puede acceder y confirma.
3. Meta vuelve a Messajo, que cambia el código por un token de acceso, lee la cuenta, suscribe la app a los webhooks y lee el perfil de mensajes.
4. Listo: la cuenta aparece como **Activa**, con los campos de webhook suscritos.

- Una cuenta liberada: se conecta directamente.
- Más de una: Messajo muestra un selector y conecta **una por inicio de sesión**. Repite el inicio de sesión para conectar las demás.
- Ninguna: error [`instagram_account_not_professional`](/es/errors#instagram_account_not_professional).

Si cancelas en la pantalla de Meta, el intento queda en el **Historial** de la conexión con el evento `CANCEL`. Si un paso falla después de crear la conexión, queda **Pendiente** con el paso que faltó, y **Completar conexión** rehace solo lo que falta.

Una organización puede conectar varias cuentas. Para conectar la cuenta de un cliente, envía una [invitación por enlace](/es/connect/whatsapp/#invitar-al-cliente-por-enlace) con el canal Instagram: la persona autoriza desde la página pública de la invitación, sin cuenta en Messajo.

## Acceso sin vencimiento

El acceso no vence, así que no hay renovación. Si Meta lo revoca (contraseña cambiada, app retirada de la cuenta, error `190`), la conexión pasa a `needs_reconnect` con `token_invalid` y el dueño recibe el aviso con el enlace de reconexión. Reconectar mantiene la misma conexión.

### Acceso a Direct desactivado

Si **Permitir acceso a los mensajes** está desactivado en la cuenta, la verificación de salud de la conexión registra `reason: "dm_access_disabled"`: sale un evento `connection.updated` y el panel muestra una advertencia. La conexión sigue activa y los comentarios, la publicación y las estadísticas siguen funcionando; solo Direct no. Para resolverlo, en Instagram abre **Configuración → Mensajes y respuestas a historias → Controles de mensajes → Herramientas conectadas** y activa **Permitir acceso a los mensajes**. La advertencia desaparece en la siguiente verificación.

### Cuentas conectadas antes de esta versión

Las cuentas conectadas con el Inicio de sesión con Instagram deben reconectarse una vez. Los ids de mensaje de Meta son distintos entre los dos inicios de sesión.

## Tipos de mensaje

Instagram y Messenger usan el mismo motor y el mismo `POST /v1/messages`. El `to` es el IGSID del contacto (o el `ctc_…` de Messajo).

| `type` | WhatsApp | Instagram | Messenger |
|---|---|---|---|
| `text` (con `quick_replies` en IG/Messenger) | sí | sí | sí |
| `image` · `video` · `audio` · `document` | sí | sí | sí |
| `images` (2 a 10 imágenes en un mensaje) | no | sí | no |
| `reaction` | sí | sí | sí |
| `like` (me gusta) | no | sí | no |
| `share` (compartir una publicación de la cuenta) | no | sí | no |
| `buttons` · `cards` | no | sí | sí |
| `template` · `interactive` · `location` · `contacts` · `sticker` | sí | no | no |

Un tipo fuera de la matriz devuelve `422` [`type_not_supported_by_channel`](/es/errors#type_not_supported_by_channel). En Instagram el texto admite hasta 1.000 bytes; imagen hasta 8 MB (JPEG, PNG o GIF); audio, video y PDF hasta 25 MB. `typing: true` muestra "escribiendo" antes del envío y `POST /v1/messages/{id}/read` marca la conversación como vista. El contacto llega con nombre, nombre de usuario y foto (leídos en el primer mensaje y cada 7 días).

## Ventanas y HUMAN_AGENT

Meta solo deja responder dentro de una ventana abierta por el último mensaje del contacto:

| Ventana | Cuándo vale |
|---|---|
| 24 horas | Cualquier respuesta, contada desde el último mensaje del contacto |
| 7 días | Después de que el contacto responda a un anuncio de Direct (Messajo reconoce el `referral` del anuncio) |
| 7 días | Con `tag: "human_agent"` |

`tag: "human_agent"` sirve **solo para respuestas escritas por una persona** (política de Meta): nunca la uses en automatizaciones o bots. El panel no ofrece la etiqueta en automatizaciones. Exige la función **Human Agent** aprobada en App Review; sin ella Meta rechaza y Messajo devuelve `403` [`human_agent_not_approved`](/es/errors#human_agent_not_approved).

Fuera de la ventana, Messajo rechaza antes de llamar a Meta: `422` [`outside_service_window`](/es/errors#outside_service_window), con el fin de la ventana en `details[0].message`. Con la etiqueta y más de 7 días: `422` [`human_agent_window_closed`](/es/errors#human_agent_window_closed). Reacción, me gusta y `share` no abren ni extienden la ventana.

## Comentarios, respuesta privada y menciones

Con `instagram_manage_comments`, Messajo suscribe los campos `comments`, `live_comments` y `mentions` y entrega los eventos `comment.*` y `mention.received` ([catálogo](/es/webhooks/events/#catálogo)).

| Qué | Ruta `/v1` | Evento |
|---|---|---|
| Comentarios de una publicación (en vivo desde Meta, con el estado de Messajo) | `GET /connections/{id}/posts/{post_id}/comments` | — |
| Responder en público | `POST /connections/{id}/comments/{comment_id}/replies` con `{ message }` (hasta 2.200 caracteres) | `comment.replied` |
| Ocultar o mostrar | `POST /connections/{id}/comments/{comment_id}/hide` con `{ hidden }` | `comment.hidden` · `comment.unhidden` |
| Borrar | `DELETE /connections/{id}/comments/{comment_id}` | `comment.deleted` |
| Respuesta privada | `POST /connections/{id}/comments/{comment_id}/private-reply` | `comment.private_replied` + `message.sent` |
| Menciones | `GET /connections/{id}/mentions` | `mention.received` |

La **respuesta privada** envía un mensaje por Direct a quien comentó, incluso sin una ventana de 24 h abierta. Reglas de Meta: solo `text`, `buttons` o `cards`; una por comentario (`409` [`private_reply_already_sent`](/es/errors#private_reply_already_sent)); hasta 7 días después del comentario, y en un comentario de un directo solo durante el directo (`422` [`private_reply_window_closed`](/es/errors#private_reply_window_closed)). La respuesta abre la conversación con el contacto y los siguientes mensajes siguen las ventanas normales.

Solo se pueden borrar comentarios en contenido de la propia cuenta ([`comment_not_owned`](/es/errors#comment_not_owned)). Tu respuesta vuelve de Meta como webhook, pero no genera otro evento.

## Perfil de mensajes

En **Conexiones → (cuenta) → Perfil de mensajes**, o con `GET`/`PUT /v1/connections/{id}/messaging-profile`:

- **Preguntas frecuentes** (ice breakers): hasta 4 por idioma, de hasta 80 caracteres cada una, con el `payload` que llega en el webhook cuando la persona toca.
- **Menú fijo**: hasta 20 elementos (`postback` o enlace).
- **Bienvenida de los anuncios**: en Instagram, la bienvenida son los flujos de los anuncios de Direct (`/v1/connections/{id}/welcome-flows`). Un flujo usado en un anuncio no se cambia ni se borra ([`welcome_flow_in_use`](/es/errors#welcome_flow_in_use)).

![Pantalla del perfil de mensajes de una cuenta de Instagram, con una pregunta frecuente y un flujo de bienvenida](../../../../assets/screenshots/instagram-profile-es.png)

El `PUT` es parcial: un campo ausente no cambia, `null` lo borra. Después de guardar, Messajo vuelve a leer el perfil en Meta.

## Capa espejo

Si ya hablas la Graph de Instagram, usa `/v1/instagram/{ig_user_id}/...` con el cuerpo y la respuesta de Meta intactos: Messajo pone el token de la cuenta y comprueba el permiso de la clave. Los nodos sueltos (contenido, comentario, contenedor, mensaje) están en `/v1/instagram/{ig_user_id}/nodes/{node_id}`.

- `POST …/messages` guarda el mensaje en los logs, gasta las fichas de envío y devuelve `X-Messajo-Message-Id`.
- `subscribed_apps`, `access_token` y `oauth/*` están bloqueados (`403` [`mirror_path_blocked`](/es/errors#mirror_path_blocked)).
- `media_publish` por el espejo **no** pasa por la programación de Messajo: para programar, usa [`/v1/publications`](/es/connect/instagram-content/#publicar).

## Lo que Meta no permite

- envíos masivos (no hay campañas en Instagram);
- mensajes fuera de la ventana;
- grupos;
- cuentas personales: solo funciona con cuenta profesional.
