Increase Genesys Cloud Data Action Timeout Beyond the Default Limit

What You Will Build

• This tutorial demonstrates how to programmatically increase the execution timeout for Genesys Cloud Data Actions using the PureCloud Platform Client SDK.
• It uses the Genesys Cloud CX API (/api/v2/process/actions) to modify the timeout property of an existing Data Action or define a new one with a custom timeout.
• The programming language covered is Python, utilizing the genesyscloud SDK.

Prerequisites

• OAuth Client Type: Service Account or Client Credentials Flow.
• Required Scopes:
  • process:action:read (to inspect current actions)
  • process:action:write (to update or create actions with new timeouts)
• SDK Version: genesyscloud Python SDK v2.3.0 or later.
• Language/Runtime: Python 3.8+.
• External Dependencies:
  • genesyscloud (install via pip install genesyscloud)
  • python-dotenv (for secure credential management)

Authentication Setup

Genesys Cloud uses OAuth 2.0 for API authentication. For server-side integrations involving Process Center (Data Actions), a Service Account is the standard approach. This ensures the token remains valid for long-running scripts and does not require user interaction.

Step 1: Configure Environment Variables

Create a .env file in your project root. Do not hardcode credentials in source code.

GENESYS_CLOUD_REGION=us-east-1
GENESYS_CLOUD_CLIENT_ID=your_client_id_here
GENESYS_CLOUD_CLIENT_SECRET=your_client_secret_here

Step 2: Initialize the SDK

The Genesys Cloud Python SDK handles token acquisition and refresh automatically. You must configure the region and credentials before making any API calls.

import os
from dotenv import load_dotenv
from genesyscloud import Configuration, ApiClient

# Load environment variables
load_dotenv()

def get_api_client() -> ApiClient:
    """
    Initializes and returns a configured Genesys Cloud ApiClient.
    Handles OAuth token acquisition via Client Credentials flow.
    """
    # Define the region. This determines the base URL for API calls.
    # Common regions: us-east-1, us-east-2, us-west-2, eu-west-1, ap-southeast-2
    region = os.getenv('GENESYS_CLOUD_REGION', 'us-east-1')
    
    # Initialize configuration
    config = Configuration()
    config.region = region
    
    # Set credentials
    config.client_id = os.getenv('GENESYS_CLOUD_CLIENT_ID')
    config.client_secret = os.getenv('GENESYS_CLOUD_CLIENT_SECRET')
    
    # Create the API client
    api_client = ApiClient(configuration=config)
    
    return api_client

# Initialize the client for subsequent steps
api_client = get_api_client()

Step 3: Verify Permissions

Before attempting to modify actions, verify that the service account has the correct scopes. A 403 Forbidden error typically indicates missing scopes or insufficient role permissions (e.g., “Process Builder” role).

def verify_scopes(api_client: ApiClient):
    """
    Checks if the current token has the required scopes for Process Actions.
    """
    from genesyscloud import AuthApi
    
    auth_api = AuthApi(api_client)
    
    try:
        # Retrieve the current token info
        token_info = auth_api.get_auth_tokeninfo()
        
        required_scopes = ['process:action:read', 'process:action:write']
        granted_scopes = token_info.scope.split(' ')
        
        missing_scopes = [s for s in required_scopes if s not in granted_scopes]
        
        if missing_scopes:
            print(f"ERROR: Missing required scopes: {missing_scopes}")
            print(f"Granted scopes: {granted_scopes}")
            raise PermissionError("Insufficient OAuth scopes")
        else:
            print("SUCCESS: All required scopes are present.")
            
    except Exception as e:
        print(f"Authentication verification failed: {e}")
        raise

verify_scopes(api_client)

Implementation

Step 1: Locate the Target Data Action

You cannot increase the timeout without identifying the specific Data Action ID. This step retrieves all Data Actions of type data to find the one causing the 3-second timeout issue.

API Endpoint: GET /api/v2/process/actions
SDK Class: ProcessApi

