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!
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())
zenpy_client.search(type='ticket', status_less_than='closed', assignee='foo@mail.foo', sort_order='desc')
zenpy_client.search(type='ticket', status='open')
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 Export API release notes
from zenpy.lib.api_objects import Ticket, User
zenpy_client.tickets.create(
Ticket(description='Some description',
requester=User(name='bob', email='bob@example.com'))
)
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)
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>'))
)
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)
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)
# Upload the attachment
upload_instance = zenpy_client.attachments.upload('/tmp/awesome_file.txt')
comment = Comment(body='Some comment')
# Set the comment attachment affinity to this token.
comment.uploads = upload_instance.token
# Create the ticket, with that comment with that attachment affinity. Can just as easily be a new comment on existing ticket.
ticket = Ticket(subject='example ticket', comment=comment)
ticket_audit = zenpy_client.tickets.create(ticket)
ticket = ticket_audit.ticket
# Get the last comment we just uploaded on that ticket.
the_commentresult = zenpy_client.tickets.comments(ticket)
# Redact the comment now that we just associated it with an attachment.
the_comment = the_commentresult.values[0]
attachment = zenpy_client.attachments.redact(ticket, the_comment, the_comment.attachments[0].id)
# Barring no errors, the attachment is an Attachment object with the same id as was passed in!
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)]
))
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)
# 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)
user = zenpy_client.users(id=user_id)
user.remote_photo_url = 'http://domain/example_photo.jpg'
zenpy_client.users.update(user)
categories = zenpy_client.help_center.categories()
for category in categories:
pass
articles = zenpy_client.help_center.articles(section=section)
for article in articles:
pass
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
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))
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))
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))
webhook = zenpy_client.webhooks(id=WEBHOOK_ID)
# 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)
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)
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)
new_webhook = Webhook(
authentication={
"add_position": "header",
"data": {
"token": "{{token}}"
},
"type": "bearer_token"
},
# other fields
)
zenpy_client.webhooks.create(new_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)
webhook = zenpy_client.webhooks(id=WEBHOOK_ID)
webhook.name = 'A new name'
response = zenpy_client.webhooks.patch(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)
secret = zenpy_client.webhooks.show_secret(webhook)
print(secret.secret)
secret = zenpy_client.webhooks.reset_secret(webhook)
print(secret.secret)
# 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",
)
)
wh_filters = {
'filter[from_ts]': '2023-12-04T12:00:00Z',
'filter[to_ts]': '2023-12-04T16:00:00Z',
'filter[status]': 'success',
}
for invocations in zenpy.webhooks.invocations(webhook_id, **wh_filters):
pass
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
Check out the documentation for more info.
Contributions are very welcome. I've written an explanation of the core ideas of the wrapper in the Contributors Guide.
FAQs
Python wrapper for the Zendesk API
We found that zenpy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.