n8n-nodes-conecta-integrations
Advanced tools
N8N nodes for Conecta API integration - Instagram messaging, webhooks, and content publishing
N8N nodes para integração completa com a API Conecta - Instagram Messaging, Webhooks e Publicação de Conteúdo.
Professional N8N community nodes for seamless Instagram Messaging API integration with OAuth2 authentication.
InstalaçãoInstallation • Features • Prerequisites • Quick Start • Documentation • Support
Quick Start---
Exemplos de Uso## 📖 Overview
LicençaThis package provides comprehensive Instagram integration for n8n workflows, enabling automated messaging, media management, and webhook-based event handling through the official Instagram Graph API.
---Perfect for:
Este pacote fornece nodes N8N para integração completa com a plataforma Conecta API, permitindo automação de:- 📊 Customer interaction tracking
🔄 Multi-platform messaging automation
✅ Mensagens do Instagram - Enviar/receber mensagens diretas
✅ Webhooks - Receber eventos em tempo real---
✅ Publicação de Conteúdo - Posts, Stories, Reels, Carrosséis
✅ Gestão de Chats - Listar conversas, marcar como lido## ✨ Features
✅ Comentários e Menções - Monitorar e responder
✅ Mídias - Enviar imagens, vídeos, áudios### 🔐 OAuth2 Authentication
✅ Templates - Quick replies e botões interativos- One-click authentication - Secure OAuth2 flow similar to Google Drive
🆕 Automatic long-lived tokens - Short-lived tokens (1 hour) automatically exchanged for long-lived tokens (60 days)
---- 🆕 Automatic token refresh - Tokens refresh automatically before expiration (zero configuration)
npm install n8n-nodes-conecta-integrations**Message Types:**
```- 💬 **Text Messages** - Send formatted text with up to 1000 characters
- 🖼️ **Image Messages** - Share images via public HTTPS URLs
### Via N8N Community Nodes- 🎵 **Audio Messages** - Send voice messages and audio files
- 🎬 **Video Messages** - Share video content
1. Abra seu N8N- 📤 **Media Upload** - Upload and publish photos, videos, reels, and stories
2. Vá para **Settings** → **Community Nodes**
3. Pesquise por `n8n-nodes-conecta-integrations`**Interactive Templates:**
4. Clique em **Install**- 🔘 **Button Templates** - Up to 3 action buttons (web links or postbacks)
5. Reinicie o N8N- 🎴 **Generic Templates** - Carousel cards with images and buttons
- ⚡ **Quick Replies** - Up to 13 quick response options
### Instalação Manual
**User Management:**
```bash
cd ~/.n8n/custom
git clone https://github.com/WilliamAlmeida/n8n-nodes-conecta-integrations.git
cd n8n-nodes-conecta-integrations
npm install
npm run build
```- 🎞️ **Carousel Posts** - Multi-media posts (2-10 images/videos)
- 🎬 **Reels** - Short-form videos up to 60 seconds
---- 📋 **Stories** - 24-hour temporary content
## 📦 Nodes Disponíveis**Advanced Features:**
- 🏷️ **User Tagging** - Tag up to 20 users with precise positioning
### 1. Conecta Node- 🛍️ **Product Tagging** - Tag products from Facebook catalog
- 🤝 **Collaborators** - Tag other accounts as collaborators
Node principal para operações ativas com a API Conecta.- 📍 **Location Tagging** - Add location stickers to posts
- 🎨 **Custom Thumbnails** - Set video thumbnail positions
**Recursos:**- 🎵 **Audio Attribution** - Name audio tracks in reels
#### 📬 **Chat****Media Management:**
- Listar conversas recentes- 📊 **List Media** - Get paginated list of your media
- Buscar mensagens de um chat- 🔍 **Get Media Details** - Retrieve specific media information
- Marcar mensagens como lidas- 👶 **Get Carousel Children** - Access individual carousel items
- Marcar chat como não lido
- Contar mensagens não lidas### Instagram Trigger Node
- Estatísticas de chats
**Webhook Events:**
#### 💬 **Message**- 💬 **New Messages** - Trigger on incoming messages
- Enviar mensagem de texto- 🔘 **Postback Events** - Handle button clicks and interactions
- Enviar mídia (imagem, áudio, vídeo)- ✅ **Opt-in Events** - Process user consent actions
- Enviar sticker- 💭 **Comments** (NEW!) - Trigger when someone comments on your media
- Enviar reação- 🏷️ **Mentions** (NEW!) - Trigger when someone mentions you in comments or stories
- Enviar post publicado
- Enviar resposta privada a comentário**Dual Output System:**
- Enviar quick replies- **Output 1** (Messages/Postbacks/Opt-ins) - Direct messaging events
- Enviar button template- **Output 2** (Comments/Mentions) - Content engagement events
#### 📸 **Publishing****Security Features:**
- Publicar post (Feed, Stories, Reels)- 🔒 Webhook signature validation (X-Hub-Signature-256)
- Publicar carrossel- ✓ Verify token authentication
- Verificar limite de publicação- 🛡️ HMAC SHA256 cryptographic verification
#### 👤 **Profile**---
- Buscar perfil do Instagram
## 📋 Prerequisites
---
### Required Accounts
### 2. Conecta Trigger1. **Facebook Page** - Active Facebook page
2. **Instagram Business Account** - Connected to your Facebook page
Node webhook para receber eventos em tempo real.3. **Meta Developer Account** - Access to Facebook Developer Console
4. **n8n Instance** - Self-hosted or cloud (version 0.196.0+)
**Eventos Suportados:**
### Required Permissions
- 🔵 **Messages** - Mensagens recebidas
- ❤️ **Reactions** - Reações a mensagens**For Messaging:**
- 🔘 **Postbacks** - Cliques em botões- `instagram_basic` - Basic profile access
- 🔗 **Referrals** - Mensagens de anúncios- `instagram_manage_messages` - Send and receive messages
- ✅ **Read Receipts** - Confirmações de leitura- `pages_manage_metadata` - Webhook subscriptions
- ✏️ **Message Edits** - Edições de mensagens- `pages_read_engagement` - Read engagement data
- ⏱️ **Disappearing Media** - Mídias temporárias
- 💭 **Comments** - Comentários em posts**For Content Publishing (NEW):**
- 📢 **Mentions** - Menções da conta- `instagram_content_publish` - Create and publish posts, reels, and stories
- `pages_show_list` - List Facebook pages
**Características:**- `catalog_management` - Product tagging (optional, for Instagram Shopping)
- ✅ 9 outputs separados (um para cada tipo de evento)
- ✅ Validação de Bearer Token (opcional)### Technical Requirements
- ✅ Filtragem de mensagens próprias- Node.js 18.15+ or 20.10+
- ✅ Formatação automática de timestamps- n8n version 0.196.0 or higher
- ✅ Suporte a eventos em lote- HTTPS webhook endpoint (for trigger node)
- ✅ Metadata de processamento
---
---
## 🚀 Installation
## 🔧 Configuração
### Option 1: n8n Community Nodes (Recommended)
### 1. Obter Credenciais Conecta
1. Open n8n
1. Acesse o [Painel Conecta](https://painel.conecta.com)2. Go to **Settings** → **Community Nodes**
2. Vá para **Configurações** → **API**3. Search for `n8n-nodes-conecta-integrations`
3. Copie seu **API Token**4. Click **Install**
5. Restart n8n
### 2. Configurar Credencial no N8N
### Option 2: npm Installation
1. No N8N, vá para **Credentials** → **New**
2. Pesquise por **Conecta API**
3. Cole o **API Token**
4. Clique em **Save**
### Option 2: npm Installation
```bash
cd ~/.n8n/nodes
npm install n8n-nodes-conecta-integrations
### 3. Configurar Webhook (Opcional)
### Option 3: Docker
Para usar o **Conecta Trigger**:
Add to your `docker-compose.yml`:
1. Adicione o node **Conecta Trigger** ao workflow
2. Copie a URL do webhook gerada```yaml
3. No Painel Conecta, vá para **Configurações** → **Webhooks**services:
4. Cole a URL e selecione os eventos desejados n8n:
5. Salve e ative o workflow no N8N environment:
- N8N_COMMUNITY_PACKAGES=n8n-nodes-conecta-integrations
---```
## 🎬 Quick Start---
### Exemplo 1: Auto-Responder Simples## 🎯 Quick Start
```### Step 1: Create Meta App
┌──────────────────┐
│ Conecta Trigger │ ← Recebe mensagem1. Visit [Meta for Developers](https://developers.facebook.com/apps/)
│ Events: Messages │2. Click **Create App**
└────────┬─────────┘3. Select **Business** type
│ Output 04. Add **Instagram** product
▼5. Note your **App ID** and **App Secret**
┌──────────────────┐
│ IF Node │ ← Verifica se contém "oi"### Step 2: Connect Facebook Page
│ {{ $json.message }}
│ contains "oi" │1. In App Dashboard → **Instagram** → **Basic Display**
└────────┬─────────┘2. Add your Instagram Business Account
│ true3. Generate a **Page Access Token** with required permissions
▼4. Copy the **Instagram Business Account ID**
┌──────────────────┐
│ Conecta Node │ ← Envia resposta### Step 3: Configure n8n Credentials
│ Operation: │
│ Send Message │**Using OAuth2 (Recommended):**
│ │
│ user_id: │1. In n8n: **Credentials** → **New** → **Instagram OAuth2 API**
│ {{$json.userId}} │2. Enter:
│ │ - **Client ID**: Your App ID
│ message: │ - **Client Secret**: Your App Secret
│ "Olá! Como posso │3. Click **Connect my account**
│ ajudar?" │4. Authorize in popup window
└──────────────────┘5. ✅ Connection established!
Using Access Token:
┌──────────────────┐ - **Access Token**: Your Page Access Token
│ Schedule Trigger │ ← Todo dia às 10h3. Click **Save**
│ Cron: 0 10 * * * │4. ✅ Account ID auto-discovered!
└────────┬─────────┘
│### Step 4: Build Your First Workflow
▼
┌──────────────────┐1. Create new workflow
│ HTTP Request │ ← Busca imagem2. Add **Instagram** node
│ Get daily quote │3. Select **Message** → **Send Text Message**
│ image │4. Configure:
└────────┬─────────┘ - **Credential**: Your Instagram credential
│ - **Recipient ID**: Target user's Instagram-scoped ID
▼ - **Message**: Your text content
┌──────────────────┐5. Execute!
│ Conecta Node │ ← Publica story
│ Resource: │---
│ Publishing │
│ │## 📚 Documentation
│ Operation: │
│ Publish Post │### Core Guides
│ │- 📘 [**CHANGELOG.md**](./CHANGELOG.md) - Version history and updates
│ type: stories │- 🔧 [**IMPLEMENTATION_GUIDE.md**](./IMPLEMENTATION_GUIDE.md) - Developer documentation
│ file_type: image │- � [**AUTHENTICATION_GUIDE.md**](./AUTHENTICATION_GUIDE.md) - Setup and OAuth guide
└──────────────────┘- �📋 [**Instruction Files**](./.github/instructions/) - Technical specifications
┌──────────────────┐- 📊 [**FEATURE_SUMMARY.md**](./FEATURE_SUMMARY.md) - Technical implementation details
│ Conecta Trigger │
│ Events: Messages │### Example Workflows
└────────┬─────────┘
│**Messaging:**
▼- Auto-Reply to Messages
┌──────────────────┐- Daily Announcements
│ Function Node │ ← Formata dados- Customer Support Bot
│ return { │
│ data: new Date(),**Content Publishing:**
│ usuario: │- Scheduled Daily Posts
│ $json.user.name,- Automated Carousels
│ mensagem: │- Story Automation
│ $json.message- Product Showcase Reels
│ } │
└────────┬─────────┘### API Reference
│
▼**Message Operations:**
┌──────────────────┐- `sendTextMessage` - Send text content
│ Google Sheets │ ← Salva planilha- `sendImageMessage` - Send image via URL
│ Operation: Append│- `sendAudioMessage` - Send audio file
└──────────────────┘- `sendVideoMessage` - Send video content
```- `sendButtonTemplate` - Interactive buttons
- `sendGenericTemplate` - Carousel cards
---- `sendQuickReplies` - Quick response options
- `uploadMedia` - Upload media files
## 📚 Documentação
**Post Operations (NEW):**
### Guias Completos- `createSinglePost` - Create image/video posts
- `createCarouselPost` - Multi-media carousels
- 📖 [**Conecta Trigger Guide**](./docs/CONECTA_TRIGGER_GUIDE.md) - Documentação completa do webhook- `createReel` - Short-form videos
- 🚀 [**Quick Start Guide**](./docs/CONECTA_TRIGGER_QUICKSTART.md) - Início rápido com exemplos- `publishPost` - Publish created content
- ✅ [**Implementation Checklist**](./docs/CONECTA_TRIGGER_CHECKLIST.md) - Checklist de implementação
- 📊 [**Implementation Summary**](./docs/CONECTA_TRIGGER_IMPLEMENTATION_SUMMARY.md) - Sumário técnico**Story Operations (NEW):**
- `createStory` - Create and publish stories
### Recursos de Publicação
**Media Operations (NEW):**
- 📸 [**Post & Story Guide**](./docs/publish_content/POST_STORY_GUIDE.md) - Guia completo de publicação- `listMedia` - Get your media list
- 💡 [**Examples**](./docs/publish_content/EXAMPLES.md) - Exemplos práticos- `getMedia` - Get media details
- 🎯 [**Feature Summary**](./docs/publish_content/FEATURE_SUMMARY.md) - Resumo de funcionalidades- `getMediaChildren` - Get carousel children
---**User Operations:**
- `getUserProfile` - Fetch user information
## 💡 Exemplos de Uso- `getMyProfile` - Get authenticated account info
### Enviar Mensagem de Texto**Webhook Events:**
- `messages` - Incoming messages
```javascript- `messaging_postbacks` - Button interactions
// Conecta Node- `messaging_optins` - Consent events
Resource: Message
Operation: Send Message---
// Parâmetros## � Token Management (v1.5.0+)
user_id: "123456789"
message: "Olá! Como posso ajudar?"### Automatic Long-Lived Token System
Instagram uses a two-tier token system that this package automatically manages for you:
| Token Type | Validity | Management |
// Conecta Node| Short-lived | 1 hour | Received from OAuth |
Resource: Message| Long-lived | 60 days | **Auto-exchanged** on first use |
Operation: Send Media| Refreshed | 60 days | **Auto-refreshed** before expiration |
// Parâmetros### How It Works
user_id: "123456789"
attachment_type: "image"```
attachment_url: "https://example.com/image.jpg"OAuth Authentication (User action)
``` ↓
Short-lived Token (1 hour)
### Publicar Post no Feed ↓
First API Call (automatic)
```javascript ↓
// Conecta NodeLong-lived Token Exchange (automatic)
Resource: Publishing ↓
Operation: Publish PostToken Valid for 60 Days
↓
// ParâmetrosAuto-refresh at 53 Days (automatic)
type: "feed" ↓
file_type: "image"Another 60 Days of Validity
file_url: "https://example.com/post.jpg"```
caption: "Meu novo post! #n8n #automation"
```### Key Features
### Publicar Carrossel✅ **Zero Configuration** - Everything happens automatically
✅ **No More Errors** - "refreshToken is required" error is eliminated
```javascript✅ **Smart Refresh** - Tokens refresh when at least 24 hours old and expiring within 7 days
// Conecta Node✅ **Fallback Protection** - If refresh fails, attempts to exchange current OAuth token
Resource: Publishing✅ **Secure Storage** - All tokens encrypted in N8N credential system
Operation: Publish Carousel
### Best Practices
// Parâmetros
caption: "Confira nossos produtos!"1. **Keep Workflows Active**: Run at least once every 50 days to maintain token validity
media_items: [2. **Monitor Health**: Create a weekly health-check workflow (optional)
{3. **Handle Errors Gracefully**: Use `continueOnFail` for robust error handling
file_url: "https://example.com/img1.jpg",
file_type: "image"### Token Lifecycle Example
},
{```typescript
file_url: "https://example.com/img2.jpg",// Day 1: OAuth authentication
file_type: "image"User authenticates → Short-lived token (expires in 1 hour)
}
]// Day 1: First workflow run
```First API call → Automatic exchange → Long-lived token (expires in 60 days)
### Acessar Dados do Webhook// Day 53: Automatic refresh (7 days before expiry)
API call → Token check → Auto-refresh → New long-lived token (expires in 60 days)
```javascript
// No workflow após Conecta Trigger// Repeat cycle every ~53 days as long as workflows are active
// Nome do usuário
{{ $json.user.name }}### What If Token Expires?
// Mensagem recebidaIf a workflow is inactive for 60+ days:
{{ $json.message }}1. Token expires and cannot be refreshed
// ID do usuário (para responder)3. Solution: Reconnect your Instagram OAuth2 credential (takes 30 seconds)
{{ $json.userId }}
// Verifica se tem mídia
{{ $json.hasMedia }}📘 TOKEN_MANAGEMENT.md - Comprehensive token management guide
🔧 TOKEN_MANAGEMENT_IMPLEMENTATION.md - Technical implementation details
// URL da primeira imagem
{{ $json.attachments[0].payload.url }}---
## �🔧 Configuration
---
### Webhook Setup
## 🔒 Segurança
1. In Meta App Dashboard → **Instagram** → **Webhooks**
### Validação de Token no Webhook2. Subscribe to `messages` field
3. Callback URL: Your n8n webhook URL
1. Habilite **Validate Token** no Conecta Trigger ```
2. Gere um token seguro: https://your-n8n.com/webhook/instagram
```bash ```
openssl rand -hex 324. Verify Token: Enter in both Meta and n8n credentials
```5. Click **Verify and Save**
3. Configure o token no node
4. Configure o mesmo token no Painel Conecta como:### Rate Limits
Authorization: Bearer SEU_TOKEN_AQUI- API Calls: 200 requests per hour per user
- **Buttons**: 3 per template, 20 characters per title
### Boas Práticas- **Quick Replies**: 13 max per message
- **Webhook Response**: Must respond within 20 seconds
- ✅ Use HTTPS para webhooks em produção
- ✅ Habilite validação de token---
- ✅ Use tokens fortes (32+ caracteres)
- ✅ Monitore logs de acesso## 🛠️ Troubleshooting
- ✅ Implemente rate limiting se necessário
### Common Issues
---
**"Invalid OAuth Access Token"**
## 🐛 Troubleshooting- Verify token hasn't expired
- Check required permissions are granted
### Webhook não recebe eventos- Regenerate token in Meta Developer Console
- ✅ Workflow está **ativo**?**"Webhook Verification Failed"**
- ✅ URL está correta no Painel Conecta?- Ensure verify token matches in both Meta and n8n
- ✅ Eventos corretos selecionados?- Check n8n webhook is publicly accessible via HTTPS
- ✅ Token de validação está correto?- Verify firewall allows Meta's IP ranges
### Erro 401 Unauthorized**"User Cannot Receive Messages"**
- User must initiate conversation first (24-hour window)
- Desabilite **Validate Token** temporariamente- Use message tags for out-of-window messaging
- Verifique formato: `Bearer <token>`- Verify Instagram Business Account is active
- Confirme token igual no N8N e Conecta
**"Rate Limit Exceeded"**
### Mensagem não é enviada- Implement exponential backoff
- Reduce request frequency
- Verifique se API Token está correto- Use batch operations where possible
- Confirme que `user_id` existe
- Verifique limite de mensagens (API)### Debug Mode
---Enable n8n debug logging:
```bash
## 🤝 Contribuindoexport N8N_LOG_LEVEL=debug
n8n start
Contribuições são bem-vindas! Por favor:```
1. Fork o repositório---
2. Crie uma branch para sua feature (`git checkout -b feature/nova-feature`)
3. Commit suas mudanças (`git commit -am 'Adiciona nova feature'`)## 🤝 Support
4. Push para a branch (`git push origin feature/nova-feature`)
5. Abra um Pull Request### Resources
- 📖 [Instagram Graph API Documentation](https://developers.facebook.com/docs/instagram-api)
---- 💬 [n8n Community Forum](https://community.n8n.io)
- 🐛 [Issue Tracker](https://github.com/WilliamAlmeida/n8n-nodes-conecta-integrations/issues)
## 📞 Suporte- 📧 Email: william@wmst.com.br
- 🐛 [Reportar Issues](https://github.com/WilliamAlmeida/n8n-nodes-conecta-integrations/issues)### Contributing
- 💬 [N8N Community](https://community.n8n.io)
- 📧 Email: william@wmst.com.brContributions are welcome! Please:
1. Fork the repository
---2. Create a feature branch
3. Follow existing code style
## 📜 Licença4. Add tests for new features
5. Submit a pull request
MIT License - Veja [LICENSE.md](LICENSE.md) para detalhes.
See [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) for guidelines.
---
## 👨💻 Autor
**William Almeida**
- GitHub: [@WilliamAlmeida](https://github.com/WilliamAlmeida)
- Email: william@wmst.com.br
---
## 📄 License
MIT License - see [LICENSE.md](./LICENSE.md) for details.
Copyright © 2025 William Almeida
---
## ⭐ Changelog## 🙏 Acknowledgments
### v2.0.0 (2024-10-20)- Built with [n8n](https://n8n.io) - Fair-code workflow automation
- Powered by [Instagram Graph API](https://developers.facebook.com/docs/instagram-api)
#### 🎉 Nova Versão - Conecta API- Icons by [Instagram Brand Guidelines](https://en.instagram-brand.com/)
- ✅ **Removido:** Suporte ao Instagram Graph API (antigo)---
- ✅ **Adicionado:** Conecta Node completo
- ✅ **Adicionado:** Conecta Trigger com 9 tipos de eventos## 📊 Stats
- ✅ **Adicionado:** Suporte a publicação de conteúdo
- ✅ **Adicionado:** Gestão completa de chats
- ✅ **Adicionado:** Envio de mídias e templates
- ✅ **Melhorado:** Documentação completa
- ✅ **Melhorado:** Exemplos práticos
#### Migração---
Se você estava usando a versão antiga (Instagram Graph API), este pacote agora usa exclusivamente a **Conecta API**. **Made with ❤️ for the n8n community** | [GitHub](https://github.com/WilliamAlmeida/n8n-nodes-conecta-integrations) | [npm](https://www.npmjs.com/package/n8n-nodes-conecta-integrations)
**Ação necessária:**
1. Obtenha credenciais da Conecta API
2. Reconfigure seus workflows com os novos nodes
3. Consulte a documentação para detalhes
---
## 🙏 Agradecimentos
- Equipe N8N pela excelente plataforma
- Conecta pela API robusta
- Comunidade open source
---
**⭐ Se este projeto foi útil, considere dar uma estrela no GitHub!**
---
Made with ❤️ by [William Almeida](https://github.com/WilliamAlmeida)
FAQs
N8N nodes for Conecta API integration - Instagram messaging, webhooks, and content publishing
The npm package n8n-nodes-conecta-integrations receives a total of 9 weekly downloads. As such, n8n-nodes-conecta-integrations popularity was classified as not popular.
We found that n8n-nodes-conecta-integrations demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Socket CTO Ahmad Nassri discusses why supply chain attacks now target developer machines and what AI means for the future of enterprise security.
Security News
Learn the essential steps every developer should take to stay secure on npm and reduce exposure to supply chain attacks.
Security News
Experts push back on new claims about AI-driven ransomware, warning that hype and sponsored research are distorting how the threat is understood.