n8n-nodes-dinastiapi

This is an n8n community node that provides a complete integration with DinastiAPI - a multi-user and multi-device REST API for WhatsApp.

DinastiAPI implements a robust WhatsApp Web API that allows you to send and receive messages, manage groups, handle media files, and much more through a simple REST interface.

n8n is a fair-code licensed workflow automation platform.

Table of Contents

• Installation
• Operations
• Credentials
• Nodes Overview
• Message Configuration Parameters
• Usage Examples
• Features
• Error Handling
• Compatibility
• Resources

Installation

Follow the installation guide in the n8n community nodes documentation.

Quick Installation

1. In n8n, go to Settings > Community Nodes
2. Click Install a community node
3. Enter n8n-nodes-dinastiapi
4. Click Install

Manual Installation

npm install n8n-nodes-dinastiapi

Operations

This package includes 11 specialized nodes, each focused on specific WhatsApp operations:

🔐 DinastiAPI Credentials

Handles authentication with your DinastiAPI instance.

📱 DinastiAPI Session

• Connect - Connect to WhatsApp servers
• Disconnect - Disconnect from WhatsApp
• Get Status - Check connection status
• Get QR Code - Get QR code for scanning
• Logout - Logout and terminate session
• Pair Phone - Get pairing code for phone
• Set Proxy - Configure proxy settings
• Configure S3 - Set up S3 storage for media
• Test S3 - Test S3 connection

💬 DinastiAPI Message

Send various types of messages:

• Text - Send text messages
• Image - Send images with optional captions
• Audio - Send audio messages
• Video - Send videos with optional captions
• Document - Send documents of any type
• Sticker - Send stickers
• Location - Send location coordinates
• Contact - Send contact cards (vCard)
• Template - Send template messages with buttons
• Buttons - Send interactive button messages
• List - Send list messages
• Poll - Send polls to groups

🗨️ DinastiAPI Chat

Manage chat interactions:

• Delete Message - Delete sent messages
• Edit Message - Edit previously sent messages
• Download Media - Download media from messages
• Mark as Read - Mark messages as read
• React to Message - Send reactions to messages
• Set Presence - Show typing/recording indicators

👤 DinastiAPI User

User information and presence:

• Check Users - Check if users have WhatsApp
• Get User Info - Get detailed user information
• Get Avatar - Get user profile pictures
• Get Contacts - Get all contacts
• Set Presence - Set global online/offline status
• Get Business Profile - Get complete business profile information
• Get Privacy Settings - Get privacy settings for the current user
• Get My Status - Get current user status message
• Set My Status - Set current user status message
• Update Push Name - Update display name (push name)
• Get LID From Phone - Get Local ID (LID) from phone number/JID
• Get Phone From LID - Get phone number/JID from Local ID (LID)
• List LID Mappings - List all LID-Phone mappings

👥 DinastiAPI Group

Complete group management:

• Create - Create new groups
• List - List all groups
• Get Info - Get group information
• Get Invite Link - Get group invite link
• Join - Join group via invite
• Leave - Leave a group
• Set Name - Change group name
• Set Description - Set group description
• Set Photo - Set group photo
• Remove Photo - Remove group photo
• Set Announce - Enable/disable admin-only messages
• Set Locked - Lock/unlock group info editing
• Set Ephemeral - Configure disappearing messages
• Update Participants - Add/remove/promote/demote members

🔗 DinastiAPI Webhook

Configure webhook settings:

• Get - Get current webhook configuration
• Set - Configure webhook URL and events
• Update - Update webhook settings
• Delete - Remove webhook configuration

👨‍💼 DinastiAPI Admin

Administrative operations (requires admin token):

• List Users - List all DinastiAPI users
• Create User - Create new user with token
• Delete User - Delete user from database
• Delete User Full - Complete user removal (DB, S3, logout)

🔔 DinastiAPI Trigger

Receive real-time WhatsApp events with complete event mapping:

• Events - Message, Read Receipt, Presence, History Sync, Chat Presence, All Events
• Advanced Filters - Filter by sender phone, chat ID, message type, content, groups/direct, from me/others, token
• Message Type Detection - Automatic detection of text, media, PTT, documents, stickers, URLs, locations, contacts, buttons, lists, templates, polls, orders, and unknown types
• Media Support - Complete base64 and S3 media data extraction
• Content Parsing - Intelligent message content extraction with type-specific fields
• Simplified Output - Clean, structured output with all relevant fields mapped
• Raw Data Access - Optional complete raw webhook data for debugging

