Integración de Instagram para VoiceOS

Gestiona tu cuenta de Instagram por voz desde el notch del Mac. Pregunta cómo va la cuenta, lee comentarios y mensajes directos, y publica una foto o un carrusel arrastrándola al notch y diciendo qué pie de foto ponerle.

Se requiere una cuenta de empresa o de creador. La API de Instagram no expone estadísticas, comentarios, mensajes directos ni publicación en una cuenta personal; esto es una regla de Meta, no nuestra, y no hay forma de evitarla.

Para convertirla: app de Instagram → tu perfil → menú ☰ → Configuración y privacidad → Tipo de cuenta y herramientas → Cambiar a cuenta profesional. Elige Creador o Empresa y sigue las indicaciones. Es gratuito, reversible y no hace pública tu cuenta si era privada. Vuelve a conectar esta integración después.

Configuración

Seis pasos. Los pasos 3 y 4 solo son necesarios si quieres publicar; la lectura funciona sin ellos.

1. Instalar dependencias

cd instagram
bun install

2. Conectar Instagram a través de Composio

Composio es el transporte de autenticación y API sobre el que se ejecuta esta integración.

1. Obtén una clave de API desde el panel de Composio.

2. Añade Instagram como aplicación en tu proyecto de Composio. Eso crea la configuración de autenticación que necesita el flujo de conexión.

Apruebas el OAuth real de Instagram en el paso 6; aquí no hay nada que hacer todavía.

3. Crear el bucket de retransmisión de fotos (Cloudflare R2)

Instagram nunca acepta bytes de imagen. Meta obtiene una URL pública en su lugar, con su propio rastreador. Así que una foto que sueltas en el notch se sube a tu propio bucket de R2, se entrega a Instagram como enlace y se elimina segundos después.

En el panel de Cloudflare → R2:

1. Crea un bucket.

2. Ábrelo → Configuración → URL de desarrollo público → Habilitar. Copia esa URL. El bucket debe ser público o Meta no podrá obtener la foto.

3. Gestionar tokens de API → Crear token de API, con ámbito limitado a ese único bucket, con lectura y escritura de objetos. El secreto se muestra una sola vez; cópialo ahora.

4. Opcional pero recomendado: añade una regla de ciclo de vida para eliminar objetos después de 1 día. La integración elimina cada foto por sí misma; esto es el respaldo para el raro fallo.

Omita todo este paso si solo quieres leer. account_pulse, post_insights, activity y dm_thread funcionan sin bucket. Solo create_post y schedule_post lo necesitan.

4. Dar las claves al servidor

Crea un archivo .env en esta carpeta:

COMPOSIO_API_KEY=

# Cloudflare R2 — publishing only, leave blank if you are read-only
R2_ACCOUNT_ID=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_PUBLIC_URL=

R2_ACCOUNT_ID está en la página R2 → Información general de Cloudflare, arriba a la derecha. R2_PUBLIC_URL es la URL de desarrollo público del paso 3.

Si VoiceOS te pide estos valores como campos de configuración, esa inyección tiene prioridad y el archivo es solo un respaldo para ejecutar el servidor de forma independiente.

5. Instalar en VoiceOS

Sal de VoiceOS primero. Mantiene config.json en memoria y lo reescribe al salir, así que cualquier cosa escrita mientras está en ejecución se descarta silenciosamente, sin ningún error. El instalador se niega a ejecutarse si ve que VoiceOS está activo.

osascript -e 'quit app "VoiceOS"'
python3 install-into-voiceos.py
open -a VoiceOS

Eso copia esta carpeta en ~/Library/Application Support/VoiceOS/custom-mcps/, transfiere las claves del paso 4 y lo registra. Un simple cp no es suficiente: VoiceOS también necesita dos entradas en config.json (una que indique cómo iniciar el servidor y otra que contenga el manifiesto), y escribir esas es la mayor parte de lo que hace el script. Primero hace una copia de seguridad de config.json.

--update vuelve a derivar confirmTools del manifiesto cada vez. Eso importa más de lo que parece: es la lista que VoiceOS usa para decidir qué herramientas necesitan una tarjeta de confirmación, y una entrada obsoleta que quede de un cambio de nombre permitiría que una publicación saliera sin tarjeta alguna.

