Get Ticket History API - Explained in Detail

Get Ticket History API - Explained in Detail

Introduction

This API fetches details of all actions performed on a ticket and in the sub-tabs on the ticket detail page.

Request Format

GET: api/v1/tickets/{ticket_Id}/History

Query Parameters 

  1. from - int -  Index number, starting from which the details must be fetched. If you do not specify a value for this key, the default value of 0 is considered. 
  2. limit - int - Number of details to list. The values allowed range from 1 to 50. If you do not specify a value for this key, the default value of 10 is considered.
  3. eventFilter - string - Key that filters details based on the action performed on the ticket. Values allowed are:
    1. CommentHistory  
    2. TimeEntryHistory
    3. AttachmentHistory  
    4. ApprovalHistory
    5. AssignmentRuleHistory
    6. NotificationRuleHistory
    7. WorkflowHistory
    8. MacroHistory
    9. SuperviseHistory
    10. SLAHistory
    11. BlueprintHistory
    12. TaskHistory
    13. CallHistory
    14. EventHistory
  4. agentId - long - Key that filters details of actions performed by a particular agent. Value allowed is the agent's ID in Zoho Desk.
  5. fieldName - string - Key that returns the changes in the value of a particular field. The value of this param should be the API name of the field.
Note: You can include all three filters in a single API call. If you do this, the response will contain history entries that match all three filters. 

Response Format

This API returns data as a JSON array inside a JSON object wrapper. The array contains history entries arranged in descending order of time, which means the latest action on the ticket is displayed first. The following template will give you a visual representation of the response structure. 

{
    "data": [
        {
            "eventName": "EventNameEnum",
            "eventTime": "DateTime",
            "actor": {
                "id": "Long",
                "name": "String",
                "type": "ActorTypeEnum"
            },
            "source": "SourceEnum",
            "eventInfo": [
                {
                    "propertyName": "String",
                    "propertyValue": "#Value type will vary based on propertyType",
                    "propertyType": "PropertyTypeEnum",
                    "systemProperty": "boolean"
                }
            ],
            "actorInfo": [
                {
                    "propertyName": "String",
                    "propertyValue": "#Value type will vary based on propertyType",
                    "propertyType": "PropertyTypeEnum",
                    "systemProperty": "boolean"
                }
            ]
        }
    ]
}
The JSON object inside the data array represents a single history entry. The template shows all the keys pertaining to a single history entry and its corresponding value types. Here, the value of the propertyValue key will vary based on the value of propertyType, which is an enumerable constant.

All the keys and enumeration constants used in the template are as follows:

eventName 
Key that represents the type of action performed on the ticket. The value of this key is an enumerable constant and the values supported are as follows: 
  1. TicketCreated
  2. TicketUpdated
  3. TicketDeleted
  4. TicketRestored
  5. TicketCloned
  6. TicketMergedMaster
  7. TicketSplitParent
  8. TicketSplitChild
  9. TicketArchived
  10. TicketEscalated
  11. TicketShared
  12. TicketShareModeUpdated
  13. TicketShareRevoked
  14. ThreadAdded
  15. ThreadDeleted
  16. ThreadResent
  17. CommentAdded
  18. CommentEdited
  19. CommentDeleted
  20. ApprovalSent
  21. ApprovalApproved
  22. ApprovalRejected
  23. FollowersAdded
  24. FollowersRemoved
  25. TagsAdded
  26. TagsRemoved
  27. AttachmentAdded
  28. AttachmentUpdated
  29. AttachmentDeleted
  30. AttachmentRestored
  31. AttachmentDeletedRB
  32. TimeEntryAdded
  33. TimeEntryUpdated
  34. TimeEntryDeleted
  35. TimeEntryRestored
  36. SecondaryContactsAdded
  37. SecondaryContactsUpdated
  38. OvershotDueTime
  39. BlueprintApplied
  40. BlueprintRevoked
  41. BlueprintTransitionPerformed
  42. BlueprintStateMoved
  43. CustomFunctionExecuted
  44. NotificationSent
  45. CallAdded
  46. CallUpdated
  47. CallDeleted
  48. CallRestored
  49. CallCommentAdded
  50. CallCommentEdited
  51. CallCommentDeleted
  52. CallTimeEntryAdded
  53. CallTimeEntryUpdated
  54. CallTimeEntryDeleted
  55. CallTimeEntryRestored
  56. EventAdded
  57. EventUpdated
  58. EventDeleted
  59. EventRestored
  60. EventCommentAdded
  61. EventCommentEdited
  62. EventCommentDeleted
  63. EventTimeEntryAdded
  64. EventTimeEntryUpdated
  65. EventTimeEntryDeleted
  66. EventTimeEntryRestored
  67. TaskAdded
  68. TaskUpdated
  69. TaskDeleted
  70. TaskRestored
  71. TaskCommentAdded
  72. TaskCommentEdited
  73. TaskCommentDeleted
  74. TaskTimeEntryAdded
  75. TaskTimeEntryUpdated
  76. TaskTimeEntryDeleted
  77. TaskTimeEntryRestored
  78. BugCreated
  79. BugLinked
  80. BugDelinked
  81. InvoiceCreated
  82. EstimateCreated
  83. SalesOrderCreated
eventTime
Timestamp value of the time when the action was performed.

