n8n-nodes-metricool-api

Un connecteur n8n pour l'API Metricool qui permet l'intégration avec l'interface Inbox de Metricool.

Installation

Via npm (Recommandé pour n8n auto-hébergé)

npm install n8n-nodes-metricool-api

Installation manuelle

1. Téléchargez la dernière version depuis les releases
2. Extrayez le package dans votre dossier ~/.n8n/custom/
3. Redémarrez n8n

Configuration

Credentials Metricool API

Pour utiliser ce connecteur, vous aurez besoin de :

1. User Token : Le code d'autorisation unique de votre utilisateur trouvé dans les paramètres de compte
2. User ID : L'identifiant utilisateur de votre compte Metricool
3. Blog ID : Le numéro d'identification de la marque (trouvé dans l'URL du navigateur)

Comment obtenir vos credentials

1. Connectez-vous à votre compte Metricool
2. Allez dans Paramètres du compte
3. Trouvez votre User Token dans la section API
4. Notez votre User ID
5. Le Blog ID se trouve dans l'URL quand vous naviguez dans votre tableau de bord

Fonctionnalités

Ce connecteur prend en charge les opérations suivantes :

🗨️ Conversations

• Récupérer plusieurs conversations : Obtenir une liste de conversations
• Publier un message : Envoyer un message à une conversation
• Vérifier les autorisations : Vérifier les autorisations pour les conversations
• Récupérer une image : Récupérer une image depuis les conversations

⭐ Reviews (Nouveau)

• Récupérer plusieurs avis : Obtenir une liste d'avis clients
• 📊 Surveiller les avis (Monitor Reviews) : NOUVEAU - Surveiller automatiquement les nouveaux avis sans réponse pour traitement IA
• Publier une réponse : Répondre à un avis client
• Supprimer une réponse : Supprimer une réponse à un avis

🤖 Monitor Reviews - Traitement IA automatique

Cette nouvelle fonctionnalité permet de surveiller en continu les avis Google My Business (et autres plateformes) pour détecter automatiquement ceux nécessitant une réponse et les traiter avec une IA.

Caractéristiques :

• ⏰ Surveillance temporelle : Configure la fenêtre de temps (1-168 heures) pour vérifier les nouveaux avis
• 🎯 Filtrage intelligent : Filtre par statut (PENDING pour les avis sans réponse)
• ⭐ Filtrage par notes : Définit une note minimale (1-5 étoiles)
• 🏷️ Métadonnées IA : Enrichit automatiquement chaque avis avec :
  • sentiment : positive, neutral, negative (basé sur les étoiles)
  • priority : high, medium, low (basé sur les étoiles et la récence)
  • suggestedAction : urgent_response_needed, thank_customer, acknowledge_feedback

Cas d'utilisation :

• Déclencher automatiquement un workflow IA toutes les heures
• Détecter les avis négatifs nécessitant une attention urgente
• Automatiser les réponses aux avis positifs
• Intégrer avec des services IA comme OpenAI, Claude, etc.

Providers supportés

Le champ Provider propose maintenant une liste de réseaux sociaux prédéfinis :

• Facebook
• Instagram
• Twitter/X
• LinkedIn
• TikTok
• YouTube
• Google My Business
• Pinterest
• Personnalisé (pour les autres providers)

📝 Notes

• Récupérer plusieurs notes : Obtenir une liste de notes
• Créer : Créer une nouvelle note
• Mettre à jour : Modifier une note existante
• Supprimer : Supprimer une note

💬 Commentaires de publications

• Récupérer plusieurs commentaires : Obtenir une liste de commentaires de publications
• Publier un commentaire : Ajouter un commentaire
• Supprimer un commentaire : Supprimer un commentaire
• Vérifier les autorisations : Vérifier les autorisations pour les commentaires

⭐ Avis

• Récupérer plusieurs avis : Obtenir une liste d'avis
• Publier une réponse : Répondre à un avis
• Supprimer une réponse : Supprimer une réponse à un avis

📊 Statut

• Changer le statut : Modifier le statut de la boîte de réception

Exemples d'utilisation

Récupérer des conversations

{
  "resource": "conversations",
  "operation": "getAll",
  "provider": "instagram"
}

Créer une note

{
  "resource": "notes",
  "operation": "create",
  "noteBody": {
    "content": "Nouvelle note de suivi client",
    "participantScreenNames": ["user1", "user2"],
    "participantAccountIds": ["123", "456"],
    "provider": "facebook"
  }
}

Publier un message

{
  "resource": "conversations",
  "operation": "postMessage",
  "messageBody": {
    "conversationId": "conv_123",
    "message": "Merci pour votre message !",
    "provider": "instagram"
  }
}

Récupérer des avis

{
  "resource": "reviews",
  "operation": "getAll",
  "provider": "google"
}

Monitorer les nouveaux avis GMB avec traitement IA

{
  "resource": "reviews",
  "operation": "monitorReviews",
  "provider": "google",
  "timeWindowHours": 24,
  "minStarRating": 1
}

Note importante : Cette opération détecte automatiquement les avis sans réponse en vérifiant l'absence de la propriété reply. Le statut interne Metricool (PENDING/READ) est optionnel.

Configuration d'un workflow automatisé

Voici un exemple de workflow n8n qui s'exécute toutes les heures pour traiter automatiquement les nouveaux avis Google My Business :

1. Trigger horaire (Cron Trigger)

