Documentation

Product Support

Installation

Rubygems

gem install zendesk_api

Bundler

gem "zendesk_api"

Configuration

require'zendesk_api'client=ZendeskAPI::Client.newdo |config|# Mandatory:config.url="<- your-zendesk-url ->"# e.g. https://yoursubdomain.zendesk.com/api/v2# Basic / Token Authenticationconfig.username="login.email@zendesk.com"# Choose one of the following depending on your authentication choice# More information on obtaining API tokens can be found here:# https://developer.zendesk.com/api-reference/introduction/security-and-auth/#api-tokenconfig.token="your zendesk token"# OAuth Authentication# More information on obtaining OAuth access tokens can be found here:# https://developer.zendesk.com/api-reference/introduction/security-and-auth/#oauth-access-tokenconfig.access_token="your OAuth access token"# Optional:# Retry uses middleware to notify the user# when hitting the rate limit, sleep automatically,# then retry the request.config.retry=true# Raise error when hitting the rate limit.# This is ignored and always set to false when `retry` is enabled.# Disabled by default.config.raise_error_when_rate_limited=false# Logger prints to STDERR by default, to e.g. print to stdout:require'logger'config.logger=Logger.new(STDOUT)# Disable resource cache (this is enabled by default)config.use_resource_cache=false# Changes Faraday adapter# config.adapter = :patron# Merged with the default client options hash# config.client_options = {:ssl => {:verify => false}, :request => {:timeout => 30}}# When getting the error 'hostname does not match the server certificate'# use the API at https://yoursubdomain.zendesk.com/api/v2# Change retry configuration (this is disabled by default)config.retry_on_exception=true# Error codes when the request will be automatically retried. Defaults to 429, 503config.retry_codes=[429]end

Usage

ZendeskAPI::Ticket.new(client,:id=>1,:priority=>"urgent")# doesn't actually send a request, must explicitly call #save!ZendeskAPI::Ticket.create!(client,:subject=>"Test Ticket",:comment=>{:value=>"This is a test"},:submitter_id=>client.current_user.id,:priority=>"urgent")ZendeskAPI::Ticket.find!(client,:id=>1)ZendeskAPI::Ticket.destroy!(client,:id=>1)

ticket=ZendeskAPI::Ticket.find!(client,:id=>1)ticket.update(:comment=>{:value=>"This is a test reply."})ticket.save!

client.tickets.firstclient.tickets.find!(:id=>1)client.tickets.build(:subject=>"Test Ticket")client.tickets.create!(:subject=>"Test Ticket",:comment=>{:value=>"This is a test"},:submitter_id=>client.current_user.id,:priority=>"urgent")client.tickets.destroy!(:id=>1)

Caveats

zendesk_api_client_rb $ bundle console> a = ZendeskAPI::Trackie.new(:test => []).tap(&:clear_changes)> a.changed?(:test) => false> a.test << "hello" => ["hello"]> a.changed?(:test) => false> a.test += %w{hi} => ["hello", "hi"]> a.changed?(:test) => true

Pagination

# Note that CBP (cursor based pagination) is the default and preferred way# and has fewer limitations on deep paginationtickets=client.tickets.per_page(3)page1=tickets.fetch!# GET /api/v2/tickets?page[after]={cursor}&page[size]=3page2=tickets.next# GET /api/v2/tickets?page[after]={cursor}&page[size]=3# ...# OR...# Note that OBP (offset based pagination) can incur to various limitationstickets=client.tickets.page(2).per_page(3)next_page=tickets.next# => 3tickets.fetch!# GET /api/v2/tickets?page=3&per_page=3previous_page=tickets.prev# => 2tickets.fetch!# GET /api/v2/tickets?page=2&per_page=3

client.tickets.all!do |resource|# every resource, from all pages, will be yielded to this blockend

client.tickets.all!do |resource,page_number|# all resources will be yielded along with the page numberend

Cursor Based Pagination

client.connection.get('/api/v2/suspended_tickets',page:{size:100}).body{"suspended_tickets"=>[...],"meta"=>{"has_more"=>true,"after_cursor"=>" ... ","before_cursor"=>nil},"links"=>{"prev"=>nil,"next"=>"..."}}

Callbacks

client.insert_callbackdo |env|putsenv[:response_headers]end

Resource management

