{"id":18656557,"url":"https://github.com/zendesk/zendesk_api_client_rb","last_synced_at":"2025-05-13T21:04:39.940Z","repository":{"id":2052201,"uuid":"2989987","full_name":"zendesk/zendesk_api_client_rb","owner":"zendesk","description":"Official Ruby Zendesk API Client","archived":false,"fork":false,"pushed_at":"2025-04-18T15:08:15.000Z","size":6195,"stargazers_count":389,"open_issues_count":26,"forks_count":185,"subscribers_count":430,"default_branch":"master","last_synced_at":"2025-04-28T12:07:45.188Z","etag":null,"topics":["ruby","zendesk"],"latest_commit_sha":null,"homepage":"http://developer.zendesk.com/","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zendesk.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-12-15T19:28:23.000Z","updated_at":"2025-04-14T21:06:25.000Z","dependencies_parsed_at":"2024-01-15T23:55:57.048Z","dependency_job_id":"50598db6-3ec7-49b4-9fa5-4a8787faaf6b","html_url":"https://github.com/zendesk/zendesk_api_client_rb","commit_stats":{"total_commits":1296,"total_committers":96,"mean_commits":13.5,"dds":0.3966049382716049,"last_synced_commit":"1ab8e86933624f3d691b7249c72a973fca387fde"},"previous_names":[],"tags_count":164,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_rb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_rb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_rb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zendesk%2Fzendesk_api_client_rb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zendesk","download_url":"https://codeload.github.com/zendesk/zendesk_api_client_rb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251311330,"owners_count":21569009,"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":["ruby","zendesk"],"created_at":"2024-11-07T07:23:58.019Z","updated_at":"2025-04-28T12:07:51.025Z","avatar_url":"https://github.com/zendesk.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zendesk API Client\n\n[![Test](https://github.com/zendesk/zendesk_api_client_rb/workflows/Test/badge.svg)](https://github.com/zendesk/zendesk_api_client_rb/actions/workflows/main.yml?query=branch%3Amaster)\n[![Gem Version](https://badge.fury.io/rb/zendesk_api.svg)](https://badge.fury.io/rb/zendesk_api)\n[![Code Climate](https://codeclimate.com/github/zendesk/zendesk_api_client_rb.svg)](https://codeclimate.com/github/zendesk/zendesk_api_client_rb)\n\n## Documentation\n\nThis Ruby gem is a generic wrapper around Zendesk's REST API. Follow this README and the [wiki](https://github.com/zendesk/zendesk_api_client_rb/wiki) for how to use it.\n\nYou can interact with all the resources defined in [`resources.rb`](lib/zendesk_api/resources.rb). Basically we have some cleaver code to convert Ruby objects into HTTP requests.\n\nPlease refer to our [API documentation](https://developer.zendesk.com/api-reference) for the specific endpoints and once you understand the mapping between Ruby and the HTTP endpoints you should be able to call any endpoint.\n\nThe Yard generated documentation is available in at [RubyDoc](https://www.rubydoc.info/gems/zendesk_api).\n\nPlease report any bug in the [Github issues page](https://github.com/zendesk/zendesk_api_client_rb/issues).\n\nYou might want to try out this gem in a REPL for exploring your options, if so, check out [this project](https://github.com/zendesk/zendesk_api_client_rb_repl).\n\n## Product Support\n\nThis Ruby gem supports the REST API's for Zendesk Support, Zendesk Guide,\nand Zendesk Talk. It does not yet support other Zendesk products such as\nZendesk Chat, Zendesk Explore, and Zendesk Sell.\n\n## Installation\n\nThe Zendesk API client can be installed using Rubygems or Bundler.\n\n### Rubygems\n\n```sh\ngem install zendesk_api\n```\n\n### Bundler\n\nAdd it to your Gemfile\n\n```\ngem \"zendesk_api\"\n```\n\nThen `bundle` as usual.\n\n## Configuration\n\nConfiguration is done through a block returning an instance of `ZendeskAPI::Client`.\n\n```ruby\nrequire 'zendesk_api'\n\nclient = ZendeskAPI::Client.new do |config|\n  # Mandatory:\n\n  config.url = \"\u003c- your-zendesk-url -\u003e\" # e.g. https://yoursubdomain.zendesk.com/api/v2\n\n  # Basic / Token Authentication\n  config.username = \"login.email@zendesk.com\"\n\n  # Choose one of the following depending on your authentication choice\n  # More information on obtaining API tokens can be found here:\n  # https://developer.zendesk.com/api-reference/introduction/security-and-auth/#api-token\n  config.token = \"your zendesk token\"\n\n  # OAuth Authentication\n  # More information on obtaining OAuth access tokens can be found here:\n  # https://developer.zendesk.com/api-reference/introduction/security-and-auth/#oauth-access-token\n  config.access_token = \"your OAuth access token\"\n\n  # Optional:\n\n  # Retry uses middleware to notify the user\n  # when hitting the rate limit, sleep automatically,\n  # then retry the request.\n  config.retry = true\n\n  # Raise error when hitting the rate limit.\n  # This is ignored and always set to false when `retry` is enabled.\n  # Disabled by default.\n  config.raise_error_when_rate_limited = false\n\n  # Logger prints to STDERR by default, to e.g. print to stdout:\n  require 'logger'\n  config.logger = Logger.new(STDOUT)\n\n  # Disable resource cache (this is enabled by default)\n  config.use_resource_cache = false\n\n  # Changes Faraday adapter\n  # config.adapter = :patron\n\n  # Merged with the default client options hash\n  # config.client_options = {:ssl =\u003e {:verify =\u003e false}, :request =\u003e {:timeout =\u003e 30}}\n\n  # When getting the error 'hostname does not match the server certificate'\n  # use the API at https://yoursubdomain.zendesk.com/api/v2\n\n  # Change retry configuration (this is disabled by default)\n  config.retry_on_exception = true\n\n  # Error codes when the request will be automatically retried. Defaults to 429, 503\n  config.retry_codes = [ 429 ]\nend\n```\n\n## Usage\n\nThe result of configuration is an instance of `ZendeskAPI::Client` which can then be used in two different methods.\n\nOne way to use the client is to pass it in as an argument to individual classes.\n\n_Note_: all method calls ending in `!` will raise an exception when an error occurs, see the [wiki page](https://github.com/zendesk/zendesk_api_client_rb/wiki/Errors) for more info.\n\n```ruby\nZendeskAPI::Ticket.new(client, :id =\u003e 1, :priority =\u003e \"urgent\") # doesn't actually send a request, must explicitly call #save!\n\nZendeskAPI::Ticket.create!(client, :subject =\u003e \"Test Ticket\", :comment =\u003e { :value =\u003e \"This is a test\" }, :submitter_id =\u003e client.current_user.id, :priority =\u003e \"urgent\")\nZendeskAPI::Ticket.find!(client, :id =\u003e 1)\nZendeskAPI::Ticket.destroy!(client, :id =\u003e 1)\n```\n\nYou can also update ticket objects.\n\n```ruby\nticket = ZendeskAPI::Ticket.find!(client, :id =\u003e 1)\nticket.update(:comment =\u003e { :value =\u003e \"This is a test reply.\" })\n\nticket.save!\n```\n\nAnother way is to use the instance methods under client.\n\n```ruby\nclient.tickets.first\nclient.tickets.find!(:id =\u003e 1)\nclient.tickets.build(:subject =\u003e \"Test Ticket\")\nclient.tickets.create!(:subject =\u003e \"Test Ticket\", :comment =\u003e { :value =\u003e \"This is a test\" }, :submitter_id =\u003e client.current_user.id, :priority =\u003e \"urgent\")\nclient.tickets.destroy!(:id =\u003e 1)\n```\n\nThe methods under `ZendeskAPI::Client` (such as `.tickets`) return an instance of `ZendeskAPI::Collection`, a lazy-loaded list of that resource.\nActual requests may not be sent until an explicit `ZendeskAPI::Collection#fetch!`, `ZendeskAPI::Collection#to_a!`, or an applicable methods such\nas `#each`.\n\n### Caveats\n\nResource updating is implemented by sending only the `changed?` attributes to the server (see `ZendeskAPI::TrackChanges`).\nUnfortunately, this module only hooks into `Hash` meaning any changes to an `Array` not resulting in a new instance will not be tracked and sent.\n\n```\nzendesk_api_client_rb $ bundle console\n\u003e a = ZendeskAPI::Trackie.new(:test =\u003e []).tap(\u0026:clear_changes)\n\u003e a.changed?(:test)\n =\u003e false\n\u003e a.test \u003c\u003c \"hello\"\n =\u003e [\"hello\"]\n\u003e a.changed?(:test)\n =\u003e false\n\u003e a.test += %w{hi}\n =\u003e [\"hello\", \"hi\"]\n\u003e a.changed?(:test)\n =\u003e true\n```\n\n### Pagination\n\n`ZendeskAPI::Collections` can be paginated:\n\n```ruby\n# Note that CBP (cursor based pagination) is the default and preferred way\n# and has fewer limitations on deep pagination\ntickets = client.tickets.per_page(3)\npage1 = tickets.fetch! # GET /api/v2/tickets?page[after]={cursor}\u0026page[size]=3\npage2 = tickets.next # GET /api/v2/tickets?page[after]={cursor}\u0026page[size]=3\n# ...\n\n# OR...\n# Note that OBP (offset based pagination) can incur to various limitations\ntickets = client.tickets.page(2).per_page(3)\n\nnext_page = tickets.next # =\u003e 3\ntickets.fetch! # GET /api/v2/tickets?page=3\u0026per_page=3\nprevious_page = tickets.prev # =\u003e 2\ntickets.fetch! # GET /api/v2/tickets?page=2\u0026per_page=3\n```\n\nIteration over all resources and pages is handled by `Collection#all`:\n\n```ruby\nclient.tickets.all! do |resource|\n  # every resource, from all pages, will be yielded to this block\nend\n```\n\nIf given a block with two arguments, the page number is also passed in.\n\n```ruby\nclient.tickets.all! do |resource, page_number|\n  # all resources will be yielded along with the page number\nend\n```\n\n### Cursor Based Pagination\n\nA few endpoints related to organizations, tickets, triggers and groups will now make use of cursor based pagination by default.\nIt is also recommended to use CBP whenever [the Zendesk developer documentation](https://developer.zendesk.com/api-reference) says it's supported.\nPass `page[size]=number` in the parameters to attempt a CBP request, like the example below:\n\n```ruby\nclient.connection.get('/api/v2/suspended_tickets', page: { size: 100 }).body\n{\"suspended_tickets\"=\u003e[...], \"meta\"=\u003e{\"has_more\"=\u003etrue, \"after_cursor\"=\u003e\" ... \", \"before_cursor\"=\u003enil}, \"links\"=\u003e{\"prev\"=\u003enil, \"next\"=\u003e\"...\"}}\n```\n\n### Callbacks\n\nCallbacks can be added to the `ZendeskAPI::Client` instance and will be called (with the response env) after all response middleware on a successful request.\n\n```ruby\nclient.insert_callback do |env|\n  puts env[:response_headers]\nend\n```\n\n### Resource management\n\nIndividual resources can be created, modified, saved, and destroyed.\n\n```ruby\nticket = client.tickets[0] # ZendeskAPI::Ticket.find(client, :id =\u003e 1)\nticket.priority = \"urgent\"\nticket.attributes # =\u003e { \"priority\" =\u003e \"urgent\" }\nticket.save! # Will PUT =\u003e true\nticket.destroy! # =\u003e true\n\nZendeskAPI::Ticket.new(client, { priority: \"urgent\" })\nticket.new_record? # =\u003e true\nticket.save! # Will POST\n```\n\n### Side-loading\n\nTo facilitate a smaller number of requests and easier manipulation of associated data we allow \"side-loading,\" or inclusion, of selected resources.\n\nFor example:\nA `ZendeskAPI::Ticket` is associated with `ZendeskAPI::User` through the `requester_id` field.\nAPI requests for that ticket return a structure similar to this:\n\n```json\n\"ticket\": {\n  \"id\": 1,\n  \"url\": \"http.....\",\n  \"requester_id\": 7,\n  ...\n}\n```\n\nCalling `ZendeskAPI::Ticket#requester` automatically fetches and loads the user referenced above (`/api/v2/users/7`).\nUsing side-loading, however, the user can be partially loaded in the same request as the ticket.\n\n```ruby\ntickets = client.tickets.include(:users)\n# Or client.tickets(:include =\u003e :users)\n# Does *NOT* make a request to the server since it is already loaded\ntickets.first.requester # =\u003e #\u003cZendeskAPI::User id=...\u003e\n\n# OR\n\nticket = client.tickets.find!(:id =\u003e 1, :include =\u003e :users)\nticket.requester # =\u003e #\u003cZendeskAPI::User id=...\u003e\n```\n\nCurrently, this feature is limited to only a few resources and their associations.\nThey are documented on [developer.zendesk.com](https://developer.zendesk.com/rest_api/docs/support/side_loading#supported-endpoints).\n\n#### Recommended Approach\n\nFor better control over your data and to avoid large response sizes, consider fetching related resources explicitly. This approach can help you manage data loading more precisely and can lead to optimized performance for complex applications.\n\n```ruby\nticket = ZendeskAPI::Ticket.find(id: 1)\nrequester = ZendeskAPI::User.find(id: ticket.requester_id)\n```\n\nBy explicitly fetching associated resources, you can ensure that your application only processes the data it needs, improving overall efficiency.\n\n### Omnichannel\n\nSupport for the [Agent Availability API](https://developer.zendesk.com/api-reference/agent-availability/agent-availability-api/introduction/)\n\nAn agent’s availability includes their state (such as online) for each channel (such as messaging), and their unified state across channels. It also includes the work items assigned to them.\n\n```ruby\n# All agent availabilities\nclient.agent_availabilities.fetch\n\n# fetch availability for one agent, their channels and work items\nagent_availability = ZendeskAPI::AgentAvailability.find(client, 386390041152)\nagent_availability.channels\nagent_availability.channels.first.work_items\n\n# Using the agent availability filter\nZendeskAPI::AgentAvailability.search(client, { select_channel: 'support' })\nZendeskAPI::AgentAvailability.search(client, { channel_status: 'support:online' })\n```\n\n### Search\n\nSearching is done through the client. Returned is an instance of `ZendeskAPI::Collection`:\n\n```ruby\nclient.search(:query =\u003e \"my search query\") # /api/v2/search.json?query=...\nclient.users.search(:query =\u003e \"my new query\")  # /api/v2/users/search.json?query=...\n```\n\n### Special case: Custom resources paths\n\nAPI endpoints such as `tickets/recent` or `topics/show_many` can be accessed through chaining.\nThey will too return an instance of `ZendeskAPI::Collection`.\n\n```ruby\nclient.tickets.recent\nclient.topics.show_many(:verb =\u003e :post, :ids =\u003e [1, 2, 3])\n```\n\n### Special Case: Current user\n\nUse either of the following to obtain the current user instance:\n\n```ruby\nclient.users.find!(:id =\u003e 'me')\nclient.current_user\n```\n\n### Special Case: Importing a ticket\n\nBulk importing tickets allows you to move large amounts of data into Zendesk.\n\n```ruby\nticket = ZendeskAPI::Ticket.import(client, :subject =\u003e \"Help\", :comments =\u003e [{ :author_id =\u003e 19, :value =\u003e \"This is a comment\" }])\n```\n\nFurther documentation can be found on [developer.zendesk.com](https://developer.zendesk.com/rest_api/docs/support/ticket_import)\n\n### Attaching files\n\nFiles can be attached to ticket comments using either a path or the File class and will\nbe automatically uploaded and attached.\n\n```ruby\nticket = ZendeskAPI::Ticket.new(client, :comment =\u003e { :value =\u003e \"attachments\" })\nticket.comment.uploads \u003c\u003c \"img.jpg\"\nticket.comment.uploads \u003c\u003c File.new(\"img.jpg\")\nticket.save!\n```\n\n### Apps API\n\nv1.1.0 introduces support for the Zendesk [Apps API](https://developer.zendesk.com/rest_api/docs/support/apps)\n\n#### Creating Apps\n\n```ruby\nupload = client.apps.uploads.create!(:file =\u003e \"path/to/app.zip\")\nclient.apps.create!(:name =\u003e \"test\", :upload_id =\u003e upload.id)\n\n# Or\n\napp = ZendeskAPI::App.new(client, :name =\u003e \"test\")\napp.upload = \"path/to/app.zip\"\napp.save!\n\n# Or\n\nupload = ZendeskAPI::App::Upload.new(client, :file =\u003e \"path/to/app.zip\")\nupload.save!\n\napp = ZendeskAPI::App.new(client, :name =\u003e \"test\")\napp.upload_id = upload.id\napp.save!\n\n# Or\n\nclient.apps.create!(:name =\u003e \"test\", :upload =\u003e \"app.zip\")\n```\n\n*Note: job statuses are currently not supported, so you must manually poll the job status API for app creation.*\n\n```ruby\nbody = {}\nuntil %w{failed completed}.include?(body[\"status\"])\n  response = client.connection.get(app.response.headers[\"Location\"])\n  body = response.body\n\n  sleep(body[\"retry_in\"])\nend\n```\n\n#### Updating Apps\n\n```ruby\nupload = client.apps.uploads.create!(:file =\u003e \"NewApp.zip\")\n\n# Then\n\nclient.apps.update!(:id =\u003e 123, :upload_id =\u003e upload.id)\n\n# Or\n\napp = ZendeskAPI::App.new(client, :id =\u003e 123)\napp.upload_id = upload.id\napp.save!\n\n# Or\n\nZendeskAPI::App.update!(client, :id =\u003e 123, :upload_id =\u003e upload.id)\n```\n\n#### Deleting Apps\n\n```ruby\nclient.apps.destroy!(:id =\u003e 123)\n\napp = ZendeskAPI::App.new(client, :id =\u003e 123)\napp.destroy!\n\nZendeskAPI::App.destroy!(client, :id =\u003e 123)\n```\n\n#### Installing an App\n\n**Installation name is required**\n\n```ruby\ninstallation = ZendeskAPI::AppInstallation.new(client, :app_id =\u003e 123, :settings =\u003e { :name =\u003e 'Name' })\ninstallation.save!\n\n# or\n\nclient.apps.installations.create!(:app_id =\u003e 123, :settings =\u003e { :name =\u003e 'Name' })\n\n# or\n\nZendeskAPI::AppInstallation.create!(client, :app_id =\u003e 123, :settings =\u003e { :name =\u003e 'Name' })\n```\n\n#### List Installations\n\n```ruby\napps = client.app.installations\napps.fetch!\n```\n\n#### Update Installation\n\n```ruby\nclient.app.installations.update!(:id =\u003e 123, :settings =\u003e { :title =\u003e \"My New Name\" })\n\ninstallation = ZendeskAPI::AppInstallation.new(client, :id =\u003e 123)\ninstallation.settings = { :title =\u003e \"My New Name\" }\ninstallation.save!\n\nZendeskAPI::AppInstallation.update!(client, :id =\u003e 123, :settings =\u003e { :title =\u003e \"My New Name\" })\n```\n\n#### Delete Installation\n\n```ruby\nclient.app.installations.destroy!(:id =\u003e 123)\n\ninstallation = ZendeskAPI::AppInstallation.new(client, :id =\u003e 123)\ninstallation.destroy!\n\nZendeskAPI::AppInstallation.destroy!(client, :id =\u003e 123)\n```\n\n## Running the gem locally\n\nSee `.github/workflows/main.yml` to understand the CI process.\n\n```\nbundle exec rake # Runs the tests\nbundle exec rubocop # Runs the lint (use `--fix` for autocorrect)\n```\n\n## Releasing a new gem version\n\n1. From updated master: `git checkout -b bump-vX.X.X`, according to [SemVer](https://semver.org)\n2. Ensure the CHANGELOG is correct and updated, this is your last opportunity\n3. Execute `bundle exec bump:patch # minor|major`, this bumps the version in a new commit, and adds the relative git tag\n4. Push to GitHub `git push origin vX.X.X -u \u0026\u0026 git push --tags`\n5. Raise a PR ([example](https://github.com/zendesk/zendesk_api_client_rb/pull/540)) including the code diff ([example](https://github.com/zendesk/zendesk_api_client_rb/compare/v2.0.1...v3.0.0.rc1))\n6. Get it approved and merged\n7. Post a message in Slack `#rest-api` (example **TODO**), so advocacy are aware that we are going to release a new gem, just in case any customer complains about something related to the gem\n8. After 2 hours from the above message, you can [approve the release of the gem](https://github.com/zendesk/zendesk_api_client_rb/deployments/activity_log?environment=rubygems-publish)\n\n## Contributing\n\n1. Fork the project.\n2. Make your feature addition or bug fix.\n3. **Add tests for it**. This is important so that we don't break it in a future\n   version unintentionally.\n4. Commit. Do not alter `Rakefile`, version, or history. (If you want to have\n   your own version, that is fine, but bump version in a commit by itself that\n   we can ignore when we pull.)\n5. Submit a pull request.\n\n**Note:** Live specs will likely fail for external contributors. The Zendesk devs can help with that. If you have permissions and some live specs unexpectedly fail, that might be a data error, see the REPL for that.\n\n## Merging contributors pull requests\n\nExternal contributions don't run live specs, so we need to use a workaround. Assuming a PR from `author:author/branch` to `default_branch`:\n\n1. Create a branch in our repo `author_branch`\n2. Change the destination branch of the PR to `author_branch`\n3. Merge\n4. Create a pr in our repo from `default_branch`\n   - Make sure they know the commits still carry their name\n   - [Example](https://github.com/zendesk/zendesk_api_client_rb/pull/553)\n\n## Copyright and license\n\nCopyright 2015-2023 Zendesk\n\nSee [LICENSE](./LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fzendesk_api_client_rb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzendesk%2Fzendesk_api_client_rb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzendesk%2Fzendesk_api_client_rb/lists"}