Ir al contenido

Conectar canales

Conectar Instagram

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

  • 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.
  • 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).

Messajo solo pide los permisos de la API de Instagram con Inicio de sesión con Facebook para Empresas:

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 fotos, videos, carruseles, Reels e historias no
instagram_manage_insights Leer las 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). 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, con el permiso en details[0].message, hasta que reconectes.

  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.

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 con el canal Instagram: la persona autoriza desde la página pública de la invitación, sin cuenta en Messajo.

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.

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.

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.

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. 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).

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.

Fuera de la ventana, Messajo rechaza antes de llamar a Meta: 422 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. Reacción, me gusta y share no abren ni extienden la ventana.

Con instagram_manage_comments, Messajo suscribe los campos comments, live_comments y mentions y entrega los eventos comment.* y mention.received (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); hasta 7 días después del comentario, y en un comentario de un directo solo durante el directo (422 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). Tu respuesta vuelve de Meta como webhook, pero no genera otro evento.

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).

Pantalla del perfil de mensajes de una cuenta de Instagram, con una pregunta frecuente y un flujo de bienvenida

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

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).
  • media_publish por el espejo no pasa por la programación de Messajo: para programar, usa /v1/publications.
  • envíos masivos (no hay campañas en Instagram);
  • mensajes fuera de la ventana;
  • grupos;
  • cuentas personales: solo funciona con cuenta profesional.