This is a library for the Freshdesk helpdesk system for Python 2.7 and 3.6+.
It includes the following features from the Freshdesk v2 API:
- Tickets
- Get
- Create
- Update
- Delete
- Create OutBound Email
- List
- Filter (from 1.2.6)
- List Time Entries (from 1.2.4)
- Custom ticket fields (from 1.1.1)
- Ticket Fields
- Comments (known as Conversations in Freshdesk)
- Groups
- Contacts
- Company
- Roles (from 1.1.1)
- Agents (from 1.1.1)
- Solutions (from master)
- Solution Category (from 1.3.8)
- Get
- Get Translated
- List
- List Translated
- Create
- Create Translated
- Update
- Update Translated
- Delete
- Solution Folder (from 1.3.8)
- Get
- Get Translated
- List
- List Translated
- Create
- Create Translated
- Update
- Update Translated
- Delete
- Solution Article (from 1.3.8)
- Get
- Get Translated
- List
- List Translated
- Create
- Create Translated
- Update
- Update Translated
- Delete
- Solution Category (from 1.3.8)
From version 1.3.0, this library uses the Freshdesk v2 API by default.
The easiest way to install is from PyPi inside a virtualenv:
-
Create the virtualenv (Python 2.7 and 3.6+ supported) and activate it:
$ virtualenv cool_app $ cd cool_app && source bin/activate -
Install from PyPi:
$ pip install python-freshdesk -
Optionally, run the test suite:
$ pip install pytest $ pytest
Please note the domain and API key are not real and the example will not work without changing these.
>>> from freshdesk.api import API
>>> a = API('company.freshdesk.com', 'q8dnkjaS554Aol21dmnas9d92')To find your API key, follow Freshdesk's step-by-step solution article How to find your API key.
The API class provides access to all the methods exposed by the Freshdesk API.
Optionally, the API can be given SSL verification and/or proxy settings to obey for all requests:
>>> a = API('company.freshdesk.com', 'q8dnkjaS554Aol21dmnas9d92', verify=False)>>> proxies = {
... 'http': 'http://example.proxy:8000',
... 'https': 'https://example.proxy:8443'
... }
>>> a = API('company.freshdesk.com', 'q8dnkjaS554Aol21dmnas9d92', proxies=proxies)The Ticket API is accessed by using the methods assigned to the a.tickets instance. Tickets are loaded as instances
of the freshdesk.v2.models.Ticket class, and can be iterated over:
>>> a.tickets.list_tickets()
[<Ticket 'New ticket'>, <Ticket 'Some tests should be created'>, <Ticket 'Library needs to be uploaded to PyPi'>]
>>> a.tickets.list_deleted_tickets()
[<Ticket 'This is a sample ticket'>]To see which attributes were loaded for a ticket:
>>> ticket = a.tickets.get_ticket(4)
>>> repr(ticket)
"<Ticket 'I keep typing Freskdesk instead of Freshdesk!>"
>>> ticket._keys
set([u'status', u'source_name', u'ticket_type', u'updated_at', ...])Attributes are automatically converted to native Python objects where appropriate:
>>> a.tickets.list_tickets()[0].created_at
datetime.datetime(2014, 12, 5, 14, 7, 44)Or converted from indexes to their descriptions:
>>> ticket.priority
'medium'
>>> ticket.status
'closed'
>>> ticket.source
'phone'You can get additional details of the ticket in the response using extra arguments (from 1.3.5).
Please take a look at the FreshDesk documentation for more details: View a Ticket
>>> ticket = a.tickets.get_ticket(4, "conversation", "requester", "company", "stats")
>>> ticket.stats
{'agent_responded_at': '2020-06-26T01:23:39Z',
'requester_responded_at': '2020-06-25T23:10:15Z',
'first_responded_at': '2020-06-17T20:23:43Z',
'status_updated_at': '2020-07-24T15:35:21Z',
'reopened_at': None,
'resolved_at': '2020-07-24T15:35:21Z',
'closed_at': None,
'pending_since': None}Creating a ticket can be done by calling create_ticket():
ticket = a.tickets.create_ticket('This is a sample ticket',
email='example@example.com',
description='This is the description of the ticket',
tags=['example'])To create a ticket with attachments, pass a list of fully quilified file paths with key name attachments:
ticket = a.tickets.create_ticket('This is a sample ticket',
email='example@example.com',
description='This is the description of the ticket',
tags=['example'],
attachments=[
'/path/to/file1',
'/path/to/file2']
)The only positional argument is the subject, which is always required.
You will need to specify at least one of: requester_id, email, facebook_id, phone or twitter_id as the
requester of the ticket, or the request will fail. All other keyword arguments are optional.
You can get the list of tickets by calling list_tickets():
ticket = a.tickets.list_tickets(filter_name=None, updated_since='2014-01-01T00:00:00.000Z', page=1, per_page=10)All arguments given above are optional.
By default the new_and_my_open filter is used. If you want to list all the tickets without any filter, pass
filter_name=None.
Only the tickets that have been created within the past 30 days will be returned by default.
For fetching older tickets, use the updated_since argument to pass a datetime in isoformat (from 1.3.3).
Pagination is supported. If page argument is not passed, all pages are fetched, else the specified page is returned.
Updating a ticket is similar to creating a ticket. The only differences are that the ticket ID becomes the first positional argument, and subject becomes an optional named argument.
In this example, we update the subject and set the priority of the ticket as urgent:
ticket = a.tickets.update_ticket(4,
subject='This is an urgent ticket',
priority=4)The full list of named arguments you can pass can be found in updating a ticket.
To delete a ticket, just pass the ticket ID value to delete_ticket():
a.tickets.delete_ticket(4)To view ticket fields, call list_ticket_fields() with a field type:
>>> a.ticket_fields.list_ticket_fields(type='default_requester')
[<TicketFields Requester Email of Requester >, <TicketFields Type Type of Ticket >]To view comments on a ticket (note or reply), pass the ticket number to list_comments():
>>> a.comments.list_comments(4)
[<Comment for <Ticket 'Some tests should be created'>>]
>>> ticket.comments[0]
'We could use Travis CI'Pagination is supported. If page option is not specified, then all the pages are fetched, else specified page is returned.
The original comment (called "description" in Freshdesk) is available on the Ticket instance:
>>> ticket.description
'nose is a good suite'If you want to add a comment to an existing ticket, you can do it via a note or a reply.
The differences between notes and replies are that notes can be private (only visible to the agents, default). Replies are intended to be comments that are sent to the user (e.g. as an email).
To create a note:
>>> comment = a.comments.create_note(4,
'This is a public note',
private=False)
'<Comment for Ticket #4>'To create a reply:
>>> a.comments.create_reply(4, 'This is the body of a reply')
'<Comment for Ticket #4>'The documentaion for creating a reply and creating a note will provide details of the fields available, which you can pass as named arguments.
In both methods, the ticket ID and body must be given as positional arguments.
Freshdesk mixes up the naming of contacts and users, depending on whether they are an agent or not.
python-freshdesk simply calls them all contacts and are represented as Contact instances:
>>> repr(a.contacts.get_contact(1234))
"<Contact 'Rachel'>"Get the list of contacts using:
>>> repr(a.contacts.list_contacts(page=1, per_page=10))
["<Contact 'Rachel'>"]Pagination is supported. If page option is not specified, then all the pages are fetched, else specified page is
returned. Contact can be filtered using name or email by passing the filter as email=abc@xyz.com or
mobile=123792182138 or state=deleted
Other supported methods are create_contact, update_contact, soft_delete_contact, permanently_delete_contact,
restore_contact
To convert a contact to an agent, use:
>>> repr(a.contacts.make_agent(1))
["<Agent 'Rachel'>"]To get a specific agent instance, use:
>>> repr(a.agents.get_agent(1234))
"<Agent 'Rachel'>"You can list all agents by calling list_agents():
>>> repr(a.agents.list_agents(page=1, per_page=10))
["<Agent 'Rachel'>"]Pagination is supported. If page option is not specified, then all the pages are fetched, else specified page is
returned. Agent can be filtered using name or email by passing the filter as email=abc@xyz.com or
mobile=123792182138
Other supported methods are update_agent, delete_agent
To get the list of groups, use:
>>> repr(a.groups.list_groups(page=1, per_page=10))
["<Group 'Service Managers'>"]Pagination is supported. If page option is not specified, then all the pages are fetched, else specified page is returned.
To get a group, use:
>>> repr(a.groups.get_group(1))
["<Group 'Service Managers'>"]To get the list of companies, use:
>>> repr(a.companies.list_companies(page=1, per_page=10))
["<Company 'Super Nova'>"]Pagination is supported. If page option is not specified, then all the pages are fetched, else specified page is returned.
To get a company, use:
>>> repr(a.companies.get_company(1))
"<Company 'Super Nova'>"a.companies.filter_companies(query="updated_at:>'2020-07-12'")To delete a company (from 1.3.5), call delete_company() and pass the Freshdesk company ID.
To get the list of solution categories, use:
>>> repr(a.solutions.categories.list_categories())
["<SolutionCategory 'General Category' #2>"]To get the translated solution categories, use:
>>> repr(a.solutions.categories.list_categories_translated('fr'))
["<SolutionCategory 'Catégorie générale' #2>"]To get the list of folders from a solution category, use:
>>> repr(a.solutions.folders.list_from_category(2))
["<SolutionFolder 'Getting Started' #3>"]To get the list of translated folders from a solution category, use:
>>> repr(a.solutions.folders.list_from_category_translated(2, 'fr'))
["<SolutionFolder 'Commencer' #3>"]To get list of solution articles within a folder, use:
>>> repr(a.solutions.articles.list_from_foldery(3))
["<SolutionArticle 'Changing account details' #4>"]To get list of solution translatied articles within a folder, use:
>>> repr(a.solutions.articles.list_from_foldery_translated(3, 'fr'))
["<SolutionArticle 'Modifier les détails du compte' #4>"]To get a specific article by number, use:
>>> repr(a.solutions.articles.get_article(5))
["<SolutionArticle 'Adding a payment method' #5>"]To get a translated solution article, use:
>>> repr(a.solutions.articles.get_article_translated(5, 'fr'))
["<SolutionArticle 'Ajouter un moyen de paiement' #5>"]Thank you to all the people who have worked on this library and made it great for everyone.