ZenPy: Python Wrapper for Zendesk API

Warnings

• breaking Zendesk is deprecating password authentication for API calls. ZenPy version 2.0.53 introduced warnings (or errors, configurable via `password_treatment_level`) when using passwords. Relying solely on email and password will eventually break your integration.
  Fix: Migrate to Zendesk API tokens or OAuth for authentication. Update your `Zenpy` initialization to use `token` or `oauth_token` instead of `password`.
• breaking Support for Python 3.5 was dropped in ZenPy version 2.0.49. Older Python environments using this version will experience compatibility issues.
  Fix: Upgrade your Python environment to Python 3.6 or newer.
• gotcha The ZenPy Chat API now exclusively uses Zendesk API v2, deprecating direct reliance on the `zopim` endpoint that was previously used. This change was implemented in version 2.0.54.
  Fix: Ensure your Chat API interactions are compatible with Zendesk Chat API v2 endpoints and the updated ZenPy `zenpy_client.chats` methods, rather than direct `zopim` references.
• gotcha Zendesk's bulk API operations typically have a limit (e.g., 100 objects per call). ZenPy does not automatically paginate or regulate this limit. Exceeding it can lead to `APIException` errors or silent truncation of your data by Zendesk.
  Fix: Manually chunk your bulk operations to stay within Zendesk's documented limits (e.g., 100 objects per call) and handle `APIException` for robust error management.
• gotcha ZenPy supports rate limiting controls but requires proper configuration to avoid HTTP 429 (Too Many Requests) errors. By default, it may sleep and retry, but this can cause long delays.
  Fix: Consider setting `raise_on_ratelimit=True` in the `Zenpy` constructor to handle `RateLimitError` exceptions programmatically, allowing you to implement custom retry logic (e.g., with backoff) or reschedule tasks. You can also configure `ratelimit_budget` or `proactive_ratelimit`.
• gotcha ZenPy's pagination via Python slices has limitations. It always pulls the first 100 objects by default for certain endpoints and does not support negative slicing or multiple accesses of the same slice reliably.
  Fix: Be aware of the default 100-object fetch when using slices. For extensive pagination, refer to the documentation on 'Cursor Based Generators' or 'Incremental Exports' which may offer more robust solutions.

Install

• pip install zenpy Install ZenPy

Imports

• Zenpy

  from zenpy import Zenpy

• Ticket

  from zenpy.lib.api_objects import Ticket

Quickstart

This quickstart demonstrates how to initialize the ZenPy client using API token authentication (recommended) and then create and retrieve a basic Zendesk ticket. Ensure `ZENDESK_EMAIL`, `ZENDESK_API_TOKEN`, and `ZENDESK_SUBDOMAIN` environment variables are set.

import os
from zenpy import Zenpy
from zenpy.lib.api_objects import Ticket

# Authenticate using environment variables (API Token is recommended)
creds = {
    'email': os.environ.get('ZENDESK_EMAIL', 'your_email@example.com'),
    'token': os.environ.get('ZENDESK_API_TOKEN', 'your_zendesk_api_token'),
    'subdomain': os.environ.get('ZENDESK_SUBDOMAIN', 'your_subdomain')
}

# Create a Zenpy instance
try:
    zenpy_client = Zenpy(**creds)
    print("Successfully connected to Zendesk.")

    # Create a new ticket
    new_ticket = zenpy_client.tickets.create(
        Ticket(
            subject="Urgent: Coffee Machine Broken!",
            description="The office coffee machine is completely out of order."
        )
    )
    print(f"Created ticket with ID: {new_ticket.id}")

    # Retrieve and print a ticket's subject
    retrieved_ticket = zenpy_client.tickets(id=new_ticket.id)
    print(f"Retrieved ticket subject: {retrieved_ticket.subject}")

except Exception as e:
    print(f"An error occurred: {e}")