問い合わせの操作履歴データを取得するAPIに関する詳細

問い合わせの操作履歴データを取得するAPIに関する詳細

はじめに

このAPIでは、問い合わせ内や問い合わせの詳細画面の各サブタブにて行われたすべての操作に関する詳細データを取得することができます。

リクエスト形式

GET: api/v1/tickets/{問い合わせID}/History

クエリーの各パラメーター 

  1. from - int -  インデックス番号です。この番号から詳細データを取得します。このキーの値を指定しない場合、初期値は「0」と識別されます。 
  2. limit - int - 表示する詳細データの件数です。1から50までの値を指定できます。このキーの値を指定しない場合、初期値は「10」と識別されます。
  3. eventFilter - string - 問い合わせにて行われた操作に基づいて詳細データを抽出するためのキーです。指定可能な値は以下のとおりです:
    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 - 特定の担当者によって行われた操作に関する詳細データを抽出するためのキーです。指定可能な値は、 Zoho Deskの担当者ID です。
  5. fieldName - string - 特定の項目における、変更後の値を返すためのキーです。このパラメーターの値は、項目のAPI名である必要があります。
メモ: APIの1回の実行において、3つすべてのフィルターを含めることができます。3つすべてのフィルターを含める場合、3つすべてのフィルターに一致する履歴データをレスポンスとして返します。 

レスポンスの形式

このAPIは、JSONオブジェクトの括弧内のJSON配列をデータとして返します。配列には、新しい時間から順に並べられた履歴データが含まれます。つまり、問い合わせにて行われた最新の操作が先頭に表示されます。以下のテンプレートは、レスポンスのデータ構造の例です。 

      {
      
         
            "data"
         
      
      : [
      {
      
         
            "eventName"
         
      
      : 
      
         "EventNameEnum"
      
      ,
      
         
            "eventTime"
         
      
      : 
      
         "DateTime"
      
      ,
      
         
            "actor"
         
      
      : {
      
         
            "id"
         
      
      : 
      
         "Long"
      
      ,
      
         
            "name"
         
      
      : 
      
         "String"
      
      ,
      
         
            "type"
         
      
      : 
      
         "ActorTypeEnum"
      
      },
      
         
            "source"
         
      
      : 
      
         "SourceEnum"
      
      ,
      
         
            "eventInfo"
         
      
      : [
      {
      
         
            "propertyName"
         
      
      : 
      
         "String"
      
      ,
      
         
            "propertyValue"
         
      
      : 
      
         "#値の種類は「propertyType」によって異なります"
      
      ,
      
         
            "propertyType"
         
      
      : 
      
         "PropertyTypeEnum"
      
      ,
      
         
            "systemProperty"
         
      
      : 
      
         "boolean"
      
      }
      ],
      
         
            "actorInfo"
         
      
      : [
      {
      
         
            "propertyName"
         
      
      : 
      
         "String"
      
      ,
      
         
            "propertyValue"
         
      
      : 
      
         "#値の種類は「propertyType」によって異なります"
         
            ,
         
         
"propertyType" : "PropertyTypeEnum" , "systemProperty" : "boolean" } ] } ] }
data 配列内のJSONオブジェクトは、単一の履歴データを表します。上記のテンプレートでは、単一の履歴データとそれに対応する値の種類に関連するすべてのキーが表示されています。こちらでは、キー「 propertyValue 」の値は、列挙定数である「 propertyType 」の値によって異なります。

テンプレートにて使用されているすべてのキーと列挙定数は、以下のとおりです:

eventName 
問い合わせにて行われた操作の種類を表すためのキーです。このキーの値は列挙定数であり、対応している値は以下のとおりです: 
  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
操作が行われた時間を表す値です。

actor
問い合わせにて操作を行ったユーザー、または機能に関する詳細データです。問い合わせでの操作は、サポート担当者、顧客、自動化ルール、Zoho Deskのシステムによって行われたものです。このオブジェクトが含まれるそれぞれのキーは、以下のとおりです:
      id        -   操作を行ったユーザーや設定のIDです。場合によっては、この値はnullになります。
      name   - 操作を行ったユーザーや設定の名前です。担当者、または顧客によって操作が行われた場合、ユーザーの氏名を返します。自動化ルールによって操作が行われた場合、ルールの名前を返します。Zoho Deskのシステムによって操作が行われた場合、「 DeskSystem 」を値として返します。
      type    - 操作を行ったユーザーや設定の種類です。対応している値は以下のとおりです:
  1. Agent
  2. Contact
  3. DirectAssignment
  4. RoundRobinAssignment
  5. NotificationRule
  6. SLA
  7. Workflow
  8. Macro
  9. Supervise
  10. Blueprint
  11. System
source
操作に関連する情報です。たとえば、問い合わせにスレッドが追加された場合、このキーは、ユーザーがスレッドを追加した際に使用した経路(チャネル)に関する情報を返します。対応している値は以下のとおりです: 
  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
場合によっては、このキーの値はnullになります。

eventInfo
操作に関連する追加情報です。 eventInfo の値は、構成要素の種類として Propertyオブジェクト を持つJSON配列です。操作に関連する追加情報がない場合は、 eventInfo の値には何も表示されません。

actorInfo
操作を行ったユーザーや設定に関連する追加情報です。 eventInfo と同様に、 actorInfo の値は、構成要素の種類として Property オブジェクトを持つJSON配列です。操作を行ったユーザーや設定に関連する追加情報がない場合は、 actorInfo の値には何も表示されません。