from genesyscloud import ProcessApi
from genesyscloud.process.rest import ApiException

def find_data_action_by_name(api_client: ApiClient, action_name: str) -> str | None:
    """
    Searches for a Data Action by name and returns its ID.
    
    Args:
        api_client: Initialized Genesys Cloud API client.
        action_name: The exact name of the Data Action.
        
    Returns:
        The ID of the action if found, otherwise None.
    """
    process_api = ProcessApi(api_client)
    
    try:
        # Query parameters
        # page_size: Maximum 2000 items per page
        # type: Filter for 'data' actions specifically
        response = process_api.get_process_actions(
            page_size=2000,
            type='data'
        )
        
        if not response.entities:
            print("No data actions found.")
            return None
            
        # Iterate through entities to find the match
        for action in response.entities:
            if action.name == action_name:
                print(f"Found Action: {action.name} (ID: {action.id})")
                print(f"Current Timeout: {action.timeout} ms")
                return action.id
                
        print(f"Action '{action_name}' not found.")
        return None
        
    except ApiException as e:
        print(f"Exception when calling ProcessApi->get_process_actions: {e}")
        if e.status == 401:
            print("Authentication failed. Check Client ID/Secret.")
        elif e.status == 403:
            print("Forbidden. Check OAuth scopes.")
        raise

# Example usage
# action_id = find_data_action_by_name(api_client, "My External API Call")

Step 2: Retrieve the Action Definition

To update the timeout, you must first fetch the current definition of the Data Action. This ensures you do not overwrite other properties (like the HTTP request body or headers) when you only intend to change the timeout.

API Endpoint: GET /api/v2/process/actions/{actionId}
OAuth Scope: process:action:read

def get_action_definition(api_client: ApiClient, action_id: str):
    """
    Retrieves the full definition of a specific Data Action.
    
    Args:
        api_client: Initialized Genesys Cloud API client.
        action_id: The ID of the Data Action.
        
    Returns:
        The ActionDefinition object.
    """
    process_api = ProcessApi(api_client)
    
    try:
        # Fetch the specific action
        response = process_api.get_process_action(action_id)
        
        # Validate that the action exists and is of type 'data'
        if not response or response.type != 'data':
            raise ValueError(f"Action ID {action_id} is not a valid Data Action.")
            
        return response
        
    except ApiException as e:
        print(f"Exception when calling ProcessApi->get_process_action: {e}")
        if e.status == 404:
            print(f"Action ID {action_id} not found.")
        raise

Step 3: Update the Timeout Value

The timeout property in the ActionDefinition object is an integer representing milliseconds. The default is often 3000 ms (3 seconds). To handle calls taking 5 seconds or more, set this value to at least 5000 ms, or higher (e.g., 10000 ms for 10 seconds) to provide a safety buffer.

Critical Constraint: The maximum timeout for a Data Action is 30000 ms (30 seconds). If your integration requires more than 30 seconds, you must use a different pattern (such as a webhook callback or asynchronous flow).

API Endpoint: PUT /api/v2/process/actions/{actionId}
OAuth Scope: process:action:write

def update_action_timeout(api_client: ApiClient, action_id: str, new_timeout_ms: int):
    """
    Updates the timeout property of a Data Action.
    
    Args:
        api_client: Initialized Genesys Cloud API client.
        action_id: The ID of the Data Action.
        new_timeout_ms: The new timeout value in milliseconds (max 30000).
    """
    process_api = ProcessApi(api_client)
    
    # Validate timeout range
    if new_timeout_ms < 1 or new_timeout_ms > 30000:
        raise ValueError("Timeout must be between 1 and 30000 milliseconds.")
        
    # Fetch current definition to preserve other properties
    current_action = get_action_definition(api_client, action_id)
    
    # Update the timeout property
    current_action.timeout = new_timeout_ms
    
    # Prepare the request body
    # The SDK expects the ActionDefinition object
    try:
        # Update the action
        # Note: The SDK handles serialization of the ActionDefinition object
        response = process_api.put_process_action(
            action_id=action_id,
            body=current_action
        )
        
        print(f"SUCCESS: Updated timeout for Action '{response.name}' to {response.timeout} ms.")
        
    except ApiException as e:
        print(f"Exception when calling ProcessApi->put_process_action: {e}")
        if e.status == 409:
            print("Conflict: The action version has changed. Retrieve the latest version and retry.")
        elif e.status == 400:
            print("Bad Request: Check the payload structure.")
        raise

