{"id":17212405,"url":"https://github.com/facetoe/zenpy","last_synced_at":"2025-05-14T05:10:32.154Z","repository":{"id":27027947,"uuid":"30492678","full_name":"facetoe/zenpy","owner":"facetoe","description":"Python wrapper for the Zendesk API","archived":false,"fork":false,"pushed_at":"2025-04-27T05:00:59.000Z","size":6259,"stargazers_count":350,"open_issues_count":50,"forks_count":160,"subscribers_count":18,"default_branch":"master","last_synced_at":"2025-04-27T06:17:51.857Z","etag":null,"topics":["api","client","python","python-wrapper","wrapper","zendesk","zendesk-api"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facetoe.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["facetoe"]}},"created_at":"2015-02-08T14:01:02.000Z","updated_at":"2025-04-03T14:32:53.000Z","dependencies_parsed_at":"2023-01-14T05:50:25.632Z","dependency_job_id":"7b75811e-95e4-480f-832e-21baa45608cb","html_url":"https://github.com/facetoe/zenpy","commit_stats":{"total_commits":776,"total_committers":66,"mean_commits":"11.757575757575758","dds":"0.34536082474226804","last_synced_commit":"7bb3ff89f517ab77e80edfaed2486ad52839d699"},"previous_names":[],"tags_count":108,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facetoe%2Fzenpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facetoe%2Fzenpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facetoe%2Fzenpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facetoe%2Fzenpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facetoe","download_url":"https://codeload.github.com/facetoe/zenpy/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254076848,"owners_count":22010611,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","python","python-wrapper","wrapper","zendesk","zendesk-api"],"created_at":"2024-10-15T02:59:57.455Z","updated_at":"2025-05-14T05:10:32.131Z","avatar_url":"https://github.com/facetoe.png","language":"Python","readme":"[![Build Status](https://travis-ci.org/facetoe/zenpy.svg?branch=master)](https://travis-ci.org/facetoe/zenpy)\n\n# Zenpy\n\nZenpy 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.\n\nZenpy supports both Python2 and Python3.\n\nPlease report bugs!\n\n* [Quickstart](#quickstart)\n* [Examples](#examples)\n  * Ticketing\n    * [Creating a ticket with a different requester](#creating-a-ticket-with-a-different-requester)\n    * [Commenting on a ticket](#commenting-on-a-ticket)\n    * [Adding a HTML comment to a ticket](#adding-a-html-comment-to-a-ticket)\n    * [Appending tags to a ticket](#appending-tags-to-a-ticket)\n    * [Uploading an attachment](#uploading-an-attachment)\n    * [Creating a ticket with a custom field set](#creating-a-ticket-with-a-custom-field-set)\n    * [Updating a custom field on a ticket](#updating-a-custom-field-on-a-ticket)\n    * [Applying a Macro to a ticket](#applying-a-macro-to-a-ticket)\n  * Users\n    * [Adding a photo to a user](#adding-a-photo-to-a-user)\n  * Help center\n    * [List all categories from help center](#List-all-categories-from-help-center)\n    * [List all help center articles](#List-all-help-center-articles)\n    * [List all help center articles in a section](#List-all-help-center-articles-in-a-section)\n    * [Create new category in help center](#Create-new-category-in-help-center)\n    * [Create new section in help center](#Create-new-section-in-help-center)\n    * [Create new article in help center](#Create-new-article-in-help-center)\n  * Other\n    * [Working with webhooks](#Working-with-webhooks)\n    * [Pagination](#Pagination)\n* [Documentation](#documentation)\n* [Contributions](#contributions)\n\n## Quickstart\n\n```python\nfrom zenpy import Zenpy\nfrom zenpy.lib.api_objects import Ticket\n# Create a Zenpy instance\nzenpy_client = Zenpy(**credentials)\n\n# Create a new ticket\nzenpy_client.tickets.create(Ticket(subject=\"Important\", description=\"Thing\"))\n\n# Perform a simple search\nfor ticket in zenpy_client.search('PC LOAD LETTER', type='ticket', assignee='facetoe'):\n    # No need to mess around with ids, linked objects can be accessed directly.\n    print(ticket.requester.name)\n\n    # All objects can be converted to a Python dict.\n    print(ticket.to_dict())\n\n    # Or to JSON.\n    print(ticket.to_json())\n```\n\n## Examples\n\n##### Searching open and pending tickets for a specific user and sort them by descending\n\n```python\nzenpy_client.search(type='ticket', status_less_than='closed', assignee='foo@mail.foo', sort_order='desc')\n```\n\n##### Searching only opened tickets\n\n```python\nzenpy_client.search(type='ticket', status='open')\n```\n\n##### Exporting all tickets matching the query\n\nBy default, Search API has a limit of 1000 results in total.\nSearch Export API allows exporting unlimited number of results, so if you'd like to export all results, \nuse this method instead:\n\n```python\nfor ticket in zenpy_client.search_export(type='ticket', status='open'):\n    print(ticket)\n```\n\nRead more about these limitations:\n\n[Search results limits](https://developer.zendesk.com/api-reference/ticketing/ticket-management/search/#results-limit)\n\n[Search Export API release notes](https://support.zendesk.com/hc/en-us/articles/4408825120538-Support-API-Announcing-the-Export-Search-Results-endpoint-)\n\n##### Creating a ticket with a different requester\n\n```python\nfrom zenpy.lib.api_objects import Ticket, User\n\nzenpy_client.tickets.create(\n    Ticket(description='Some description',\n           requester=User(name='bob', email='bob@example.com'))\n)\n```\n\n##### Commenting on a ticket\n\n```python\nfrom zenpy.lib.api_objects import Comment\n\nticket = zenpy_client.tickets(id=some_ticket_id)\nticket.comment = Comment(body=\"Important private comment\", public=False)\nzenpy_client.tickets.update(ticket)\n```\n\n##### Adding a HTML comment to a ticket\n\n```python\nfrom zenpy.lib.api_objects import Ticket, Comment\n\nzenpy_client.tickets.create(Ticket(\n    subject='Html comment example',\n    comment=Comment(body='The smoke is very colorful',\n                    html_body='\u003ch2\u003eThe smoke is \u003ci\u003every\u003c/i\u003e colourful\u003c/h2\u003e'))\n)\n```\n\n##### Appending tags to a ticket\n\n```python\nfrom zenpy.lib.api_objects import Ticket\n\nticket = zenpy_client.tickets(id=some_ticket_id)\nticket.tags.extend(['onetag', 'twotag', 'threetag', 'four'])\nzenpy_client.tickets.update(ticket)\n```\n\n##### Uploading an attachment\n\n```python\nfrom zenpy.lib.api_objects import Comment\n\n# Upload the file (or file-like object) to Zendesk and obtain an Upload instance\nupload_instance = zenpy_client.attachments.upload('/tmp/awesome_file.txt')\n\nticket = zenpy_client.tickets(id=some_ticket_id)\nticket.comment = Comment(body='This comment has my file attached', uploads=[upload_instance.token])\nzenpy_client.tickets.update(ticket)\n```\n\n##### Creating a comment attachment and then redacting it\n\n```python\n# Upload the attachment\nupload_instance = zenpy_client.attachments.upload('/tmp/awesome_file.txt')\ncomment = Comment(body='Some comment')\n# Set the comment attachment affinity to this token.\ncomment.uploads = upload_instance.token\n\n# Create the ticket, with that comment with that attachment affinity.  Can just as easily be a new comment on existing ticket.\nticket = Ticket(subject='example ticket', comment=comment)\nticket_audit = zenpy_client.tickets.create(ticket)\nticket = ticket_audit.ticket\n\n# Get the last comment we just uploaded on that ticket.\nthe_commentresult = zenpy_client.tickets.comments(ticket)\n\n# Redact the comment now that we just associated it with an attachment.\nthe_comment = the_commentresult.values[0]  \nattachment =  zenpy_client.attachments.redact(ticket, the_comment, the_comment.attachments[0].id)\n\n# Barring no errors, the attachment is an Attachment object with the same id as was passed in!\n```\n\n##### Creating a ticket with a custom field set\n\n```python\nfrom zenpy.lib.api_objects import CustomField, Ticket\n\nticket_audit = zenpy_client.tickets.create(Ticket(\n    subject='Has custom field',\n    description=\"Wow, such field\",\n    custom_fields=[CustomField(id=43528467, value=1337)]\n))\n```\n\n##### Updating a custom field on a ticket\n\n```python\nfrom zenpy.lib.api_objects import CustomField\nticket = zenpy_client.tickets(id=some_ticket_id)\nticket.custom_fields.append(CustomField(id=43528467, value=1337))\nzenpy_client.tickets.update(ticket)\n```\n\n##### Applying a Macro to a ticket\n\n```python\n# Execute the show_macro_effect() method which returns what the macro *would* do.\n# The method accepts either Zenpy objects or ids.\nmacro_result = zenpy_client.tickets.show_macro_effect(ticket_id_or_object, macro_id_or_object)\n\n# Update the ticket to actually change the ticket.\nzenpy_client.tickets.update(macro_result.ticket)\n```\n\n##### Adding a photo to a user\n\n```python\nuser = zenpy_client.users(id=user_id)\nuser.remote_photo_url = 'http://domain/example_photo.jpg'\nzenpy_client.users.update(user)\n```\n\n##### List all categories from help center\n\n```python\ncategories = zenpy_client.help_center.categories()\nfor category in categories:\n    pass\n\n```\n\n##### List all help center articles\n\n```python\narticles = zenpy_client.help_center.articles(section=section)\nfor article in articles:\n    pass\n```\n\n##### List all help center articles in a section\n\n```python\nsection = zenpy_client.help_center.categories.sections(category_id=category.id)\narticles = zenpy_client.help_center.sections.articles(section=section)\nfor article in articles:\n    pass\n```\n\n##### Create new category in help center\n\n```python\nfrom zenpy import Zenpy\nfrom zenpy.lib.api_objects.help_centre_objects import Category\nnew_category = zenpy_client.help_center.categories.create(\n            Category(\n                name=\"Category name\",\n                description=\"Category description\",\n                locale=\"en-us\",\n                created_at=datetime.now(),\n                updated_at=datetime.now()\n            )\n        )\nprint(new_category.to_dict(serialize=True))\n```\n\n##### Create new section in help center\n\n```python\nfrom zenpy import Zenpy\nfrom zenpy.lib.api_objects.help_centre_objects import Section\nnew_section = zenpy_client.help_center.sections.create(\n            Section(\n                name=\"Section name\",\n                description=\"Section description\",\n                category_id=new_category.id,\n                locale=\"en-us\",\n                created_at=datetime.now(),\n                updated_at=datetime.now()\n            )\n        )\nprint(new_section.to_dict(serialize=True))\n```\n\n##### Create new article in help center\n\n```python\nfrom zenpy import Zenpy\nfrom zenpy.lib.api_objects.help_centre_objects import Article\nnew_article = zenpy_client.help_center.articles.create(\n                    section=new_section.id,\n                    article=Article(\n                        name=\"Article Name\",\n                        body=\"\u003cp\u003eArticle html content body\u003c/p\u003e\",\n                        locale=\"en-us\",\n                        title=\"Article title\",\n                        section_id=new_section.id,\n                        created_at=datetime.now(),\n                        updated_at=datetime.now()\n                    ),\n                )\nprint(new_article.to_dict(serialize=True))\n```\n\n##### Working with webhooks\n\n###### Show a webhook\n```python\nwebhook = zenpy_client.webhooks(id=WEBHOOK_ID) \n```\n\n###### List webhooks\n```python\n# Just list all the webhooks\nfor webhook in zenpy_client.webhooks.list():\n    pass # Do something with it\n\n# Filter the webhooks by a string in the name\nfor webhook in zenpy_client.webhooks.list(filter='some string'):\n    pass # Do something with it\n\n# Using sorting and pagination according to https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhooks/#list-webhooks\nzenpy_client.webhooks.list(sort='name')\nzenpy_client.webhooks.list(page_before=X, page_size=Y)\nzenpy_client.webhooks.list(page_after=N, page_size=Y)\n```\n\n###### Creating a webhook that uses basic authentication\n```python\nfrom zenpy.lib.api_objects import Webhook\n\nnew_webhook = Webhook(\n    authentication={\n        \"add_position\": \"header\",\n        \"data\": {\n            \"password\": \"hello_123\",\n            \"username\": \"john_smith\"\n        },\n        \"type\": \"basic_auth\"\n    },\n    endpoint=\"https://example.com/status/200\",\n    http_method=\"GET\",\n    name=\"Example Webhook\",\n    description=\"Webhook description\",\n    request_format=\"json\",\n    status=\"active\",\n    subscriptions=[\"conditional_ticket_events\"],\n) \nzenpy_client.webhooks.create(new_webhook)\n```\n\n###### Creating a webhook that uses no authentication\n```python\nnew_webhook = Webhook(\n    endpoint=\"https://example.com/status/200\",\n    http_method=\"GET\",\n    name=\"Example Webhook\",\n    description=\"Webhook description\",\n    request_format=\"json\",\n    status=\"active\",\n    subscriptions=[\"conditional_ticket_events\"],\n) \nzenpy_client.webhooks.create(new_webhook)\n```\n\n###### Creating a webhook that uses bearer token authentication\n```python\nnew_webhook = Webhook(\n    authentication={\n        \"add_position\": \"header\",\n        \"data\": {\n            \"token\": \"{{token}}\"\n        },\n        \"type\": \"bearer_token\"\n    },\n    # other fields\n) \nzenpy_client.webhooks.create(new_webhook)\n```\n\n###### Updating a webhook\n```python\nfrom zenpy.lib.api_objects import Webhook\n\nwebhook = zenpy_client.webhooks(id=WEBHOOK_ID) \n\n# Note: We need a brand new object because of API specific requirements for 'update'\n# https://developer.zendesk.com/api-reference/event-connectors/webhooks/webhooks/#update-webhook\n\nnew_webhook = Webhook(\n                    name=\"New name\",\n                    request_format=\"json\",\n                    http_method=\"GET\",\n                    endpoint=\"https://example.com/status/200\",\n                    status=\"active\",\n                    authentication={\n                      \"add_position\": \"header\",\n                      \"data\": {\n                          \"password\": \"hello_123\",     # As we can't get it back we need to pass it again from scratch\n                          \"username\": \"john_smith\"\n                      },\n                      \"type\": \"basic_auth\"\n                  },\n)\nresponse = zenpy_client.webhooks.update(webhook.id, new_webhook)\n```\n\n###### Partially updating (patching) a webhook\n```python\nwebhook = zenpy_client.webhooks(id=WEBHOOK_ID)\nwebhook.name = 'A new name'\nresponse = zenpy_client.webhooks.patch(webhook)\n```\n\n###### Cloning a webhook\n```python\nfrom zenpy.lib.api_objects import Webhook\n\nan_existing_webhook = zenpy_client.webhooks(id=WEBHOOK_ID) \nnew_webhook = zenpy_client.webhooks.clone(an_existing_webhook)\n\n# Or just\nnew_webhook = zenpy_client.webhooks.clone(WEBHOOK_ID)\n```\n\n###### Working with secrets\n```python\n\nsecret = zenpy_client.webhooks.show_secret(webhook)\nprint(secret.secret)\n\nsecret = zenpy_client.webhooks.reset_secret(webhook)\nprint(secret.secret)\n```\n\n###### Testing webhooks\n```python\n\n# Testing an existing webhook \"as is\"\"\nresponse = zenpy_client.webhooks.test(webhook)\n\n# Testing an existing webhook with modifications \nresponse = zenpy_client.webhooks.test(\n                    webhook, \n                    request=dict(\n                      endpoint='https://example.org/'\n                    )\n)\n\n# Sending a test request without creating a webhook\nresponse = zenpy_client.webhooks.test(\n                    request=dict(\n                        endpoint=\"https://example.org\",\n                        request_format=\"json\",\n                        http_method=\"GET\",\n                    )\n                )\n```\n\n###### Getting a webhook invocations\n\n[API documentation](https://developer.zendesk.com/api-reference/webhooks/webhooks-api/webhooks/#list-webhook-invocations)\n\n```python\nwh_filters = {\n    'filter[from_ts]': '2023-12-04T12:00:00Z',\n    'filter[to_ts]': '2023-12-04T16:00:00Z',\n    'filter[status]': 'success',\n}\n\nfor invocations in zenpy.webhooks.invocations(webhook_id, **wh_filters):\n    pass\n\n```\n\n##### Pagination\n\nPlease refer to the [official documentation](https://developer.zendesk.com/api-reference/introduction/pagination/) to get details. Also check this article: [Which endpoints are supported?](https://support.zendesk.com/hc/en-us/articles/4408846180634#h_01FF626TG8VD0W4JP9DBBSXESK)\n\n```python\n# An old style offset pagination, not recommended. Since August 15, 2023, is limited to 100 pages.\nfields = zenpy_client.ticket_fields()\n# Or\nfields = zenpy_client.ticket_fields(cursor_pagination=False)\n\n# A new cursor offset pagination\nfields = zenpy_client.ticket_fields(cursor_pagination=True) # is equal to 100 results per page\n# Or\nfields = zenpy_client.ticket_fields(cursor_pagination=50) # 50 results per page\n\n```\n\n## Documentation\n\nCheck out the [documentation](http://docs.facetoe.com.au/) for more info.\n\n### Contributions\nContributions are very welcome. I've written an explanation of the core ideas of the wrapper in the [Contributors Guide](https://github.com/facetoe/zenpy/wiki/Contributors-Guide).\n","funding_links":["https://github.com/sponsors/facetoe"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacetoe%2Fzenpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacetoe%2Fzenpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacetoe%2Fzenpy/lists"}