ticket=client.tickets[0]# ZendeskAPI::Ticket.find(client, :id => 1)ticket.priority="urgent"ticket.attributes# => { "priority" => "urgent" }ticket.save!# Will PUT => trueticket.destroy!# => trueZendeskAPI::Ticket.new(client,{priority:"urgent"})ticket.new_record?# => trueticket.save!# Will POST

Side-loading

"ticket": {"id":1,"url":"http.....","requester_id":7,...}

tickets=client.tickets.include(:users)# Or client.tickets(:include => :users)# Does *NOT* make a request to the server since it is already loadedtickets.first.requester# => #<ZendeskAPI::User id=...># ORticket=client.tickets.find!(:id=>1,:include=>:users)ticket.requester# => #<ZendeskAPI::User id=...>

Recommended Approach

ticket=ZendeskAPI::Ticket.find(id:1)requester=ZendeskAPI::User.find(id:ticket.requester_id)

Omnichannel

# All agent availabilitiesclient.agent_availabilities.fetch# fetch availability for one agent, their channels and work itemsagent_availability=ZendeskAPI::AgentAvailability.find(client,386390041152)agent_availability.channelsagent_availability.channels.first.work_items# Using the agent availability filterZendeskAPI::AgentAvailability.search(client,{select_channel:'support'})ZendeskAPI::AgentAvailability.search(client,{channel_status:'support:online'})

Search

client.search(:query=>"my search query")# /api/v2/search.json?query=...client.users.search(:query=>"my new query")# /api/v2/users/search.json?query=...

Special case: Custom resources paths

client.tickets.recentclient.topics.show_many(:verb=>:post,:ids=>[1,2,3])

Special Case: Current user

client.users.find!(:id=>'me')client.current_user

Special Case: Importing a ticket

ticket=ZendeskAPI::Ticket.import(client,:subject=>"Help",:comments=>[{:author_id=>19,:value=>"This is a comment"}])

Attaching files

ticket=ZendeskAPI::Ticket.new(client,:comment=>{:value=>"attachments"})ticket.comment.uploads <<"img.jpg"ticket.comment.uploads <<File.new("img.jpg")ticket.save!

Apps API

Creating Apps

upload=client.apps.uploads.create!(:file=>"path/to/app.zip")client.apps.create!(:name=>"test",:upload_id=>upload.id)# Orapp=ZendeskAPI::App.new(client,:name=>"test")app.upload="path/to/app.zip"app.save!# Orupload=ZendeskAPI::App::Upload.new(client,:file=>"path/to/app.zip")upload.save!app=ZendeskAPI::App.new(client,:name=>"test")app.upload_id=upload.idapp.save!# Orclient.apps.create!(:name=>"test",:upload=>"app.zip")

body={}until%w{failedcompleted}.include?(body["status"])response=client.connection.get(app.response.headers["Location"])body=response.bodysleep(body["retry_in"])end

Updating Apps

upload=client.apps.uploads.create!(:file=>"NewApp.zip")# Thenclient.apps.update!(:id=>123,:upload_id=>upload.id)# Orapp=ZendeskAPI::App.new(client,:id=>123)app.upload_id=upload.idapp.save!# OrZendeskAPI::App.update!(client,:id=>123,:upload_id=>upload.id)

Deleting Apps

client.apps.destroy!(:id=>123)app=ZendeskAPI::App.new(client,:id=>123)app.destroy!ZendeskAPI::App.destroy!(client,:id=>123)

Installing an App

installation=ZendeskAPI::AppInstallation.new(client,:app_id=>123,:settings=>{:name=>'Name'})installation.save!# orclient.apps.installations.create!(:app_id=>123,:settings=>{:name=>'Name'})# orZendeskAPI::AppInstallation.create!(client,:app_id=>123,:settings=>{:name=>'Name'})

List Installations

apps=client.app.installationsapps.fetch!

Update Installation

client.app.installations.update!(:id=>123,:settings=>{:title=>"My New Name"})installation=ZendeskAPI::AppInstallation.new(client,:id=>123)installation.settings={:title=>"My New Name"}installation.save!ZendeskAPI::AppInstallation.update!(client,:id=>123,:settings=>{:title=>"My New Name"})

Delete Installation

client.app.installations.destroy!(:id=>123)installation=ZendeskAPI::AppInstallation.new(client,:id=>123)installation.destroy!ZendeskAPI::AppInstallation.destroy!(client,:id=>123)

Running the gem locally

bundle exec rake # Runs the testsbundle exec rubocop # Runs the lint (use `--fix` for autocorrect)

Releasing a new version

Contributing

Merging contributors pull requests

Copyright and license