Step 4: Handling Rate Limits (429 Too Many Requests)

Genesys Cloud APIs enforce rate limits. If you are updating many actions in a loop, you may encounter 429 errors. The SDK does not automatically retry all operations, so explicit retry logic is recommended for bulk updates.

import time

def update_action_with_retry(api_client: ApiClient, action_id: str, new_timeout_ms: int, max_retries: int = 3):
    """
    Updates the action timeout with exponential backoff for 429 errors.
    """
    for attempt in range(max_retries):
        try:
            update_action_timeout(api_client, action_id, new_timeout_ms)
            return True  # Success
        except ApiException as e:
            if e.status == 429:
                wait_time = 2 ** attempt  # Exponential backoff: 1s, 2s, 4s
                print(f"Rate limited (429). Retrying in {wait_time} seconds... (Attempt {attempt + 1}/{max_retries})")
                time.sleep(wait_time)
            else:
                raise  # Re-raise non-429 errors
                
    raise Exception("Max retries exceeded for rate limiting.")

Complete Working Example

The following script combines all steps into a single executable module. It authenticates, finds a specific Data Action by name, and updates its timeout to 10 seconds (10000 ms).

#!/usr/bin/env python3
"""
Genesys Cloud Data Action Timeout Updater

This script updates the timeout of a specified Data Action to handle
longer-running external API calls.

Prerequisites:
1. pip install genesyscloud python-dotenv
2. Create a .env file with GENESYS_CLOUD_REGION, GENESYS_CLOUD_CLIENT_ID, GENESYS_CLOUD_CLIENT_SECRET
"""

import os
import sys
import time
from dotenv import load_dotenv
from genesyscloud import Configuration, ApiClient, ProcessApi, AuthApi
from genesyscloud.process.rest import ApiException

# Load environment variables
load_dotenv()

def init_api_client() -> ApiClient:
    """Initializes the Genesys Cloud API Client."""
    config = Configuration()
    config.region = os.getenv('GENESYS_CLOUD_REGION', 'us-east-1')
    config.client_id = os.getenv('GENESYS_CLOUD_CLIENT_ID')
    config.client_secret = os.getenv('GENESYS_CLOUD_CLIENT_SECRET')
    
    if not config.client_id or not config.client_secret:
        raise EnvironmentError("Missing GENESYS_CLOUD_CLIENT_ID or GENESYS_CLOUD_CLIENT_SECRET in .env")
        
    return ApiClient(configuration=config)

def check_scopes(api_client: ApiClient):
    """Verifies the required OAuth scopes are present."""
    auth_api = AuthApi(api_client)
    try:
        token_info = auth_api.get_auth_tokeninfo()
        scopes = token_info.scope.split(' ')
        required = ['process:action:read', 'process:action:write']
        missing = [s for s in required if s not in scopes]
        if missing:
            raise PermissionError(f"Missing scopes: {missing}")
    except ApiException as e:
        raise RuntimeError(f"Scope verification failed: {e}")

def find_action_id(api_client: ApiClient, action_name: str) -> str:
    """Finds the ID of a Data Action by name."""
    process_api = ProcessApi(api_client)
    try:
        # Fetch data actions
        response = process_api.get_process_actions(page_size=2000, type='data')
        
        if not response.entities:
            raise ValueError("No data actions found.")
            
        for action in response.entities:
            if action.name == action_name:
                return action.id
                
        raise ValueError(f"Action named '{action_name}' not found.")
        
    except ApiException as e:
        raise RuntimeError(f"Failed to list actions: {e}")

