zenpy 2.0.27

Python wrapper for the Zendesk API

Zenpy

Zenpy is a Python wrapper for the Zendesk, Chat and HelpCentre APIs. The goal of the project is to make it easy to write clean, fast, Pythonic code when interacting with Zendesk progmatically. The wrapper tries to keep API calls to a minimum. Wherever it makes sense objects are cached, and attributes of objects that would trigger an API call are evaluated lazily.

Zenpy supports both Python2 and Python3.

Please report bugs!

:warning: Beginning on August 15, 2023, Zendesk limits offset-based pagination (OBP) to 100 pages (10,000 results) and recommends using cursor-based pagination (CBP) for most API endpoints. Please refer to a corresponding block below and this issue to get more information.

• Quickstart
• Examples
  • Ticketing
    • Creating a ticket with a different requester
    • Commenting on a ticket
    • Adding a HTML comment to a ticket
    • Appending tags to a ticket
    • Uploading an attachment
    • Creating a ticket with a custom field set
    • Updating a custom field on a ticket
    • Applying a Macro to a ticket
  • Users
    • Adding a photo to a user
  • Help center
    • List all categories from help center
    • List all help center articles
    • List all help center articles in a section
    • Create new category in help center
    • Create new section in help center
    • Create new article in help center
  • Other
    • Working with webhooks
    • Pagination
• Documentation
• Contributions

Quickstart

from zenpy import Zenpy
from zenpy.lib.api_objects import Ticket
# Create a Zenpy instance
zenpy_client = Zenpy(**credentials)

# Create a new ticket
zenpy_client.tickets.create(Ticket(subject="Important", description="Thing"))

# Perform a simple search
for ticket in zenpy_client.search('PC LOAD LETTER', type='ticket', assignee='facetoe'):
    # No need to mess around with ids, linked objects can be accessed directly.
    print(ticket.requester.name)

    # All objects can be converted to a Python dict.
    print(ticket.to_dict())

    # Or to JSON.
    print(ticket.to_json())

Examples

Searching open and pending tickets for a specific user and sort them by descending

zenpy_client.search(type='ticket', status_less_than='closed', assignee='[e-mail]', sort_order='desc')

Searching only opened tickets

zenpy_client.search(type='ticket', status='open')

Exporting all tickets matching the query

By default, Search API has a limit of 1000 results in total. Search Export API allows exporting unlimited number of results, so if you'd like to export all results, use this method instead:

for ticket in zenpy_client.search_export(type='ticket', status='open'):
    print(ticket)

Read more about these limitations:

Search results limits

Search Export API release notes

Creating a ticket with a different requester

from zenpy.lib.api_objects import Ticket, User

zenpy_client.tickets.create(
    Ticket(description='Some description',
           requester=User(name='bob', email='[e-mail]'))
)

Commenting on a ticket

from zenpy.lib.api_objects import Comment

ticket = zenpy_client.tickets(id=some_ticket_id)
ticket.comment = Comment(body="Important private comment", public=False)
zenpy_client.tickets.update(ticket)

Adding a HTML comment to a ticket

from zenpy.lib.api_objects import Ticket, Comment

zenpy_client.tickets.create(Ticket(
    subject='Html comment example',
    comment=Comment(body='The smoke is very colorful',
                    html_body='<h2>The smoke is <i>very</i> colourful</h2>'))
)

Appending tags to a ticket

from zenpy.lib.api_objects import Ticket

ticket = zenpy_client.tickets(id=some_ticket_id)
ticket.tags.extend(['onetag', 'twotag', 'threetag', 'four'])
zenpy_client.tickets.update(ticket)

Uploading an attachment

from zenpy.lib.api_objects import Comment

# Upload the file (or file-like object) to Zendesk and obtain an Upload instance
upload_instance = zenpy_client.attachments.upload('/tmp/awesome_file.txt')

ticket = zenpy_client.tickets(id=some_ticket_id)
ticket.comment = Comment(body='This comment has my file attached', uploads=[upload_instance.token])
zenpy_client.tickets.update(ticket)

Creating a ticket with a custom field set

from zenpy.lib.api_objects import CustomField, Ticket

ticket_audit = zenpy_client.tickets.create(Ticket(
    subject='Has custom field',
    description="Wow, such field",
    custom_fields=[CustomField(id=43528467, value=1337)]
))

Updating a custom field on a ticket

from zenpy.lib.api_objects import CustomField
ticket = zenpy_client.tickets(id=some_ticket_id)
ticket.custom_fields.append(CustomField(id=43528467, value=1337))
zenpy_client.tickets.update(ticket)

Applying a Macro to a ticket

# Execute the show_macro_effect() method which returns what the macro *would* do.
# The method accepts either Zenpy objects or ids.
macro_result = zenpy_client.tickets.show_macro_effect(ticket_id_or_object, macro_id_or_object)

# Update the ticket to actually change the ticket.
zenpy_client.tickets.update(macro_result.ticket)

Adding a photo to a user

user = zenpy_client.users(id=user_id)
user.remote_photo_url = 'http://domain/example_photo.jpg'
zenpy_client.users.update(user)

List all categories from help center

categories = zenpy_client.help_center.categories()
for category in categories:
    pass

List all help center articles

articles = zenpy_client.help_center.articles(section=section)
for article in articles:
    pass

List all help center articles in a section

section = zenpy_client.help_center.categories.sections(category_id=category.id)
articles = zenpy_client.help_center.sections.articles(section=section)
for article in articles:
    pass

Create new category in help center

