Z-API WhatsApp icon

Z-API WhatsApp

Custom operations

Actions17

Overview

This node integrates with the Z-API WhatsApp service to perform various messaging-related operations. Specifically, the Add Label operation allows users to add a label (or tag) to a WhatsApp chat identified by a phone number or group ID. This is useful for organizing chats, categorizing conversations, or marking important contacts within WhatsApp.

Practical scenarios include:

  • Automatically tagging customer chats as "important" or "support" when they initiate contact.
  • Organizing group chats by adding relevant labels for easier filtering.
  • Managing marketing campaigns by labeling chats based on campaign tags.

Properties

Name Meaning
Instance Your Z-API instance ID, identifying your specific WhatsApp API instance.
Token Your Z-API token used for authenticating API requests.
Client Token Your Z-API client token, an additional authentication header required by the API.
Phone The phone number or group ID of the chat to which the label will be added.
Tag The label/tag name to add to the specified chat (e.g., "important", "support").

Output

The node outputs a JSON object representing the response from the Z-API server after attempting to add the label. This typically includes status information about the success or failure of the operation.

Example output structure (simplified):

{
  "success": true,
  "message": "Label added successfully",
  "data": {
    "phone": "601154272790",
    "tag": "important"
  }
}

No binary data is produced by this operation.

Dependencies

  • Requires access to the Z-API WhatsApp service.
  • Needs valid credentials: an instance ID, a token, and a client token for authentication.
  • The node makes HTTP PUT requests to the Z-API endpoint to add labels.
  • Ensure that the n8n workflow has internet access and the credentials are correctly configured.

Troubleshooting

  • Common issues:

    • Invalid or expired tokens may cause authentication failures.
    • Incorrect phone number or group ID format can lead to errors or no effect.
    • Network connectivity problems can prevent successful API calls.

  • Error messages:

    • "The operation "add-label" is not supported for resource "messages"!" — indicates a misconfiguration in the operation or resource selection.
    • Authentication errors usually return HTTP 401 or 403; verify tokens and permissions.
    • If the API returns an error, it will be included in the node's output; check the message for details.

  • Resolution tips:

    • Double-check all credential values and ensure they are current.
    • Verify the phone number/group ID format matches what Z-API expects.
    • Test connectivity to https://api.z-api.io from your environment.
    • Use the "Continue On Fail" option in n8n to handle errors gracefully during batch processing.

Links and References

Discussion