WPPConnect Action

JIVAS action wrapper for WhatsApp API communications using the WPPConnect API with advanced mass messaging outbox. This action provides a wrapper for WhatsApp API communications using the WPPConnect API. As a core action, it simplifies and streamlines interactions with WhatsApp. The package is a singleton and requires the Jivas library version ^2.0.0.

Package Information

• Name: jivas/wppconnect_action
• Author: V75 Inc.
• Architype: WPPConnectAction

Meta Information

• Title: WPPConnect Action
• Group: core
• Type: action

Configuration

• Singleton: true

Dependencies

• Jivas: ~2.0.0-aplha.40
• PulseAction: ~0.0.2
• WPPConnect Server: ~2.8.5

---

How to Use

Below is detailed guidance on how to configure and use the WPPConnect Action.

Overview

The WPPConnect Action provides an abstraction layer for interacting with WhatsApp via the WPPConnect API. It supports multiple configurations for various use cases, including:

• Webhook registration for message handling.
• Message broadcasting to multiple recipients.
• Integration with WPPConnect for sending text, media, and location messages.

Dynamic Adaptation

The WPPConnect Action includes advanced mechanisms to optimize message delivery:

• Automatic Interval Adjustment: Dynamically modifies send intervals based on success rates to ensure efficient delivery.
• Variable Batch Sizes: Alternates batch sizes between defined minimum and maximum values for flexibility.
• Random Jitter: Introduces slight randomness to sending intervals to prevent detection of predictable patterns.

These features enhance reliability and minimize disruptions during high-volume messaging operations.

---

Configuration Structure

To use the WPPConnect Action, you need to set up the following configuration parameters. These specify connection and behavioral details.