{
  "cronExpression": "0 * * * *",
  "timezone": "Europe/Paris"
}

2. Nœud Metricool - Monitor Reviews

{
  "resource": "reviews",
  "operation": "monitorReviews",
  "provider": "google",
  "timeWindowHours": 1,
  "minStarRating": 1
}

3. Condition - Vérifier s'il y a de nouveaux avis

// Expression n8n pour vérifier si des avis ont été trouvés
return $json.length > 0

4. Traitement IA pour chaque avis

Pour chaque avis trouvé, vous pouvez utiliser les métadonnées IA générées :

• aiMetadata.sentiment : Sentiment détecté (positive, negative, neutral)
• aiMetadata.priority : Priorité calculée (high, medium, low)
• aiMetadata.suggestedAction : Action suggérée (respond_immediately, respond_soon, monitor, thank)
• aiMetadata.needsResponse : Indique si une réponse est nécessaire

5. Génération de réponse automatique

Selon la logique définie dans Org.mmd, vous pouvez :

• Envoyer les avis négatifs (1-2 étoiles) vers un agent humain
• Générer des réponses automatiques pour les avis positifs
• Programmer des notifications pour les avis neutres

Exemple de workflow complet

{
  "name": "GMB Reviews AI Monitor",
  "nodes": [
    {
      "name": "Every Hour",
      "type": "n8n-nodes-base.cron",
      "parameters": {
        "rule": {
          "interval": [{"field": "hours", "step": 1}]
        }
      }
    },
    {
      "name": "Monitor GMB Reviews",
      "type": "n8n-nodes-metricool-api",
      "parameters": {
        "resource": "reviews",
        "operation": "monitorReviews",
        "provider": "google",
        "timeWindowHours": 1
      }
    },
    {
      "name": "Has New Reviews?",
      "type": "n8n-nodes-base.if",
      "parameters": {
        "conditions": {
          "options": {
            "leftValue": "={{$json.length}}",
            "operation": "greaterThan",
            "rightValue": 0
          }
        }
      }
    },
    {
      "name": "Process Each Review",
      "type": "n8n-nodes-base.function",
      "parameters": {
        "functionCode": "// Traiter chaque avis selon sa priorité IA\nfor (const review of items) {\n  const priority = review.json.aiMetadata.priority;\n  const sentiment = review.json.aiMetadata.sentiment;\n  \n  if (priority === 'high' && sentiment === 'negative') {\n    // Envoyer une alerte immédiate\n    review.json.action = 'alert_human';\n  } else if (sentiment === 'positive') {\n    // Réponse automatique de remerciement\n    review.json.action = 'auto_thank';\n  }\n}\n\nreturn items;"
      }
    }
  ]
}

Développement

Prérequis

• Node.js ≥ 18.10
• pnpm ≥ 8.1

Installation des dépendances

pnpm install

Build

pnpm build

Développement en mode watch

pnpm dev

Linting et formatage

pnpm lint
pnpm format

Structure du projet

n8n-nodes-metricool-api/
├── credentials/
│   └── MetricoolApi.credentials.ts
├── nodes/
│   └── Metricool/
│       ├── Metricool.node.ts
│       └── metricool-icon.svg
├── dist/                          # Fichiers compilés
├── package.json
├── tsconfig.json
└── README.md

API Endpoints supportés

Ce connecteur utilise l'API Metricool v2 :

• GET /v2/inbox/conversations
• POST /v2/inbox/conversations
• GET /v2/inbox/conversations/authorizations
• GET /v2/inbox/conversations/fetch-image
• GET /v2/inbox/notes
• POST /v2/inbox/notes
• PUT /v2/inbox/notes/{id}
• DELETE /v2/inbox/notes/{id}
• GET /v2/inbox/post-comments
• POST /v2/inbox/post-comments
• DELETE /v2/inbox/post-comments
• GET /v2/inbox/post-comments/authorizations
• GET /v2/inbox/reviews
• POST /v2/inbox/reviews/replies
• DELETE /v2/inbox/reviews/replies
• PUT /v2/inbox/status

Contribution

Les contributions sont les bienvenues ! Veuillez :

1. Fork le projet
2. Créer une branche pour votre fonctionnalité
3. Committer vos changements
4. Pousser vers la branche
5. Créer une Pull Request

Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.

Changelog

Version 1.2.0 (Septembre 2024)

• ✅ Amélioration du champ Provider : Ajout d'une liste déroulante avec les réseaux sociaux populaires
• ✅ Support des providers personnalisés : Possibilité de saisir des providers non listés
• ✅ Correction des erreurs "Bad request" : Résolution des doublons baseURL qui causaient des erreurs HTTP

Version 1.1.2 (Septembre 2024)

• ✅ Correction des erreurs baseURL : Suppression des doublons qui causaient des erreurs de compilation
• ✅ Stabilisation des requêtes HTTP : Toutes les opérations ont maintenant un baseURL cohérent

Version 1.1.1 (Septembre 2024)

• ✅ Ajout de l'endpoint Reviews : Support complet de /v2/inbox/reviews GET
• ✅ Correction des erreurs "Invalid URL" : Ajout des baseURL manquants

Support

Si vous rencontrez des problèmes :

1. Vérifiez que vos credentials Metricool sont corrects
2. Consultez les issues GitHub
3. Créez une nouvelle issue si nécessaire

Liens utiles

• Documentation n8n
• API Metricool
• Créer des nodes n8n personnalisés

Développé avec ❤️ pour la communauté n8n