conecta-integrations

N8N nodes for Conecta API integration - Instagram messaging, webhooks, and content publishing

Package Information

Downloads: 0 weekly / 12 monthly

Latest Version: 2.0.2

Author: William Almeida

Available Nodes

Conecta

Integração com a plataforma Conecta API

Conecta Trigger

Dispara workflow em eventos de webhook do Instagram via Conecta

Documentation

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.

Visão Geral
Instalação Installation • Features • Prerequisites • Quick Start • Documentation • Support
Nodes Disponíveis
Quick Start---
Documentação
Exemplos de Uso## 📖 Overview
Suporte
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)

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: 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![npm](https://img.shields.io/npm/v/n8n-nodes-conecta-integrations)

- ✅ **Adicionado:** Envio de mídias e templates![downloads](https://img.shields.io/npm/dt/n8n-nodes-conecta-integrations)

- ✅ **Melhorado:** Documentação completa![license](https://img.shields.io/npm/l/n8n-nodes-conecta-integrations)

- ✅ **Melhorado:** Exemplos práticos![node version](https://img.shields.io/node/v/n8n-nodes-conecta-integrations)



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

conecta-integrationsInstall