instagram

## Overview

Complete integration with Instagram via the Graph API. Publishing, analytics, comments, DMs, hashtags, scheduling, templates, and management of Business/Creator accounts.

## When to Use This Skill

- When the user mentions "instagram" or related topics
- When the user mentions "ig" or related topics
- When the user mentions "post instagram" or related topics
- When the user mentions "publicar instagram" or related topics
- When the user mentions "reels instagram" or related topics
- When the user mentions "stories instagram" or related topics

## Do Not Use This Skill When

- The task is unrelated to instagram
- A simpler, more specific tool can handle the request
- The user needs general-purpose assistance without domain expertise

## How It Works

Full control of the Instagram account via the Graph API. Publishing, community, analytics,
DMs, hashtags, templates, and dashboard — all managed with governance (rate limits, audit log,
confirmations before public actions).

## Quick Summary

| Area | Scripts | What it does |
|------|---------|-----------|
| **Setup** | `account_setup.py`, `auth.py` | Configure account, OAuth, token |
| **Publishing** | `publish.py`, `schedule.py` | Publish photo/video/reel/story/carousel, schedule |
| **Community** | `comments.py`, `messages.py` | Comments, DMs, mentions |
| **Analytics** | `insights.py`, `analyze.py` | Metrics, best times, top posts |
| **Hashtags** | `hashtags.py` | Search and tracking |
| **Intelligence** | `templates.py`, `analyze.py` | Content templates, trends |
| **Infra** | `export.py`, `serve_api.py`, `run_all.py` | Export, dashboard, sync |
| **Reading** | `profile.py`, `media.py` | Profile, list media |

## Location

```
C:\Users\renat\skills\instagram\
├── SKILL.md
├── scripts/
│   ├── requirements.txt
│   │  # ── CORE ──
│   ├── config.py                     # Paths, constantes, specs de mídia
│   ├── db.py                         # SQLite: accounts, posts, comments, insights
│   ├── auth.py                       # OAuth 2.0, token storage/refresh
│   ├── api_client.py                 # Instagram Graph API wrapper + retry
│   ├── governance.py                 # Rate limits, audit log, confirmações
│   │  # ── FEATURES ──
│   ├── account_setup.py              # Detecção conta, migração, verificação
│   ├── publish.py                    # Publicar + upload local via Imgur
│   ├── schedule.py                   # Orquestrador: approved → published
│   ├── comments.py                   # Ler/responder/deletar comentários
│   ├── messages.py                   # DMs (enviar/receber/listar)
│   ├── insights.py                   # Fetch + store métricas
│   ├── hashtags.py                   # Pesquisa + tracking
│   ├── profile.py                    # Ver/atualizar perfil
│   ├── media.py                      # Listar mídia, detalhes
│   │  # ── INTELIGÊNCIA ──
│   ├── templates.py                  # Templates de caption/hashtags
│   ├── analyze.py                    # Melhores horários, top posts
│   │  # ── INFRA ──
│   ├── export.py                     # Exportar JSON/CSV/JSONL
│   ├── serve_api.py                  # FastAPI + dashboard
│   └── run_all.py                    # Sync completo
├── references/
│   ├── graph_api.md                  # Endpoints e parâmetros
│   ├── permissions.md                # Scopes OAuth por feature
│   ├── rate_limits.md                # Limites 2025
│   ├── account_types.md              # Business vs Creator
│   ├── publishing_guide.md           # Specs de mídia
│   ├── setup_walkthrough.md          # Guia Meta App
│   └── schema.md                     # ER diagram
├── static/
│   └── dashboard.html                # Dashboard Chart.js
└── data/
    

## Installation (One Time)

```bash
pip install -r C:\Users\renat\skills\instagram\scripts\requirements.txt
```

## Initial Configuration

```bash

## 1. Check The Instagram Account Type

python C:\Users\renat\skills\instagram\scripts\account_setup.py --check

## 2. Configure Oauth (Opens Browser For Authorization)

python C:\Users\renat\skills\instagram\scripts\auth.py --setup

## 3. Verify That Everything Is Working