⏳ DinastiAPI Send and Wait

Send messages and wait for responses:

• Approval Messages - Send messages with approval buttons
• Free Text Response - Wait for user text input via web form
• Custom Forms - Create custom forms for user responses
• Wait Time Limits - Set maximum wait times
• Attribution - Optional n8n branding

🤖 DinastiAPI AI

Optimized for AI workflows and tools with complete message type support:

• Send Text - Send text messages with AI-friendly interface
• Send Image - Send images with captions (Binary/Base64/URL)
• Send Audio - Send audio messages with PTT support (Binary/Base64/URL)
• Send Video - Send videos with captions (Binary/Base64/URL)
• Send Document - Send documents with filenames (Binary/Base64/URL)
• Send Location - Send geographical coordinates with location names
• Send Contact - Send contact information with VCard data
• Send Sticker - Send stickers in WebP format (Binary/Base64/URL)
• Send Buttons - Send interactive button messages for AI decision trees
• Send List - Send structured lists with multiple options for AI menus
• Send Poll - Send group polls for AI-driven surveys and decisions
• Get Status - WhatsApp connection and session status
• Get Business Profile - Get complete business profile information including business hours, categories, and contact details
• Get My Status - Get current user status message and status settings
• Check User - Validate if phone numbers have WhatsApp accounts
• Get Avatar - Universal avatar retrieval for users, groups, newsletters, and LIDs
• Get User Info - Detailed user information and presence data
• List Groups - All WhatsApp groups with metadata
• List Newsletters - Available newsletters and channels
• Universal Media Support - All media types support Binary Data, Base64, and URL sources
• Mention System - Complete mention support for specific users and all group members
• Batch Processing - Process multiple recipients and message types efficiently
• Error Tolerance - Continue workflow execution on individual failures
• AI Tools Compatible - Perfect for use with n8n AI Tools and automation

Credentials

To use these nodes, you need to configure the DinastiAPI credentials:

1. API Token - Your DinastiAPI user token for authentication
2. API URL - The base URL of your DinastiAPI instance

Credential Validation

The credentials are automatically validated when configured. The validation provides real-time information about your DinastiAPI session:

• Authentication Status - Confirms API token validity
• Session Information - Shows session name, connection status, and login state
• Dynamic Messages - Example: "Connected to setupautomatizado (Connected, Logged In)"

3. Advanced Options (Optional):
   • Proxy URL - HTTP/SOCKS5 proxy for requests
   • Request Timeout - Timeout in milliseconds
   • Retry on Failure - Enable automatic retries
   • Max Retries - Maximum retry attempts

Setting up DinastiAPI

1. Install and run DinastiAPI following the official documentation
2. Create a user with an authentication token
3. Use the token and API URL in n8n credentials

Nodes Overview

Modular Design

This package follows a modular design where each node focuses on specific functionality:

• Session Management - Connection, authentication, and configuration
• Messaging - All message sending operations
• Chat Operations - Message management and interactions
• User Operations - User information and presence
• Group Management - Complete group functionality
• Webhook Configuration - Event subscription management
• Administration - User management (admin only)
• Event Trigger - Real-time event reception
• Send and Wait - Interactive approval workflows
• AI Integration - Optimized node for AI Tools and workflows

Key Features

• ✅ Complete API Coverage - All DinastiAPI endpoints implemented across 11 specialized nodes
• 🔄 Automatic Retry Logic - Built-in retry mechanism with exponential backoff
• 🛡️ Robust Error Handling - Graceful error handling with detailed messages
• 🎯 Type Safety - Full TypeScript implementation with comprehensive type checking
• 📦 Universal Media Support - Handle all media types with Binary Data, Base64, and URL sources
• 🔐 Multi-tenant Support - Each user has independent WhatsApp sessions
• ☁️ S3 Integration - Optional cloud storage for media files with automatic delivery
• 🌐 Proxy Support - HTTP/SOCKS5 proxy configuration for all operations
• ⚡ High Performance - Optimized for production use with efficient media handling
• 🎨 User-Friendly - Intuitive interface with helpful descriptions and examples
• 🤖 Complete AI Integration - Dedicated AI node with full message type support (11 types)
• 💬 Interactive Messages - Full support for buttons, lists, polls, and stickers
• 🎯 Mention System - Complete mention support for individuals and group-wide mentions
• 📱 Media Optimization - Smart media source detection and URL support for reduced payloads
• ✅ Enhanced Validation - Real-time credential validation with session status
• 🔧 Batch Processing - Efficient processing of multiple operations with error tolerance
• 🌍 Multi-format Support - WebP stickers, VCard contacts, geographic locations
• 📊 Group Intelligence - Advanced group management with polls and administrative controls