def update_timeout(api_client: ApiClient, action_id: str, new_timeout_ms: int) -> bool:
    """Updates the timeout for a specific Data Action."""
    process_api = ProcessApi(api_client)
    
    if new_timeout_ms > 30000:
        raise ValueError("Maximum timeout is 30000 ms (30 seconds).")
        
    try:
        # 1. Get current definition
        current_action = process_api.get_process_action(action_id)
        
        # 2. Modify timeout
        current_action.timeout = new_timeout_ms
        
        # 3. Update the action
        # Note: We must pass the entire object, not just the timeout field
        updated_action = process_api.put_process_action(
            action_id=action_id,
            body=current_action
        )
        
        print(f"Successfully updated '{updated_action.name}' timeout to {updated_action.timeout} ms.")
        return True
        
    except ApiException as e:
        if e.status == 409:
            print("Version conflict detected. Please retry.")
        else:
            print(f"API Error: {e}")
        raise

def main():
    # Configuration
    ACTION_NAME = "My Long Running API Call"  # Replace with your action name
    NEW_TIMEOUT_MS = 10000  # 10 seconds
    
    print(f"Starting timeout update for action: {ACTION_NAME}")
    print(f"Target timeout: {NEW_TIMEOUT_MS} ms")
    
    try:
        # 1. Initialize Client
        api_client = init_api_client()
        
        # 2. Verify Scopes
        check_scopes(api_client)
        
        # 3. Find Action ID
        print("Searching for action...")
        action_id = find_action_id(api_client, ACTION_NAME)
        print(f"Found Action ID: {action_id}")
        
        # 4. Update Timeout
        print("Updating timeout...")
        update_timeout(api_client, action_id, NEW_TIMEOUT_MS)
        
    except Exception as e:
        print(f"Error: {e}")
        sys.exit(1)

if __name__ == "__main__":
    main()

Common Errors & Debugging

Error: 403 Forbidden

Cause: The OAuth token used does not have the process:action:write scope, or the Service Account does not have the “Process Builder” role assigned in the Genesys Cloud Admin Console.

Fix:

1. Go to Admin > Security > OAuth Clients.
2. Select your client.
3. Ensure process:action:write is checked under “Scopes”.
4. Go to Admin > Users.
5. Select the Service Account associated with the client.
6. Ensure the “Process Builder” role is assigned to the user.

Error: 409 Conflict

Cause: The version field in the ActionDefinition object is stale. Genesys Cloud uses optimistic locking. If another user modified the action after you fetched it, the update will fail.

Fix:
Implement a retry logic that re-fetches the action definition before updating, as shown in the update_action_with_retry example above. Alternatively, manually refresh the action in the Genesys Cloud UI and re-run the script.

Error: 400 Bad Request - “Timeout must be less than or equal to 30000”

Cause: You attempted to set a timeout higher than the maximum allowed limit (30 seconds) for a Data Action.

Fix:
Reduce the new_timeout_ms value to 30000 or lower. If your external API requires more than 30 seconds, you cannot use a synchronous Data Action. You must redesign the flow to use an asynchronous pattern:

1. The Data Action sends a request to your endpoint.
2. Your endpoint acknowledges immediately (200 OK).
3. Your backend processes the long-running task.
4. Your backend sends a callback to a Genesys Cloud Webhook or uses the Async API to update the conversation context.

Error: 429 Too Many Requests

Cause: You are making too many API calls in a short period. Genesys Cloud enforces rate limits per client ID.

Fix:
Implement exponential backoff. When a 429 is received, pause execution for 2^n seconds (where n is the attempt number) before retrying. Do not retry immediately.

Official References

• Genesys Cloud Process API Documentation
• ActionDefinition Schema
• Python SDK Reference
• OAuth Scopes Documentation