python C:\Users\renat\skills\instagram\scripts\profile.py --view
```

If the account is personal, the `account_setup.py --guide` script gives migration
instructions for Business or Creator.

## Photo (Accepts A Local File — Uploads Automatically Via Imgur)

python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image caminho/foto.jpg --caption "Texto do post"

## Video

python C:\Users\renat\skills\instagram\scripts\publish.py --type video --video caminho/video.mp4 --caption "Meu vídeo"

## Reel

python C:\Users\renat\skills\instagram\scripts\publish.py --type reel --video caminho/reel.mp4 --caption "Novo reel!"

## Story

python C:\Users\renat\skills\instagram\scripts\publish.py --type story --image caminho/story.jpg

## Carousel (2-10 Images)

python C:\Users\renat\skills\instagram\scripts\publish.py --type carousel --images img1.jpg img2.jpg img3.jpg --caption "Carrossel"

## Create As A Draft (Does Not Publish Immediately)

python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image foto.jpg --caption "Texto" --draft

## Approve A Draft For Publishing

python C:\Users\renat\skills\instagram\scripts\publish.py --approve --id 5
```

## Schedule A Future Post

python C:\Users\renat\skills\instagram\scripts\schedule.py --type photo --image foto.jpg --caption "Post agendado" --at "2026-03-01T10:00"

## List Scheduled Posts

python C:\Users\renat\skills\instagram\scripts\schedule.py --list

## Process Posts Ready To Publish

python C:\Users\renat\skills\instagram\scripts\schedule.py --process

## Cancel A Schedule

python C:\Users\renat\skills\instagram\scripts\schedule.py --cancel --id 5
```

## List Comments On A Post

python C:\Users\renat\skills\instagram\scripts\comments.py --list --media-id 12345

## Reply To A Comment

python C:\Users\renat\skills\instagram\scripts\comments.py --reply --comment-id 67890 --text "Obrigado!"

## Delete A Comment

python C:\Users\renat\skills\instagram\scripts\comments.py --delete --comment-id 67890

## View Mentions

python C:\Users\renat\skills\instagram\scripts\comments.py --mentions

## Unreplied Comments

python C:\Users\renat\skills\instagram\scripts\comments.py --unreplied
```

## Send A Dm

python C:\Users\renat\skills\instagram\scripts\messages.py --send --user-id 12345 --text "Olá!"

## List Conversations

python C:\Users\renat\skills\instagram\scripts\messages.py --conversations

## View Messages In A Conversation

python C:\Users\renat\skills\instagram\scripts\messages.py --thread --conversation-id 12345
```

## Metrics For A Specific Post

python C:\Users\renat\skills\instagram\scripts\insights.py --media --media-id 12345

## Account Metrics (Last 7 Days)

python C:\Users\renat\skills\instagram\scripts\insights.py --user --period day --since 7

## Fetch And Save Insights For All Recent Posts

python C:\Users\renat\skills\instagram\scripts\insights.py --fetch-all --limit 20
```

## Best Times To Post (Based On Your Data)

python C:\Users\renat\skills\instagram\scripts\analyze.py --best-times

## Top Posts By Engagement

python C:\Users\renat\skills\instagram\scripts\analyze.py --top-posts --limit 10

## Growth Trends

python C:\Users\renat\skills\instagram\scripts\analyze.py --growth --period 30
```

## Find Recent Posts With A Hashtag

python C:\Users\renat\skills\instagram\scripts\hashtags.py --search "artificialintelligence" --limit 25

## Top Posts For A Hashtag

python C:\Users\renat\skills\instagram\scripts\hashtags.py --top "tecnologia"

## Hashtag Info (Post Count)

python C:\Users\renat\skills\instagram\scripts\hashtags.py --info "marketing"
```

## Create A Template

python C:\Users\renat\skills\instagram\scripts\templates.py --create --name "promo" --caption "Nova promoção: {produto}! {desconto}% OFF" --hashtags "#oferta,#desconto,#promoção"

## List Templates

python C:\Users\renat\skills\instagram\scripts\templates.py --list

## Use A Template In A Post

python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image foto.jpg --template promo --vars produto="Tênis" desconto=30
```

## View Profile

python C:\Users\renat\skills\instagram\scripts\profile.py --view

## List Recent Posts

python C:\Users\renat\skills\instagram\scripts\media.py --list --limit 10

## Details Of A Post

python C:\Users\renat\skills\instagram\scripts\media.py --details --media-id 12345
```