Message Configuration Parameters

Advanced Message Options

Both DinastiAPIMessage and DinastiAPIAI nodes support comprehensive message configuration through the Additional Options section:

Core Parameters

• Message ID - Custom message identifier for tracking (auto-generated if not provided)
• Presence Simulation - Simulate typing/recording indicators (0-30,000ms)
  • Text/Documents: Shows typing indicator
  • Audio/Video: Shows recording indicator
  • Example: 2000 for 2-second typing simulation

WhatsApp Features

• Message Duration - Disappearing messages with expiration times:

  • 0 - No expiration (default)
  • 86400 - 24 hours
  • 604800 - 7 days
  • 7776000 - 90 days

• View Once - Single-view messages (image/video/audio only)

  • true - Message disappears after single view
  • false - Normal message (default)

• Link Preview - Automatic URL preview for text messages

  • true - Generate rich link previews
  • false - Plain text URLs (default)

Message Context & Threading

• Forward Message - Mark message as forwarded

  • isForwarded: true - Shows "Forwarded" label

• Reply To Message - Thread replies to specific messages

  {
    "contextInfo": {
      "context": [{
        "stanzaId": "MESSAGE_ID_TO_REPLY_TO",
        "participant": "[email protected]"
      }]
    }
  }
  

• Forward Information - Enhanced forwarding structure

  {
    "forwardInfo": {
      "forward": [{
        "isForwarded": true
      }]
    }
  }
  

Mention System

• Specific Users - Mention individual users

  {
    "mentions": {
      "mentionConfig": [{
        "type": "specific",
        "jids": "[email protected],[email protected]"
      }]
    }
  }
  

• All Group Members - Mention everyone in group

  {
    "mentions": {
      "mentionConfig": [{
        "type": "all"
      }]
    }
  }
  

Supported Recipients

All messaging operations support multiple recipient types:

• Phone Numbers: 5491155553934 (automatically formatted to @s.whatsapp.net)
• Groups: [email protected]
• Newsletters: 120363025246943103@newsletter
• LIDs: user@lid

Media Source Options

All media types (image, audio, video, document, sticker) support three source types:

Binary Data

{
  "imageSource": "binary",
  "binaryProperty": "data"
}

Base64 Encoding

{
  "imageSource": "base64", 
  "imageBase64": "data:image/jpeg;base64,iVBORw0KGgoAAAANSUhEUgAA..."
}

URL Sources

{
  "imageSource": "url",
  "imageUrl": "https://example.com/image.jpg"
}

Message Types & Parameters

Text Messages

{
  "messageType": "text",
  "phone": "5491155553934",
  "body": "Hello World!",
  "additionalOptions": {
    "linkPreview": true,
    "presence": 2000
  }
}

Image Messages

{
  "messageType": "image",
  "phone": "5491155553934", 
  "imageSource": "url",
  "imageUrl": "https://example.com/image.jpg",
  "caption": "Check this out!",
  "additionalOptions": {
    "viewOnce": true,
    "presence": 1500
  }
}

Audio Messages

{
  "messageType": "audio",
  "phone": "5491155553934",
  "audioSource": "url", 
  "audioUrl": "https://example.com/audio.ogg",
  "additionalOptions": {
    "presence": 3000
  }
}

Video Messages

{
  "messageType": "video",
  "phone": "5491155553934",
  "videoSource": "url",
  "videoUrl": "https://example.com/video.mp4", 
  "caption": "Amazing video!",
  "additionalOptions": {
    "viewOnce": true,
    "duration": 86400
  }
}

Document Messages

{
  "messageType": "document",
  "phone": "5491155553934",
  "documentSource": "url",
  "documentUrl": "https://example.com/document.pdf",
  "fileName": "report.pdf",
  "additionalOptions": {
    "presence": 2500
  }
}