Property オブジェクトの構造は以下のとおりです:

Propertyオブジェクト

      {
      
               
         
            "propertyName"
         
      
      : 
      
         "String"
      
      ,
      
               
         
            "systemProperty"
         
      
      : 
      
         "boolean"
      
      ,
      
               
         
            "propertyType"
         
      
      : 
      
         "PropertyTypeEnum"
      
      ,
      
               
         
            "propertyValue"
         
      
      : 
      
         "#「propertyType」によって異なります"
      
      }
      
   
Property オブジェクトには、単一のリソースのプロパティのデータが含まれます。たとえば、1件の問い合わせの項目の値や、1件のコメント内の@メンションです。このオブジェクトにて対応しているキーは、以下のとおりです:      
       propertyName    - プロパティの名前です。
      systemProperty - プロパティがシステムによって生成されたかどうかを表す真偽値です。カスタム項目は、システムによって生成されたプロパティとは扱われません。
      propertyType      - プロパティの種類です。対応している値は以下のとおりです:
      
Propertyの種類
Propertyの値の種類
Text
単一の値です。
TextList
構成要素として単一の値のみを含むJSON配列です。
Enum
計算可能な値に対応する文字列です。値は、関連するデータによって異なります。
Boolean
真偽値です。
Date
「yyyy-mm-dd」形式の日付です。
DateTime
時間を表す値です。
Duration
秒数にて期間を表す整数値です。
Numeric
数値です。整数、または小数のいずれかです。
Entity
担当者、顧客、問い合わせ、活動、ブループリントなど、単一の項目を表すJSONオブジェクトです。詳細については、別途以下で説明します。
EntityList
Entity オブジェクトのJSON配列です。
PropertyGroup
Property オブジェクトのJSON配列です。
PropertyGroupList
PropertyGroup 配列のJSON配列です。
ValueTransition
項目の更新内容を表すJSONオブジェクトです。詳細については、別途以下で説明します。

Entity
Entityオブジェクトの構造は、以下のとおりです:
{
      "id": "Long",
      "name": "String",
      "type": "EntityTypeEnum"
}
id        - 項目のIDです。
name   - 項目の名前です。問い合わせの場合、問い合わせ番号が表示されます。活動の場合、活動の件名が表示されます。 
type     - 項目の種類です。この値は列挙定数です。対応している値は以下のとおりです:
  1. Agent
  2. Contact
  3. Department
  4. Team
  5. Ticket
  6. Call
  7. Event
  8. Task
  9. Activity
  10. Blueprint
  11. Transition
  12. Layout
項目が削除され、項目のデータがシステム内に存在しない場合は、削除された項目のデータが表示されます。削除された項目の詳細データは、以下の形式で表示されます:
         { 
         
                  
            
               "id"
            
         
         : 
         
            "Long/null"
         
         , 
         
                  
            
               "name"
            
         
         : 
         
            "DELETED-ENTITY"
         
         , 
         
                  
            
               "type"
            
         
         : 
         
            "EntityTypeEnum-Deleted"
         
         }
         
      
以下は、削除されたチームの詳細データの例です。
         { 
         
                  
            
               "id"
            
         
         : 
         
            "57890890789568"
         
         , 
         
                  
            
               "name"
            
         
         : 
         
            "DELETED-ENTITY"
         
         , 
         
                  
            
               "type"
            
         
         : 
         
            "Team-Deleted"
         
         }
         
      
メモ:活動が削除された場合、活動の正確な種類は識別されません。そのため、種類は単に「Activity」として表示されます。活動が削除されていない場合は、活動の正確な種類が表示されます。

ValueTransition
このオブジェクトは、項目の更新内容に関連する情報を返します。このオブジェクトの構造は、以下のとおりです:
      { 
      
               
         
            "previousValue"
         
      
      : 
      
         "#「type」によってデータの種類が異なります"
      
      , 
      
               
         
            "updatedValue"
         
      
      : 
      
         "#「type」によってデータの種類が異なります"
      
      , 
      
               
         
            "type"
         
      
      : 
      
         "ValueTransitonTypeEnum"
      
      }
      
   
previousValue updatedValue のキーの値は、常に同じデータの種類になります。種類の値は、 type のキーによって異なります。
PropertyGroup PropertyGroupList ValueTransition を除くプロパティの種類は、すべて遷移の値に対応しています。

対応している履歴のイベントの一覧や、それぞれのイベントの表示方法については、 こちらのドキュメント をご参照ください。

    Zoho CRM 管理者向けトレーニング

    「導入したばかりで基本操作や設定に不安がある」、「短期間で集中的に運用開始できる状態にしたい」、「運用を開始しているが再度学び直したい」 といった課題を抱えられているユーザーさまに向けた少人数制のオンライントレーニングです。

    日々の営業活動を効率的に管理し、導入効果を高めるための方法を学びましょう。

    Zoho CRM Training



              Zoho Desk Resources

              • Desk Community Learning Series


              • Digest


              • Functions


              • Meetups


              • Kbase


              • Resources


              • Glossary


              • Desk Marketplace


              • MVP Corner


              • Word of the Day









                                Resources

                                Videos

                                Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                eBooks

                                Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                Webinars

                                Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                CRM Tips

                                Make the most of Zoho CRM with these useful tips.