SparkBot icon

SparkBot

Interact with SparkBot WhatsApp API
Join our community

Actions148

Overview

The node provides integration with the SparkBot WhatsApp API, specifically enabling users to search outbound WhatsApp messages based on various filters. This operation is useful for retrieving message records that match specific criteria such as status, delivery state, message type, sender agent, target group or channel, and time ranges.

Common scenarios include:

  • Auditing sent messages by filtering for failed or pending messages.
  • Retrieving messages sent by a particular agent or device.
  • Searching messages containing certain text or linked to specific WhatsApp IDs.
  • Paginating through large sets of outbound messages sorted by creation or delivery date.

Practical example: A customer support team can use this node to fetch all messages delivered in the last week that contain a certain keyword, helping them analyze communication effectiveness.

Properties

Name Meaning
Filters Collection of filters to narrow down the search results. Includes the following options:
- Search Term Text content, phone number, group, or message IDs to search messages by.
- Status Filter messages by their current status. Options: Queued, Processing, Sent, Delivered, Read, Failed, Pending.
- Delivery Status Filter messages by delivery status. Options: Pending, Sent, Delivered, Read, Failed.
- Webhook Status Filter messages by webhook callback status. Options: Pending, Success, Failed.
- Include Expand subentity documents per message. Options: Device, Agent, Events.
- Message IDs Filter by specific message IDs (multiple values allowed).
- Agent IDs Filter messages sent by specific agent IDs (multiple values allowed).
- Source Origin of message creation. Options: API, Web Chat.
- Target Type Kind of chat target. Options: User, Group, Channel.
- Message Type Filter messages by type. Options: Text, Image, Video, Audio, Voice, Document, Location, Contact, Buttons, List, Template.
- WhatsApp IDs Filter by WhatsApp message IDs (multiple values allowed).
- Device IDs Filter by specific device IDs (multiple values allowed).
- Device Filter by device ID or phone number.
- Reference Filter by message reference (multiple values allowed).
- Priority Filter by message priority. Options: Low, Normal, High, Urgent.
- Phone Number Filter by target phone number in E.164 format.
- Group ID Filter by target group WhatsApp ID.
- Channel ID Filter by target channel WhatsApp ID.
- Delivery After Messages scheduled for delivery after this date/time.
- Delivery Before Messages scheduled for delivery before this date/time.
- Created After Messages created after this date/time.
- Created Before Messages created before this date/time.
- Sort Sort order for results. Options: Recent First (date descending), Oldest First (date ascending).
- Results Page Size Number of results per page (pagination size). Default is 20.
- Page Number Page number for pagination, starting from 0.

Output

The output is an array of JSON objects representing outbound messages matching the specified filters. Each object contains detailed information about a message, including its content, status, delivery details, associated device, agent, events (if included), and metadata such as timestamps and identifiers.

If the "Include" filter option is used, related sub-entities like device info, agent details, or event logs are expanded within each message object.

The node does not output binary data.

Dependencies

  • Requires an API key credential for authenticating with the SparkBot WhatsApp API.
  • The node depends on the SparkBot service being accessible and properly configured.
  • Some filter options load dynamic choices via methods (e.g., agents, devices, groups), which require appropriate API access permissions.

Troubleshooting

  • Common issues:

    • Invalid or missing API key will cause authentication failures.
    • Using invalid filter values (e.g., non-existent agent or device IDs) may return empty results or errors.
    • Pagination parameters out of range might result in no data returned.
    • Date/time filters must be valid ISO strings; incorrect formats may cause errors.

  • Error messages:

    • Authentication errors typically indicate problems with the API key credential.
    • Validation errors may occur if filter parameters are malformed or unsupported.
    • Network or connectivity errors suggest issues reaching the SparkBot API endpoint.

  • Resolutions:

    • Verify API key correctness and permissions.
    • Double-check filter values and formats.
    • Ensure network connectivity and API availability.
    • Use smaller page sizes or adjust pagination if large datasets cause timeouts.

Links and References

Discussion