Z-API WhatsApp icon

Z-API WhatsApp

Custom operations

Actions17

Overview

This node enables interaction with the Z-API WhatsApp service to pin or unpin messages in a WhatsApp chat or group. It allows users to specify a message by its ID and either pin it for a specified duration or unpin it. This functionality is useful for highlighting important messages in conversations, such as announcements, reminders, or key information that should remain easily accessible.

Practical examples include:

  • Pinning a critical update message in a customer support group for 7 days.
  • Unpinning a previously pinned message after the relevant period has passed.
  • Automatically managing pinned messages based on workflow conditions.

Properties

Name Meaning
Instance The unique identifier of the Z-API instance to use for the request.
Token The API token required to authenticate requests to the Z-API service.
Client Token An additional client authentication token for secure access to the Z-API API.
Phone The phone number or group ID where the message resides (e.g., "5511999999999").
Message ID The unique identifier of the message to be pinned or unpinned.
Message Action The action to perform on the message: either "Pin" or "Unpin".
Pin Message Duration Duration for which the message should be pinned; options are "24 Hours", "7 Days", or "30 Days". Only applicable when pinning a message.

Output

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

No binary data output is produced by this node.

Example output structure (simplified):

{
  "status": "success",
  "message": "Message pinned successfully",
  "data": {
    "phone": "5511999999999",
    "messageId": "77DF5293EBC176FFA6A88838E7A6AD83",
    "action": "pin",
    "duration": "24_hours"
  }
}

Dependencies

  • Requires access to the Z-API WhatsApp service.
  • Needs valid credentials: an instance ID, an API token, and a client token from Z-API.
  • The node makes HTTP POST requests to the Z-API endpoint https://api.z-api.io/instances/{instance}/token/{token}/pin-message.
  • Proper configuration of these credentials within n8n is necessary for successful execution.

Troubleshooting

  • Common issues:

    • Invalid or expired tokens leading to authentication errors.
    • Incorrect instance ID or phone number causing resource not found errors.
    • Using "pin" action without specifying a valid pin duration.

  • Error messages and resolutions:

    • "The operation "pin-message" is not supported for resource "messages"!": Indicates a misconfiguration or unsupported operation; verify the selected resource and operation.
    • Authentication failures: Check that the instance ID, token, and client token are correct and active.
    • Network or connectivity errors: Ensure that the n8n server can reach the Z-API endpoints.
    • Validation errors related to message ID or phone number: Confirm that these values are accurate and correspond to existing messages and chats.

Links and References

Discussion