Location Messages

{
  "messageType": "location",
  "phone": "5491155553934",
  "latitude": 48.858370,
  "longitude": 2.294481,
  "locationName": "Eiffel Tower"
}

Contact Messages

{
  "messageType": "contact",
  "phone": "5491155553934",
  "contactName": "John Doe",
  "vcard": "BEGIN:VCARD\nVERSION:3.0\nFN:John Doe\nTEL:+1234567890\nEND:VCARD"
}

Button Messages

{
  "messageType": "buttons",
  "phone": "5491155553934",
  "body": "Choose an option:",
  "additionalOptions": {
    "mentions": {
      "mentionConfig": [{
        "type": "all"
      }]
    }
  }
}

List Messages

{
  "messageType": "list",
  "phone": "[email protected]",
  "buttonText": "Choose Service",
  "description": "Select the service you need",
  "topText": "Available Services",
  "footerText": "Powered by AI",
  "listItems": {
    "item": [
      {
        "title": "Technical Support",
        "desc": "Get help with technical issues", 
        "rowId": "tech_support"
      },
      {
        "title": "Sales Information",
        "desc": "Learn about our products",
        "rowId": "sales_info"
      }
    ]
  }
}

Poll Messages

{
  "messageType": "poll",
  "phone": "[email protected]",
  "pollHeader": "Which feature should we prioritize?",
  "pollOptions": "AI Chat,Voice Messages,File Sharing,Video Calls"
}

Link Messages

{
  "messageType": "link",
  "phone": "5491155553934",
  "link": "https://example.com",
  "linkCaption": "Check out this amazing website!",
  "additionalOptions": {
    "presence": 1000
  }
}

Sticker Messages

{
  "messageType": "sticker",
  "phone": "5491155553934",
  "stickerSource": "url",
  "stickerUrl": "https://example.com/sticker.webp"
}

Complete Example with All Features

{
  "messageType": "image",
  "phone": "[email protected]",
  "imageSource": "url",
  "imageUrl": "https://example.com/photo.jpg",
  "caption": "Team photo from today's meeting! @everyone",
  "additionalOptions": {
    "id": "custom_msg_001",
    "presence": 2000,
    "duration": 604800,
    "viewOnce": false,
    "isForwarded": true,
    "contextInfo": {
      "context": [{
        "stanzaId": "PREVIOUS_MESSAGE_ID",
        "participant": "[email protected]"
      }]
    },
    "mentions": {
      "mentionConfig": [{
        "type": "all"
      }]
    },
    "forwardInfo": {
      "forward": [{
        "isForwarded": true
      }]
    }
  }
}

Best Practices

Presence Simulation

• Text Messages: Use 1000-3000ms for natural typing simulation
• Audio Messages: Use 2000-5000ms for recording simulation
• Long Messages: Calculate ~100ms per word for realistic timing
• Groups: Keep under 2000ms to avoid spam appearance

Message Duration

• Sensitive Data: Use 24 hours (86400) for confidential information
• Temporary Messages: Use 7 days (604800) for time-sensitive content
• Compliance: Use 90 days (7776000) for audit trail requirements

View Once Messages

• Security: Use for passwords, sensitive documents, private photos
• Business: Use for confidential reports, temporary access codes
• Support: Supported only for image, video, and audio messages

Mentions

• Groups: Use type: "all" sparingly to avoid notification fatigue
• Specific: Always include proper JID format (@s.whatsapp.net)
• Mixed: You can combine specific mentions with other message features

Media Sources

• Performance: URL sources are fastest and reduce payload size
• Reliability: Binary data is most reliable for critical media
• Compatibility: Base64 offers good balance of reliability and performance

Error Handling

• Continue on Fail: Enable for batch operations to process all items
• Validation: Always validate phone numbers and JIDs before sending
• Timeouts: Set appropriate timeouts for media-heavy operations

Usage Examples

Send a Text Message

// Using DinastiAPI Message node
{
  "messageType": "text",
  "phone": "5491155553934",
  "body": "Hello from n8n!"
}

Send an Image with Caption

// Using DinastiAPI Message node
{
  "messageType": "image",
  "phone": "5491155553934",
  "imageSource": "binary",
  "binaryProperty": "data",
  "caption": "Check out this image!"
}