actor
Details of the user or functionality that performed the action on the ticket. Ticket actions can be performed by support agents, or customers, or automation rules, or the Zoho Desk system itself. The different keys included in this object are as follows:
      id       -  ID of the actor. In some cases, the value can be null.
      name - Name of the actor. If the actor is an agent or a customer, their full name is returned; if the actor is an automation rule, the name of the rule is returned; and if the actor is the Zoho Desk system, the value DeskSystem is returned.
      type   - Type of the actor. Values supported are:
  1. Agent
  2. Contact
  3. DirectAssignment
  4. RoundRobinAssignment
  5. NotificationRule
  6. SLA
  7. Workflow
  8. Macro
  9. Supervise
  10. Blueprint
  11. System
source
Contextual information related to the action. For instance, if a thread is added to a ticket, this key will return information on the channel through which the thread was added. The values supported are: 
  1. Email
  2. Chat
  3. OfflineChat
  4. HelpCenter
  5. Forum
  6. Twitter
  7. Facebook
  8. FeedbackWidget
  9. WebForm
  10. CustomChannel
  11. Import
  12. IncomingResponse
  13. CustomerRating
  14. Setting
  15. LicenseDowngrade
  16. ZohoBugTracker
  17. Jira
  18. ZohoBooks
  19. ZohoInvoice
  20. ZohoInventory
In some cases, the value of this key can be null.

eventInfo
Additional details related to the action. The value of eventInfo is a JSON array with the property object as its element type. The value of eventInfo will be an empty array if no additional information about the action is available.

actorInfo
Additional details related to the actor. Just like in the case of eventInfo, the value of actorInfo is also a JSON array with the property object as its element type. The value of actorInfo will be an empty array if no additional information about the actor is available.

The structure of the property object is as follows:

Property Object

{
      "propertyName": "String",
      "systemProperty": "boolean",
      "propertyType": "PropertyTypeEnum",
      "propertyValue": "# Will vary based on propertyType" 
}
The property object contains data on a single property of a resource. For instance, field values in a ticket and @mentions in a comment. The keys supported in the object are as follows:      
      propertyName   - Name of the property.
      systemProperty - Boolean value that denotes whether the property is system-generated or not. Custom fields are treated as non-system properties.
      propertyType     - Type of the property. Values supported are:
      
Property type
Property value type
Text
String value
TextList
JSON array containing only string values as elements.
Enum
This is a string value that supports countable values. The possible values vary, based on the context.
Boolean
Boolean value
Date
Date in the yyyy-mm-dd format
DateTime
Timestamp value
Duration
Integer value that represents the duration in seconds.
Numeric
Numeric value — it can be an integer or a float value.
Entity
JSON object that represent a single entity, such as agent, customer, ticket, activity, blueprint, and so on. A more detailed explanation is given below.
EntityList
JSON array of Entity objects
PropertyGroup
JSON array of Property objects
PropertyGroupList
JSON array of PropertyGroup arrays
ValueTransition
JSON object that represents a field update. A more detailed explanation is given below.

Entity
The structure of this object is as follows:
{
      "id": "Long",
      "name": "String",
      "type": "EntityTypeEnum"
}
id        - ID of the entity
name  - Name of the entity. In case of a ticket, the ticket number is considered and in case of an activity, the subject of the activity is considered. 
type    - Type of the entity, which is an enumerable constant. The values supported are:
  1. Agent
  2. Contact
  3. Department
  4. Team
  5. Ticket
  6. Call
  7. Event
  8. Task
  9. Activity
  10. Blueprint
  11. Transition
  12. Layout
If an entity is deleted and its corresponding data is not available in the system, it is presented as a deleted entity. Details of deleted entities are displayed in the following format:
{
      "id": "Long/null",
      "name": "DELETED-ENTITY",
      "type": "EntityTypeEnum-Deleted"
}
Below is an example of details of a deleted team.
{
      "id": "57890890789568",
      "name": "DELETED-ENTITY",
      "type": "Team-Deleted"
}
Note: If an activity is deleted, the exact type of the activity cannot be identified. So, the API returns the type as just "Activity". For activities that are not deleted, the exact type is returned.

ValueTransition
This object returns information related to a field update. The structure of this object is as follows:
{
      "previousValue": "# data type will vary based on type",
      "updatedValue": "# data type will vary based on type",
      "type": "ValueTransitonTypeEnum"
}
The values of both the previousValue and updatedValue keys will always be of the same data type. The type of value will change, based on the type key.
All property types except PropertyGroup, PropertyGroupList, and ValueTransition are supported by value transitions.

To view the list of history events supported and an example for each event, refer to this document.

    • Related Articles

    • Events Supported in the Get Ticket History API

      Introduction The Get ticket history API returns details of the actions — called events — performed on a ticket. In this document, you will learn about the different events supported and the variations of each event. Ticket History Events Each event ...

    • Customer Ticket History for Zoho Desk

      When new tickets are assigned, it is important to show your agents the past support tickets of the customer so that your agents can have more direct, effective, and meaningful conversations. The Customer Ticket History extension for Zoho Desk ...

    • What are Ticket Tabs?

      Ticket tabs allow you to link tickets to the other standard modules in your help desk.  These tabs provide contextual information about a ticket such as ticket activity, pending tasks, supportive files, resolutions and the like. Let's take a look at ...

    • Viewing Article History in Knowledge base

      It is not unusual for a knowledge base article to undergo multiple updates both during drafting and once published for customers. But keeping track of what is going on around an article is equally important. It will save you a lot of headaches when ...

    • GoToWebinar for Zoho Desk

      Webinars help give product demos and make a great tool for customer support. The GoToWebinar extension for Zoho Desk helps support agents explain their product efficiently through webinars, allowing them to resolve support tickets faster. With this ...