## Export Analytics To Csv

python C:\Users\renat\skills\instagram\scripts\export.py --type insights --format csv

## Export Comments

python C:\Users\renat\skills\instagram\scripts\export.py --type comments --format json

## Export Everything

python C:\Users\renat\skills\instagram\scripts\export.py --type all --format csv

## Start The Web Dashboard

python C:\Users\renat\skills\instagram\scripts\serve_api.py

## Open: Http://Localhost:8000/Dashboard

```

## Authentication Status

python C:\Users\renat\skills\instagram\scripts\auth.py --status

## Full Sync (Fetches Profile + Media + Insights + Comments)

python C:\Users\renat\skills\instagram\scripts\run_all.py

## Partial Sync

python C:\Users\renat\skills\instagram\scripts\run_all.py --only media insights
```

## Rate Limits

The skill automatically tracks the API rate limits:
- **200 requests/hour** per account
- **25 posts/day** per account
- **30 unique hashtags/week** per account
- **200 DMs/hour** per account

At 90% of the limit, the skill emits warnings. If exceeded, it blocks the action and reports
how long to wait.

## Confirmations

Actions that affect public content require confirmation:
- **PUBLISH**: Publish photo/video/reel/story/carousel
- **DELETE**: Delete a comment
- **MESSAGE**: Send a DM
- **ENGAGE**: Reply to a comment, hide a comment

The script returns the action details and asks for confirmation before executing.

## Audit Log

All actions that modify data are logged in the SQLite database (`action_log` table):
- Timestamp, action, parameters, result, confirmation status
- Query via: `python C:\Users\renat\skills\instagram\scripts\db.py`

## Token Auto-Refresh

The OAuth token (60 days) is renewed automatically when it is within 7 days of expiring.
No manual intervention needed.

## Api Limitations

Things the Instagram Graph API **does not allow**:
- Deleting posts that are already published
- Editing captions after publishing
- Applying filters via the API
- Posting from personal accounts (Business/Creator only)
- DMs outside the 24-hour window (the user must have interacted first)
- Photos in a format other than JPEG (auto-converted by the scripts)

## "I Want To Publish A Photo"

```bash
python C:\Users\renat\skills\instagram\scripts\publish.py --type photo --image foto.jpg --caption "Texto"
```

## "Show Me My Analytics"

```bash
python C:\Users\renat\skills\instagram\scripts\run_all.py --only insights
python C:\Users\renat\skills\instagram\scripts\analyze.py --summary
```

## "What's The Best Time To Post?"

```bash
python C:\Users\renat\skills\instagram\scripts\analyze.py --best-times
```

## "Reply To This Comment"

```bash
python C:\Users\renat\skills\instagram\scripts\comments.py --reply --comment-id ID --text "Resposta"
```

## "Sync Everything"

```bash
python C:\Users\renat\skills\instagram\scripts\run_all.py
```

## "Open The Dashboard"

```bash
python C:\Users\renat\skills\instagram\scripts\serve_api.py
```

## References

Consult these when you need details:
- `references/graph_api.md` — API endpoints, parameters, and responses
- `references/publishing_guide.md` — Media specs (dimensions, formats, sizes)
- `references/rate_limits.md` — Detailed rate limits and strategies
- `references/account_types.md` — Business vs Creator differences, migration
- `references/permissions.md` — OAuth scopes required per feature
- `references/setup_walkthrough.md` — Step-by-step Meta App setup guide
- `references/schema.md` — SQLite database schema (ER diagram, fields, indexes, queries)

## Best Practices

- Provide clear, specific context about your project and requirements
- Review all suggestions before applying them to production code
- Combine with other complementary skills for comprehensive analysis

## Common Pitfalls

- Using this skill for tasks outside its domain expertise
- Applying recommendations without understanding your specific context
- Not providing enough project context for accurate analysis

## Related Skills

- `social-orchestrator` - Complementary skill for enhanced analysis
- `telegram` - Complementary skill for enhanced analysis
- `whatsapp-cloud-api` - Complementary skill for enhanced analysis