Create a Group

// Using DinastiAPI Group node
{
  "operation": "create",
  "groupName": "My n8n Group",
  "participants": "5491155553934,5491155553935"
}

Set Up Webhook Trigger

// Using DinastiAPI Trigger node - Basic setup
{
  "events": ["Message", "ReadReceipt"],
  "filters": {
    "messageType": "text",
    "isGroup": "false"
  }
}

Advanced Trigger Configuration

// Complete trigger setup with all features
{
  "events": ["Message"],
  "filters": {
    "fromPhone": "[email protected]",
    "chatId": "[email protected]",
    "messageType": "media",
    "containsText": "urgent",
    "isGroup": "true",
    "isFromMe": "false",
    "tokenFilter": "setupautomatizado"
  },
  "options": {
    "simplifyOutput": true,
    "includeMediaData": true,
    "parseMessageContent": true,
    "includeRawData": false
  }
}

Trigger Output Example

// Simplified output for a text message
{
  "eventType": "Message",
  "token": "setupautomatizado",
  "messageId": "A6BA5FB09055C47722F936C3FC74D98F",
  "chat": "[email protected]", 
  "sender": "[email protected]",
  "timestamp": "2025-05-28T06:47:26-03:00",
  "messageType": "text",
  "isFromMe": false,
  "isGroup": false,
  "pushName": "Guilherme Jansen",
  "verifiedName": "Guilherme Jansen - Setup Automatizado",
  "text": "Oi"
}

Media Message Output

// Output for audio message with S3 and base64 data
{
  "eventType": "Message",
  "messageType": "ptt",
  "audioUrl": "https://mmg.whatsapp.net/v/...",
  "duration": 3,
  "mimeType": "audio/ogg; codecs=opus",
  "mediaBase64": "T2dnUwACAAAAAAAA...",
  "mediaMimeType": "application/ogg",
  "mediaFileName": "DB56752B6A203E5A96A2E533C4D0A7CF.oga",
  "s3Data": {
    "bucket": "evolution",
    "key": "users/2fb8378b312c1d2dd127e094d9a99115/inbox/...",
    "url": "https://s3.setupautomatizado.com.br/evolution/...",
    "size": 8084
  }
}

Interactive Message Output

// Output for buttons message
{
  "eventType": "Message",
  "messageType": "buttons",
  "text": "ESCOLHA O MENU!",
  "buttons": [
    {
      "id": "81ad952f-1085-4d2c-a4b9-de228cfc4117",
      "text": "SUPORTE",
      "type": 1
    },
    {
      "id": "a4767ccb-ded6-4edd-be6a-363972fdaa0f",
      "text": "COMERCIAL",
      "type": 1
    },
    {
      "id": "8f72fd66-1e6f-48bd-a5b5-c509fcc5a9f1",
      "text": "ATENDIMENTO",
      "type": 1
    }
  ]
}

// Output for list message
{
  "eventType": "Message",
  "messageType": "list",
  "title": "<HEADER_TEXT>",
  "text": "<BODY_TEXT>",
  "buttonText": "<BUTTON_TEXT>",
  "sections": [
    {
      "title": "<LIST_SECTION_1_TITLE>",
      "rows": [
        {
          "id": "<LIST_SECTION_1_ROW_1_ID>",
          "title": "<SECTION_1_ROW_1_TITLE>",
          "description": "<SECTION_1_ROW_1_DESC>"
        }
      ]
    }
  ]
}

Send AI-Generated Message

// Using DinastiAPI AI node - Perfect for AI workflows
{
  "operation": "sendText",
  "phoneNumber": "5491155553934",
  "message": "Hello! This is an AI-generated response from n8n."
}

Send Multiple Media Files (AI Batch)

// Using DinastiAPI AI node with multiple items
[
  {
    "operation": "sendImage",
    "phoneNumber": "5491155553934",
    "imageSource": "url",
    "imageUrl": "https://example.com/image1.jpg",
    "caption": "AI Analysis Result 1"
  },
  {
    "operation": "sendDocument",
    "phoneNumber": "5491155553935",
    "documentSource": "url", 
    "documentUrl": "https://example.com/report.pdf",
    "fileName": "AI_Report.pdf",
    "caption": "Generated Report"
  }
]

