PureCloud Platform API SDK

Common errors

• ModuleNotFoundError: No module named 'PureCloudPlatformClientV2.rest'

  cause This error typically occurs when the `purecloudplatformclientv2` package is not installed correctly, or there are environment-specific issues preventing Python from locating the submodules.
  fix Ensure the package is installed via `pip install PureCloudPlatformClientV2`. If on Windows, resolve potential maximum path length limitations before installation. Verify your Python environment and path are correctly configured.

• AttributeError: module 'PureCloudPlatformClientV2' has no attribute 'PostAnalyticsConversationsAggregatesQueryRequest'

  cause This indicates an attempt to access an API class or method that either does not exist, has been renamed, or is nested differently within the SDK than expected, often due to outdated documentation or an incorrect understanding of the SDK structure.
  fix Refer to the official SDK documentation or the `platform-client-sdk-python` GitHub repository to find the correct API class. For analytics queries, the correct class is typically `PureCloudPlatformClientV2.AnalyticsApi()`.

• ApiException: {'message': 'Invalid login credentials.' ...} or ApiException: 'This request requires a user context. Client credentials cannot be used for requests to this resource.'

  cause These `ApiException` errors are related to authentication. 'Invalid login credentials' means the client ID, client secret, or region configuration is incorrect. 'This request requires a user context' means you are attempting to use client credentials (app-level authentication) for an API endpoint that requires user-specific authorization (e.g., Implicit Grant, Authorization Code Grant, PKCE Grant).
  fix For 'Invalid login credentials', double-check your `GENESYS_CLOUD_CLIENT_ID`, `GENESYS_CLOUD_CLIENT_SECRET`, and `PureCloudPlatformClientV2.configuration.host` (region). For 'This request requires a user context', use an appropriate OAuth grant type that provides a user context (like Authorization Code Grant or PKCE) for the specific API endpoint.

• No such file or directory (during pip install PureCloudPlatformClientV2 on Windows)

  cause This error often occurs on Windows due to the default maximum path length limitation, which prevents `pip` from installing packages with deeply nested file structures, like `purecloudplatformclientv2`.
  fix On Windows, disable the maximum path length limitation. This can typically be done via a Group Policy setting or a registry edit (e.g., enabling 'Enable Win32 long paths' in Local Group Policy Editor under 'Computer Configuration > Administrative Templates > System > Filesystem'). After applying the change, restart your system if necessary and retry `pip install PureCloudPlatformClientV2`.

• ModuleNotFoundError: No module named 'purecloudplatformclientv2'

  cause The `purecloudplatformclientv2` library is not installed in the Python environment, or the script is being run in an environment different from where the library was installed.
  fix Install the library using pip: `pip install purecloudplatformclientv2`

Warnings

• breaking Preview APIs included in the SDK are subject to breaking and non-breaking changes at any time without notice. These resources are not stable.
  Fix: Avoid using Preview APIs in production environments or be prepared for frequent updates and code changes. Check the Genesys Cloud Developer Center for a list of preview APIs.
• breaking The SDK can have major version bumps due to changes in the underlying Platform API's Swagger definition, even if the API itself remains at major version 2. It is strongly recommended to keep the SDK updated to the latest version.
  Fix: Regularly update the SDK to the latest version. Review release notes for potential breaking changes that might require code modifications.
• gotcha On Windows, the maximum path length limitation can cause a 'No such file or directory' error during installation.
  Fix: Remove the maximum path length limitation on your Windows system as described in Microsoft documentation, or install the project in a shorter directory path.
• gotcha By default, Python's `None` values for model properties are stripped out before sending requests, meaning they won't be serialized as JSON `null`. To explicitly send a JSON `null` value, use `PureCloudPlatformClientV2.ApiNullValue()`.
  Fix: If an API endpoint requires sending a `null` value for a property (e.g., to reset it), assign `PureCloudPlatformClientV2.ApiNullValue()` to that property instead of `None`.
• gotcha The Client Credentials Grant is intended for non-human applications. Some API endpoints (e.g., Conversations API) require a user context and will not work with client credentials, resulting in a 'This request requires a user context' error.
  Fix: For endpoints requiring a user context, use user-based authorization grants like Authorization Code Grant, PKCE Grant, or Implicit Grant. These typically involve redirecting a user to the Genesys Cloud login page in a browser.
• gotcha By default, SDK logging does not include request and response bodies due to potential PII.
  Fix: To log request/response bodies for debugging, set `PureCloudPlatformClientV2.configuration.logger.log_request_body = True` and `PureCloudPlatformClientV2.configuration.logger.log_response_body = True`. Be mindful of PII in logs.
