WSAPI Trigger icon

WSAPI Trigger

Trigger on WSAPI webhook events (messages, chats, calls, users, etc.)

Actions7

Overview

This node acts as a webhook trigger for WSAPI events, specifically designed to listen for various message-related events such as new messages, message reads, deletions, stars, and initial message history syncs. It is useful in scenarios where you want to automate workflows based on real-time messaging activity, for example:

  • Automatically processing or responding to incoming messages.
  • Tracking when messages are read or deleted.
  • Archiving starred messages.
  • Syncing message history during device pairing.

The node listens for selected message event types via a webhook and can optionally parse the event data for easier access or download media files automatically when messages contain media attachments.

Properties

Name Meaning
Message Events Select which message events to listen for. Options: Message, Message Read, Message Deleted, Message Starred, Message History Sync.
Auto-Download Media Boolean option to automatically download media files when message events contain media attachments.
Parse Event Data Boolean option to parse the eventData field based on event type for easier access to individual fields.
Include Raw Event Boolean option to include the original webhook payload in the output for full raw data inspection.
Webhook Authentication Enable custom header authentication for incoming webhooks to secure the trigger endpoint.
Auth Header Name The name of the HTTP header used for webhook authentication (required if authentication enabled).
Auth Header Value The expected value of the authentication header to validate incoming webhook requests (required if enabled).

Output

The node outputs JSON data representing the received event with the following structure:

  • instanceId: Identifier of the WSAPI instance.
  • receivedAt: Timestamp when the event was received.
  • eventType: Type of the event (e.g., "message", "message_read").
  • Parsed event data fields merged into the output if parsing is enabled.
  • Optionally includes the original raw webhook payload under rawEvent if requested.

If the event is a message containing media and auto-download is enabled, the node also outputs binary data representing the downloaded media file. This binary data includes:

  • The media content buffer.
  • Filename (extracted from response headers or generated).
  • MIME type of the media.

Additionally, metadata about the media download (timestamp and status) is added to the event data.

Dependencies

  • Requires an API key credential for WSAPI to download media files when auto-download is enabled.
  • The node makes authenticated HTTP GET requests to the WSAPI media download endpoint using this credential.
  • No other external dependencies are required.
  • If webhook authentication is enabled, users must configure the expected header name and value to secure the webhook.

Troubleshooting

  • Webhook Authentication Failure: If the webhook request does not include the correct authentication header or value, the node will ignore the request without triggering. Ensure the header name and value match exactly what is configured.
  • Missing Event Data: If the incoming webhook payload lacks eventType or eventData, the node will not trigger. Verify that the source system sends complete event data.
  • Unsupported Event Type: If the event type is not among the selected message events, the node ignores it. Confirm that the correct event types are selected in the node settings.
  • Media Download Failures: When auto-download is enabled, failures to download media (e.g., network issues, invalid credentials) will be recorded in the event data under a downloadError field. Check API credentials and network connectivity.
  • Binary Data Handling: Downstream nodes must support binary data to process downloaded media correctly.

Links and References

Discussion