from zenpy import Zenpy
from zenpy.lib.api_objects.help_centre_objects import Category
new_category = zenpy_client.help_center.categories.create(
            Category(
                name="Category name",
                description="Category description",
                locale="en-us",
                created_at=datetime.now(),
                updated_at=datetime.now()
            )
        )
print(new_category.to_dict(serialize=True))

Create new section in help center

from zenpy import Zenpy
from zenpy.lib.api_objects.help_centre_objects import Section
new_section = zenpy_client.help_center.sections.create(
            Section(
                name="Section name",
                description="Section description",
                category_id=new_category.id,
                locale="en-us",
                created_at=datetime.now(),
                updated_at=datetime.now()
            )
        )
print(new_section.to_dict(serialize=True))

Create new article in help center

from zenpy import Zenpy
from zenpy.lib.api_objects.help_centre_objects import Article
new_article = zenpy_client.help_center.articles.create(
                    section=new_section.id,
                    article=Article(
                        name="Article Name",
                        body="<p>Article html content body</p>",
                        locale="en-us",
                        title="Article title",
                        section_id=new_section.id,
                        created_at=datetime.now(),
                        updated_at=datetime.now()
                    ),
                )
print(new_article.to_dict(serialize=True))

Working with webhooks

Show a webhook

webhook = zenpy_client.webhooks(id=WEBHOOK_ID) 

List webhooks

# Just list all the webhooks
for webhook in zenpy_client.webhooks.list():
    pass # Do something with it

# Filter the webhooks by a string in the name
for webhook in zenpy_client.webhooks.list(filter='some string'):
    pass # Do something with it

# Using sorting and pagination according to https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhooks/#list-webhooks
zenpy_client.webhooks.list(sort='name')
zenpy_client.webhooks.list(page_before=X, page_size=Y)
zenpy_client.webhooks.list(page_after=N, page_size=Y)

Creating a webhook that uses basic authentication

from zenpy.lib.api_objects import Webhook

new_webhook = Webhook(
    authentication={
        "add_position": "header",
        "data": {
            "password": "hello_123",
            "username": "john_smith"
        },
        "type": "basic_auth"
    },
    endpoint="https://example.com/status/200",
    http_method="GET",
    name="Example Webhook",
    description="Webhook description",
    request_format="json",
    status="active",
    subscriptions=["conditional_ticket_events"],
) 
zenpy_client.webhooks.create(new_webhook)

Creating a webhook that uses no authentication

new_webhook = Webhook(
    endpoint="https://example.com/status/200",
    http_method="GET",
    name="Example Webhook",
    description="Webhook description",
    request_format="json",
    status="active",
    subscriptions=["conditional_ticket_events"],
) 
zenpy_client.webhooks.create(new_webhook)

Creating a webhook that uses bearer token authentication

new_webhook = Webhook(
    authentication={
        "add_position": "header",
        "data": {
            "token": "{{token}}"
        },
        "type": "bearer_token"
    },
    # other fields
) 
zenpy_client.webhooks.create(new_webhook)

Updating a webhook

from zenpy.lib.api_objects import Webhook

webhook = zenpy_client.webhooks(id=WEBHOOK_ID) 

# Note: We need a brand new object because of API specific requirements for 'update'
# https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhooks/#update-webhook

new_webhook = Webhook(
                    name="New name",
                    request_format="json",
                    http_method="GET",
                    endpoint="https://example.com/status/200",
                    status="active",
                    authentication={
                      "add_position": "header",
                      "data": {
                          "password": "hello_123",     # As we can't get it back we need to pass it again from scratch
                          "username": "john_smith"
                      },
                      "type": "basic_auth"
                  },
)
response = zenpy_client.webhooks.update(webhook.id, new_webhook)

Partially updating (patching) a webhook

webhook = zenpy_client.webhooks(id=WEBHOOK_ID)
webhook.name = 'A new name'
response = zenpy_client.webhooks.patch(webhook)

Cloning a webhook

from zenpy.lib.api_objects import Webhook

an_existing_webhook = zenpy_client.webhooks(id=WEBHOOK_ID) 
new_webhook = zenpy_client.webhooks.clone(an_existing_webhook)

# Or just
new_webhook = zenpy_client.webhooks.clone(WEBHOOK_ID)

Working with secrets

secret = zenpy_client.webhooks.show_secret(webhook)
print(secret.secret)

secret = zenpy_client.webhooks.reset_secret(webhook)
print(secret.secret)

Testing webhooks

# Testing an existing webhook "as is""
response = zenpy_client.webhooks.test(webhook)

# Testing an existing webhook with modifications 
response = zenpy_client.webhooks.test(
                    webhook, 
                    request=dict(
                      endpoint='https://example.org/'
                    )
)

# Sending a test request without creating a webhook
response = zenpy_client.webhooks.test(
                    request=dict(
                        endpoint="https://example.org",
                        request_format="json",
                        http_method="GET",
                    )
                )

Pagination

Please refer to the official documentation to get details. Also check this article: Which endpoints are supported?

# An old style offset pagination, not recommended. Since August 15, 2023, is limited to 100 pages.
fields = zenpy_client.ticket_fields()
# Or
fields = zenpy_client.ticket_fields(cursor_pagination=False)

# A new cursor offset pagination
fields = zenpy_client.ticket_fields(cursor_pagination=True) # is equal to 100 results per page
# Or
fields = zenpy_client.ticket_fields(cursor_pagination=50) # 50 results per page

Documentation

Check out the documentation for more info.

Contributions

Contributions are very welcome. I've written an explanation of the core ideas of the wrapper in the Contributors Guide.