Zalo OA Refresh Token icon

Zalo OA Refresh Token

Refresh Zalo OA access token and store it in database for reuse
Join our community

Overview

This node manages the access token lifecycle for a Zalo Official Account integration, specifically focusing on checking the status of the current access token or refreshing it if needed. It is useful in scenarios where workflows depend on valid authentication tokens to interact with Zalo's API, ensuring seamless and uninterrupted API calls.

A practical example: before making API requests to Zalo, you can use this node to verify if the access token is still valid or refresh it automatically. This avoids failures due to expired tokens and helps maintain continuous operation of integrations such as chatbots, messaging automation, or analytics fetching from Zalo Official Accounts.

Properties

Name Meaning
Return Access Token Whether to return the actual access token in the response (useful for webhook endpoints).

The node supports two operations internally (though only "Check Token Status" was requested):

  • Refresh Token: Refreshes the access token using the stored refresh token.
  • Check Token Status: Checks if the current access token is still valid without refreshing.

Output

The output JSON structure depends on the selected operation:

  • Check Token Status:

    {
  "is_valid": boolean,               // Whether the current access token is still valid
  "expires_at": string|null,         // ISO timestamp when the token expires, or null if unknown
  "hours_until_expiry": number,      // Number of hours until token expiry (rounded down)
  "should_refresh": boolean,         // Whether the token should be refreshed soon (less than 2 hours left)
  "check_executed_at": string,       // ISO timestamp when the check was performed
  "access_token": string|null        // The access token itself, included only if 'Return Access Token' is true
}

  • Refresh Token:

    {
  "success": true,
  "message": "Token refreshed successfully and saved to database",
  "access_token": string,            // New access token
  "refresh_token": string,           // New refresh token
  "expires_in": string,              // Expiry duration in seconds
  "expires_at": string,              // ISO timestamp when the token expires
  "db_save_success": boolean,        // Whether saving tokens to database succeeded
  "refresh_executed_at": string      // ISO timestamp when refresh was executed
}

If the node encounters errors and continueOnFail is enabled, it outputs an error object with details.

No binary data output is produced by this node.

Dependencies

  • Requires an API key credential for authenticating with Zalo's OAuth service.
  • Uses HTTP requests to Zalo's OAuth endpoint (https://oauth.zaloapp.com/v4/oa/access_token) to refresh tokens.
  • Optionally connects to a database via n8n's database connection to store and retrieve tokens persistently.
  • Reads and writes environment variables for token caching as fallback storage.
  • Uses n8n workflow static data as another caching layer.

Troubleshooting

  • Common Issues:

    • Failure to connect to the database may cause inability to persist tokens, leading to repeated refreshes.
    • Missing or invalid API credentials will cause token refresh failures.
    • Network timeouts or unreachable OAuth endpoint can interrupt token refresh.
    • Environment variables not set or accessible may prevent token caching.

  • Error Messages:

    • "Failed to execute operation 'Check Token Status': ..." indicates issues during token validation or retrieval.
    • "Failed to refresh token: ..." signals problems during the refresh request, possibly due to invalid refresh token or network issues.
    • "Database connection not available" means the node cannot save or read tokens from the database.
    • "All save methods failed:" means tokens could not be saved to any storage method (database, env vars, static data).

  • Resolutions:

    • Verify API credentials are correctly configured and valid.
    • Ensure database connection is properly set up and accessible.
    • Check network connectivity to Zalo OAuth endpoints.
    • Confirm environment variables permissions and presence if used.
    • Enable continueOnFail to allow workflow continuation despite token errors.

Links and References

Discussion