Actions17
Overview
This node enables sending a carousel message via WhatsApp using the Z-API service. A carousel message consists of multiple cards, each with text, an optional image, and optional buttons that users can interact with. This is useful for presenting multiple options or products in a visually appealing way within a chat.
Common scenarios include:
- E-commerce bots showcasing product catalogs.
- Customer support bots offering multiple service options.
- Marketing campaigns presenting various promotions or events.
For example, a business could send a carousel with cards representing different product categories, each card having buttons to reply, visit a URL, or call a phone number.
Properties
| Name | Meaning |
|---|---|
| Instance | Your Z-API instance ID used to identify your WhatsApp session. |
| Token | Your Z-API token for authenticating API requests. |
| Client Token | Your Z-API client token for additional authentication. |
| Phone | The recipient's phone number or group ID where the carousel message will be sent. |
| Message | The main text message accompanying the carousel. |
| Carousel Cards | Collection of carousel cards, each containing: |
| - Card Text | Text content displayed on the individual carousel card. |
| - Image URL | Optional URL of an image shown on the carousel card. |
| - Buttons | Optional buttons on the card; each button has: |
| Button ID | Unique identifier for the button. |
| Button Label | Text displayed on the button. |
| Button Type | Type of button: Reply, URL, or Call. |
| URL | (Required if type is URL) The link opened when the button is clicked. |
| Phone Number | (Required if type is Call) The phone number dialed when the button is clicked. |
Output
The node outputs a JSON array where each element corresponds to the response from the Z-API after sending the carousel message. The structure typically includes status information about the message delivery.
If the API supports it, the output may also contain metadata about the sent message, but no binary data is produced by this operation.
Dependencies
- Requires access to the Z-API WhatsApp service.
- Needs three credentials: an instance ID, a token, and a client token for authentication.
- The node makes HTTP POST requests to the Z-API endpoints.
- No additional environment variables are required beyond these credentials.
Troubleshooting
- Invalid Credentials: If the instance ID, token, or client token are incorrect or expired, the API will reject the request. Verify and update credentials as needed.
- Malformed Carousel Data: Ensure each carousel card has required fields like text and valid button configurations. Missing required button properties (e.g., URL for URL buttons) will cause errors.
- Network Issues: Connectivity problems can cause request failures. Check network access to
api.z-api.io. - Unsupported Operation: Using this node with operations other than "send-carousel" under the "messages" resource will throw an error.
- API Rate Limits: Excessive requests might be throttled by Z-API. Implement retries or backoff strategies if needed.
Links and References
- Z-API Official Documentation
- WhatsApp Business API Overview
- n8n HTTP Request Node Documentation (for understanding underlying HTTP calls)