Send Interactive Messages with AI

// Send sticker for reactions
{
  "operation": "sendSticker",
  "phoneNumber": "5491155553934",
  "stickerSource": "url",
  "stickerUrl": "https://example.com/thumbs-up.webp"
}

// Send buttons for AI decision tree
{
  "operation": "sendButtons",
  "phoneNumber": "5491155553934",
  "message": "How can I help you today?",
  "additionalOptions": {
    "mentions": {
      "mentionConfig": [{
        "type": "specific",
        "jids": "[email protected]"
      }]
    }
  }
}

// Send list for AI-generated menu
{
  "operation": "sendList",
  "phoneNumber": "[email protected]",
  "buttonText": "Choose Service",
  "description": "Select the service you need",
  "topText": "AI Assistant Services",
  "footerText": "Powered by AI",
  "listItems": {
    "item": [
      {
        "title": "Technical Support",
        "desc": "Get help with technical issues",
        "rowId": "tech_support"
      },
      {
        "title": "Sales Information", 
        "desc": "Learn about our products",
        "rowId": "sales_info"
      },
      {
        "title": "General Questions",
        "desc": "Ask any general questions",
        "rowId": "general_qa"
      }
    ]
  }
}

// Send poll for group decisions
{
  "operation": "sendPoll",
  "phoneNumber": "[email protected]",
  "pollHeader": "Which feature should we prioritize?",
  "pollOptions": "AI Chat Enhancement,Voice Messages,File Sharing,Video Calls"
}

AI Tools Integration Examples

// Complete AI workflow with mentions and media
{
  "operation": "sendVideo",
  "phoneNumber": "5491155553934",
  "videoSource": "base64",
  "videoBase64": "data:video/mp4;base64,AAAAIGZ0eXBpc29tAAACAGlzb21pc...",
  "caption": "Here's your AI-generated tutorial video",
  "additionalOptions": {
    "id": "ai_tutorial_001",
    "mentions": {
      "mentionConfig": [{
        "type": "all"
      }]
    }
  }
}

// AI processing with binary data from previous nodes
{
  "operation": "sendDocument",
  "phoneNumber": "5491155553934",
  "documentSource": "binary",
  "documentBinaryProperty": "processed_report",
  "fileName": "AI_Analysis_Report.pdf",
  "caption": "Your personalized AI analysis is ready!"
}

// Get business profile information
{
  "operation": "businessProfile",
  "businessPhone": "5491155553934"
}

// Get privacy settings
{
  "operation": "privacySettings"
}

// Update push name
{
  "operation": "updatePushName",
  "pushName": "João Silva - Updated"
}

// Get current status
{
  "operation": "getMyStatus"
}

// Set new status
{
  "operation": "setMyStatus",
  "statusMessage": "Available for work! 🚀"
}

// AI Tools - Get business profile
{
  "operation": "getBusinessProfile",
  "businessPhoneNumber": "5491155553934"
}

// AI Tools - Get my status
{
  "operation": "getMyStatus"
}

Error Handling

All nodes include comprehensive error handling:

• Automatic Retries - Failed requests are retried with exponential backoff
• Continue on Fail - Option to continue workflow execution on errors
• Detailed Error Messages - Clear error descriptions for debugging
• HTTP Status Codes - Proper status code handling
• Authentication Errors - No retry on authentication failures

Compatibility

• n8n Version: Minimum n8n Version: While the node might work with earlier versions, it has been developed and tested primarily on n8n version 1.19.3.
• Node.js: 20.15 or higher
• DinastiAPI: Compatible with all DinastiAPI versions
• WhatsApp: Supports all current WhatsApp message types including interactive content
• Media Formats:
  • Images: JPEG, PNG, WebP
  • Videos: MP4, AVI, MOV (H.264 codec recommended)
  • Audio: OGG (Opus), MP3, WAV, AAC
  • Documents: PDF, DOCX, XLSX, TXT, and all file types
  • Stickers: WebP format (recommended), PNG with transparency

Resources

• n8n Community Nodes Documentation
• DinastiAPI Documentation
• DinastiAPI API Documentation
• WhatsApp Business API

Support

For issues and feature requests, please use the GitHub issues page.

License

MIT

Author

Guilherme Jansen - [email protected]

---

Made with ❤️ for the n8n community