Z-API WhatsApp icon

Z-API WhatsApp

Custom operations

Actions17

Overview

This node integrates with the Z-API WhatsApp service to send various types of WhatsApp messages programmatically. Specifically, the Send Text With Buttons operation allows sending a text message accompanied by interactive buttons to a specified phone number or group ID. This is useful for creating engaging conversations where recipients can quickly respond by clicking buttons instead of typing.

Common scenarios include:

  • Customer support bots offering quick reply options.
  • Marketing campaigns prompting users to select product categories.
  • Surveys or polls where users choose from predefined answers.

For example, a business could send a message like "Which product are you interested in?" with buttons labeled "Washing Machine", "Refrigerator", and "Microwave" for easy user selection.

Properties

Name Meaning
Instance Your Z-API instance ID used to identify your WhatsApp API session.
Token Your Z-API token for authenticating API requests.
Client Token Your Z-API client token for additional authentication headers.
Phone The recipient's phone number or group ID to which the message will be sent.
Message The text content of the message that will appear above the buttons.
Buttons A collection of interactive buttons to include with the message. Each button has:
   Button ID Unique identifier for the button (used internally to track clicks).
   Button Label The visible text displayed on the button for the user to click.

Output

The node outputs a JSON object representing the response from the Z-API WhatsApp service after attempting to send the message with buttons. This typically includes status information about the message delivery, any error messages if applicable, and metadata returned by the API.

No binary data output is produced by this operation.

Example output structure (simplified):

{
  "status": "success",
  "messageId": "abc123",
  "details": { ... }
}

Dependencies

  • Requires an active Z-API WhatsApp account with valid Instance ID, Token, and Client Token credentials.
  • The node makes HTTP POST requests to the Z-API endpoints using these credentials.
  • No additional environment variables are needed beyond providing these credentials in the node parameters.

Troubleshooting

  • Invalid Credentials: If the instance ID, token, or client token are incorrect or expired, the API will reject requests. Verify and update credentials as needed.
  • Invalid Phone Number: Ensure the phone number or group ID is correctly formatted and registered on WhatsApp.
  • Empty or Malformed Buttons: Each button must have a unique ID and label. Missing or duplicate IDs may cause errors.
  • API Rate Limits: Sending too many messages in a short time may trigger rate limiting by Z-API.
  • Network Issues: Connectivity problems can cause request failures. Check network access and proxy settings if applicable.
  • Error Messages: The node throws errors if the operation is unsupported or parameters are missing. Review error details in the node execution logs.

Links and References

Discussion