SparkBot icon

SparkBot

Interact with SparkBot WhatsApp API
Join our community

Actions148

Overview

This node interacts with the SparkBot WhatsApp API to retrieve contacts associated with a specific campaign. The "Get Campaign Contacts" operation allows users to fetch detailed contact information filtered by various criteria such as phone number, contact name, target group ID, delivery status, and more. This is useful for marketing teams or customer support agents who want to analyze or manage contacts involved in a WhatsApp campaign.

Common scenarios:

  • Retrieving all contacts targeted in a particular campaign to analyze engagement.
  • Filtering contacts by delivery or acknowledgment status to identify failed or pending messages.
  • Paginating through large sets of campaign contacts for reporting or exporting.
  • Searching contacts by phone number or group ID to quickly find specific recipients.

Practical example:
A marketing manager wants to see which contacts in a recent campaign have read the WhatsApp message. They can use this node to filter contacts by ACK status "Read" and get a paginated list sorted by most recent first.

Properties

Name Meaning
Campaign ID The unique identifier of the campaign whose contacts you want to retrieve. This is required.
Filters A collection of optional filters to narrow down the contacts returned:
- Search Search contacts by phone number, contact name, or target group ID.
- Target Filter contacts by their target identifiers, which can be phone numbers or WhatsApp group IDs. Multiple values allowed.
- Kind Filter by the type of target: either "Phone" or "Group". Multiple selections allowed.
- Status Filter contacts by delivery status. Options include "Pending", "Processing", "Delivered", and "Failed". Multiple selections allowed.
- ACK Status Filter contacts by delivery acknowledgment status. Options include "Pending", "Sent", "Delivered", "Read", and "Failed". Multiple selections allowed.
- WhatsApp Message IDs Filter contacts by one or more WhatsApp message IDs.
- Results Page Size Number of results to return per page. Defaults to 20.
- Page Number The page number to retrieve, starting from 0.
- Sort Sort order of the results by date. Options are "Recent First" (date descending) or "Oldest First" (date ascending). Defaults to "Recent First".

Output

The node outputs an array of JSON objects representing the campaign contacts matching the specified filters. Each object contains details about a contact within the campaign, including identifiers, delivery status, acknowledgment status, and other relevant metadata.

If binary data were involved (e.g., media files), it would be included in a separate binary property, but this operation focuses on contact data only.

Dependencies

  • Requires an active connection to the SparkBot WhatsApp API via an API key credential configured in n8n.
  • The node depends on the SparkBot API's campaigns endpoint to fetch campaign contact data.
  • Proper permissions and valid campaign IDs are necessary to access campaign contacts.

Troubleshooting

  • Common issues:

    • Invalid or missing Campaign ID will cause the operation to fail.
    • Incorrect API credentials or expired tokens will result in authentication errors.
    • Using filters that do not match any contacts will return empty results.
    • Pagination parameters out of range may cause no data to be returned.

  • Error messages:

    • "Campaign ID is required": Ensure the Campaign ID property is set.
    • "Authentication failed": Verify the API key credential is correct and has not expired.
    • "Resource not found" or "Invalid campaign ID": Confirm the campaign exists and the ID is accurate.
    • "Rate limit exceeded": Slow down request frequency or check API usage limits.

Links and References

Discussion