n8n-nodes-conecta-integrations
v2.0.2
Published
N8N nodes for Conecta API integration - Instagram messaging, webhooks, and content publishing
Maintainers
williamhatakeReadme
n8n-nodes-conecta-integrations
N8N nodes para integração completa com a API Conecta - Instagram Messaging, Webhooks e Publicação de Conteúdo.
📋 Índice
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:
- 🤖 Automated customer support via Instagram DM
🎯 Visão Geral- 📢 Marketing campaigns and notifications
- 🎯 Lead generation and engagement
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)
- 🆕 No more "refreshToken is required" errors - Smart token lifecycle management prevents expiration issues
🚀 Instalação- Multiple credential types - OAuth2 or manual access token
- Auto-discovery - Automatically fetches Instagram Business Account ID
Via NPM (Recomendado)
📬 Instagram Messaging Node
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:
Exemplo 2: Publicar Story Diário
- In n8n: Credentials → New → Instagram Access Token API
┌──────────────────┐ - **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
Content Publishing Guides (NEW!)
Exemplo 3: Salvar Mensagens no Google Sheets- 🚀 QUICKSTART.md - Get started in 5 minutes
- 📸 POST_STORY_GUIDE.md - Complete post/story creation guide
┌──────────────────┐- 📊 [**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:
Enviar Imagem
| 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
- Workflow shows error: "Instagram access token has expired"
// ID do usuário (para responder)3. Solution: Reconnect your Instagram OAuth2 credential (takes 30 seconds)
{{ $json.userId }}
Learn More
// 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: [email protected]
- 🐛 [Reportar Issues](https://github.com/WilliamAlmeida/n8n-nodes-conecta-integrations/issues)### Contributing
- 💬 [N8N Community](https://community.n8n.io)
- 📧 Email: [email protected] 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: [email protected]
---
## 📄 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)