6. Conecta tu cuenta

Di "¿Cómo va mi Instagram?". Si Instagram aún no está vinculado, verás una tarjeta Conectar Instagram con un enlace OAuth. Aprueba una vez y listo.

Si dice que la cuenta es personal, vuelve al recuadro de la parte superior de esta página.

Herramientas

Suelta las fotos en el notch y habla al mismo tiempo: "publica estas dos con un pie de foto sobre el hackathon". Ambas herramientas de escritura te muestran las fotos, el pie de foto y (en el caso de una programación) la hora exacta en una tarjeta antes de que se publique nada.

Cómo se gestionan tus fotos

Vale la pena leerlo una vez, porque un paso sorprende a la gente.

1. La foto se convierte a JPEG en tu Mac con sips (integrado en macOS). Instagram no acepta nada más.

2. Se sube a tu bucket de R2 con un nombre aleatorio imposible de adivinar y es legible públicamente durante unos segundos. Esto es inevitable: el rastreador de Meta es anónimo y no puede iniciar sesión, así que una URL pública es la única forma de que Instagram acepte una foto.

3. Instagram la obtiene y publica la publicación.

4. El archivo se elimina del bucket, tanto en caso de éxito como de error, en un bloque finally. La regla de ciclo de vida del paso 3 es el respaldo.

El bucket es tuyo. No se almacena nada en el servidor de nadie más, y esta integración no guarda ninguna copia de tus fotos.

Las publicaciones programadas se ejecutan en tu Mac, no en los servidores de Instagram; Instagram no tiene API de programación. Un temporizador de launchd de macOS se activa en el minuto que indicaste y publica entonces. Así que el Mac tiene que estar encendido y despierto. Si estaba apagado cuando tocaba la publicación, esta se registra como perdida en lugar de publicarse con horas de retraso, y instagram_activity te lo dice la próxima vez que preguntes.

No incluido en v1

Recortado deliberadamente, para que lo sepas antes de intentarlo:

• Enviar mensajes directos. Meta bloquea el envío de mensajes directos por API a través de la aplicación compartida de Instagram de Composio; devuelve errores de "fuera de la ventana permitida" incluso con la ventana de 24 horas claramente abierta. La integración lee los mensajes directos pero no puede enviarlos. Responde en la aplicación de Instagram.

• Responder a comentarios. La misma limitación de transporte.

• Vídeo y Reels. Solo fotos y carruseles de fotos. La publicación de vídeo necesita una ruta de subida reanudable que esta versión no tiene.

• Historias. No expuestas por el kit de herramientas.

• Programar más de 24 horas. El límite es deliberado: cada hora extra es otra forma de que un trabajo diferido se pudra donde nadie pueda verlo: la foto se elimina, se rota una clave, se revoca la conexión.

• Leer otras cuentas. Solo tu cuenta conectada.

Solución de problemas

Desarrollo

bun install
bun test          # 224 unit and failure-injection tests
bunx tsc --noEmit -p tsconfig.json

Tres reglas que los tests existen para proteger, que vale la pena conocer antes de editar:

• stdout es el cable MCP. Un solo console.log en el código enviado y VoiceOS no puede analizar el flujo JSON-RPC, así que la integración desaparece silenciosamente del enrutamiento hasta que la aplicación se reinicia. Todo se registra a través de console.error; stdoutGuard.ts es la primera importación en server.ts y reasigna la consola para las dependencias que no lo hacen.

• Nunca construyas una cadena de shell a partir de una ruta de archivo. Las fotos vienen de que el usuario arrastra un archivo al notch. Solo execFile(cmd, [args]): un archivo llamado holiday.png; rm -rf ~ es un argumento opaco para sips, y test/media-paths.test.ts lo verifica.

• Los nombres y descripciones de las herramientas deben coincidir exactamente con el manifiesto, en ambas direcciones. server.ts y voiceos.integration.json son dos copias de un mismo contrato.

confirmations/post_composer.html es la fuente de verdad para la tarjeta previa a la publicación; el manifiesto lleva una copia de ella como cadena. Edita el HTML y la copia debe regenerarse, o la tarjeta que se muestra antes de una publicación irreversible será la obsoleta.