• gotcha If connecting to a Genesys Cloud environment other than `mypurecloud.com` (e.g., `mypurecloud.ie`), the base path must be explicitly set.
  Fix: Set `PureCloudPlatformClientV2.configuration.host = 'https://api.YOUR_REGION.pure.cloud'` before constructing any API classes, replacing `YOUR_REGION.pure.cloud` with your specific Genesys Cloud environment domain (e.g., `api.mypurecloud.ie`).
• breaking Authentication failed because the `client_id` or `client_secret` was missing or invalid, resulting in an `invalid_client` error (e.g., 'no client id provided' or 'invalid client credentials').
  Fix: Ensure that `GENESYS_CLOUD_CLIENT_ID` and `GENESYS_CLOUD_CLIENT_SECRET` environment variables are correctly set, or that `PureCloudPlatformClientV2.configuration.client_id` and `PureCloudPlatformClientV2.configuration.client_secret` are properly assigned before initializing the API client. Verify that the client ID and secret values are correct for your Genesys Cloud OAuth client.
• breaking Authentication requests resulting in 'invalid_client' or 'no client id provided' errors indicate that the client ID or client secret is missing or incorrect in the authentication configuration.
  Fix: Ensure that `GENESYS_CLOUD_CLIENT_ID` and `GENESYS_CLOUD_CLIENT_SECRET` environment variables (or corresponding configuration parameters) are correctly set with valid credentials for your Genesys Cloud OAuth client.

Install

• pip install PureCloudPlatformClientV2 Install latest version

Imports

• PureCloudPlatformClientV2

  import PureCloudPlatformClientV2

  This is the primary import for the entire SDK.
• ApiClient

  import PureCloudPlatformClientV2.api_client
  api_client = PureCloudPlatformClientV2.api_client.ApiClient()

  The ApiClient is essential for configuring the SDK and handling authentication.
• Configuration

  PureCloudPlatformClientV2.configuration

  Used to access global SDK configuration settings like access token, logging, and base path.
• AuthorizationApi

  auth_api = PureCloudPlatformClientV2.AuthorizationApi(api_client)

  Example of importing and instantiating a specific API class. Replace 'AuthorizationApi' with the desired API.
• YearMonth

  from PureCloudPlatformClientV2 import YearMonth

  Special class for handling 'year-month' formatted strings in API requests/responses.
• ApiNullValue

  from PureCloudPlatformClientV2 import ApiNullValue

  Used to explicitly send a JSON 'null' value for a property, as Python's 'None' is typically stripped.

Quickstart

This quickstart demonstrates how to authenticate using the Client Credentials Grant and fetch the current user's details. Ensure your `GENESYS_CLOUD_CLIENT_ID`, `GENESYS_CLOUD_CLIENT_SECRET`, and optionally `GENESYS_CLOUD_REGION` are set as environment variables. This grant type is suitable for non-human applications or services.

import PureCloudPlatformClientV2
import os

# Configure API client with Client Credentials Grant
# Ensure GENESYS_CLOUD_CLIENT_ID and GENESYS_CLOUD_CLIENT_SECRET are set as environment variables
CLIENT_ID = os.environ.get('GENESYS_CLOUD_CLIENT_ID', '')
CLIENT_SECRET = os.environ.get('GENESYS_CLOUD_CLIENT_SECRET', '')
GENESYS_CLOUD_REGION = os.environ.get('GENESYS_CLOUD_REGION', 'mypurecloud.com') # e.g., mypurecloud.ie

# Set the Genesys Cloud region (e.g., 'mypurecloud.ie', 'mypurecloud.com.au')
# Default is mypurecloud.com
PureCloudPlatformClientV2.configuration.host = f'https://api.{GENESYS_CLOUD_REGION}'

api_client = PureCloudPlatformClientV2.api_client.ApiClient()

try:
    # Authenticate using client credentials
    api_client.get_client_credentials_token(CLIENT_ID, CLIENT_SECRET)
    print("Authentication successful!")

    # Instantiate an API class (e.g., UsersApi)
    users_api = PureCloudPlatformClientV2.UsersApi(api_client)

    # Make an API call (e.g., get the authenticated user's information)
    me = users_api.get_users_me()
    print(f"Authenticated user: {me.name} (ID: {me.id})")

except PureCloudPlatformClientV2.rest.ApiException as e:
    print(f"Exception when calling Genesys Cloud API: {e}")
    print(f"Ensure GENESYS_CLOUD_CLIENT_ID and GENESYS_CLOUD_CLIENT_SECRET are set correctly and have the necessary permissions.")
except Exception as e:
    print(f"An unexpected error occurred: {e}")