Parameter	Type	Description	Default
api_url	string	WPPConnect Server URL (e.g., "https://your-wppconnect-server.com")	""
secret_key	string	WPPConnect Server Secret Key for authentication.	""
token	string	WPPConnect Server API Key for this session.	""
session	string	WPPConnect Server Instance ID.	""
base_url	string	JIVAS Base URL (your application's base URL).	""
webhook_url	string	JIVAS webhook endpoint for receiving WPPConnect messages.	""
request_timeout	float	Length of time (in seconds) this action waits for the API to complete a request.	10.0
chunk_length	int	Maximum length of message to send. Longer texts are split into subsequent messages.	1024
use_pushname	bool	Use the WhatsApp push name as the user name when set to True.	True
ignore_newsletters	bool	Ignore newsletter messages when set to True.	True
ignore_forwards	bool	Ignore forwarded messages when set to True.	True
outbox_base_rate_per_minute	int	Base messages per minute (adapts dynamically).	20
outbox_send_interval	float	Current operational delay between batches.	2.0
outbox_min_send_interval	float	Absolute minimum delay (seconds).	1.0
outbox_max_send_interval	float	Maximum allowed delay (seconds).	10.0
outbox_min_batch_size	int	Maximum messages per batch.	1
outbox_max_batch_size	int	Minimum messages per batch..	10

---

Notes on Configuration

• Parameter Settings: Ensure all parameters are configured based on your WPPConnect Server and JIVAS deployment requirements.
• Webhook URL: The webhook_url must be a publicly accessible endpoint to enable event-driven communication from WPPConnect.
• Outbox Base Rate: Set outbox_base_rate_per_minute to 20 for new numbers. This value should align with WhatsApp's acceptable rate-per-minute limits (default is 20).
• Auto Callback: This when sending or broadcasting messages in batches, this action will trigger your supplied callback upon completion.
• Batch Size Limits: For Tier 2 accounts, keep outbox_max_batch_size at or below 10 to comply with account limitations.
• Validation: Validate your API keys, tokens, and webhook URLs before deploying in production.
• Chunk Length: Adjust chunk_length if you have use cases that involve very long text messages.
• Message Filtering: Use ignore_newsletters and ignore_forwards to filter out less relevant messages and avoid unnecessary processing.

These guidelines help optimize performance and ensure compliance with WhatsApp's messaging policies.

---

API Endpoints

Broadcast Message

Endpoint: /action/walker Method: POST

Parameters

{
   "agent_id": "<AGENT_ID>",
   "walker": "broadcast_message",
   "module_root": "actions.jivas.wppconnect_action",
   "args": {
      "message": {
         "message_type": "TEXT|MEDIA|MULTI",
         ...
      },
      "ignore_list": ["session_id_1", ...]
   }
}

---

Send Messages

Endpoint: /action/walker Method: POST

Parameters

{
   "agent_id": "<AGENT_ID>",
   "walker": "send_messages",
   "module_root": "actions.jivas.wppconnect_action",
   "args": {
      "messages": [
         // Array of message objects
      ],
      "callback_url": "https://your-callback.url"
   }
}

Example Request

{
   "messages": [
      {
         "to": "session_id",
         "message": {
            "message_type": "TEXT",
            "content": "Batch message"
         }
      }
   ],
   "callback_url": "https://example.com/status"
}

Response

Returns a job ID string for tracking.

Callback Response

Your callback will receive a JSON payload with the following structure automatically upon job completion:

{
   "status": "success|partial|error",
   "job_id": "<UUID>",
   "processed_count": 10,
   "failed_count": 2,
   "pending_count": 0
}

---

Message Formats

TEXT

{
   "message": {
      "message_type": "TEXT",
      "content": "Hello World"
   }
}

MEDIA

{
   "message": {
      "message_type": "MEDIA",
      "mime": "image/jpeg",
      "content": "Check this!",
      "data": {
         "url": "https://example.com/image.jpg",
         "file_name": "image.jpg"
      }
   }
}

MULTI

{
   "message": {
      "message_type": "MULTI",
      "content": [
         // Array of TEXT/MEDIA messages
      ]
   }
}

---

🔰 Contributing

• 🐛 Report Issues: Submit bugs found or log feature requests for the wppconnect_action project.
• 💡 Submit Pull Requests: Review open PRs, and submit your own PRs.

Contributing Guidelines

1. Fork the Repository: Start by forking the project repository to your GitHub account.
2. Clone Locally: Clone the forked repository to your local machine using a git client.

   git clone https://github.com/TrueSelph/wppconnect_action
   

3. Create a New Branch: Always work on a new branch, giving it a descriptive name.

   git checkout -b new-feature-x
   

4. Make Your Changes: Develop and test your changes locally.
5. Commit Your Changes: Commit with a clear message describing your updates.

   git commit -m 'Implemented new feature x.'
   

6. Push to GitHub: Push the changes to your forked repository.

   git push origin new-feature-x
   

7. Submit a Pull Request: Create a PR against the original project repository. Clearly describe the changes and their motivations.
8. Review: Once your PR is reviewed and approved, it will be merged into the main branch. Congratulations on your contribution!

Contributor Graph

🎗 License

This project is protected under the Apache License 2.0. See LICENSE for more information.

0.0.11 → This Version

No information provided

All Changes

0.0.1

• Initialized package using jvcli

0.0.2

• N/A

0.0.3

• Enforce ENV VARS in action registration

0.0.4

• Major Refactor of WPPConnectAPI, WPPConnectAction and action app.

0.0.5

• Added behaviour to handle quoted messages as context in replies
• Updated action app, added refinements to make UI more usable

0.0.6

• Bugfix: incorrect parameter name
• Added ignore forwards setting to ignore forwarded messages by default
• Added a timeout setting for WppConnect API requests as a remedy to the sporadic lockout issue with the WPPConnect service

0.0.7

• Patched file_url_to_base64 to selectively apply prefix
• Updated Readme

0.0.8

• Patched wppconnect_api to allow messages sent via Agent whatsapp to be received as unprompted interactions

0.0.9

• Added outbox scheduler facility, broadcast_message and send_messages endpoints

0.0.10

• Set isForwarded to false by default in parse_inbound_message
• remove parent_message_id from handle_voicenote_message, handle_media_message and handle_location_message

0.0.11

• Fixed whatsapp group ID bug which prevents agent from responding, even when tagged, when group IDs are used instead of phone number
• Added syncing of Agent name to pushname
• Added syncing of Agent Avatar to profile pic
• Added device details when registered in action app
• Added action app 5 second auto-refresh when awaiting QRcode scan