Enhance Ticket API to support email thread entries and update documentation

Author: robcoward

include/api.tickets.php

@@ -414,7 +414,7 @@ private function array2XML($object, $data) {
     }
 
     /**
-     * Add a thread entry (reply or note) to a ticket
+     * Add a thread entry (reply, note, or email) to a ticket
      * 
      * This method allows adding a new thread entry to an existing ticket.
      * It supports:
@@ -428,9 +428,9 @@ private function array2XML($object, $data) {
      * - Alerting participants
      * 
      * Request fields (Staff/API posting):
-     * - thread_type: 'note' for internal note, 'response' for public reply (required)
+     * - thread_type: 'note' for internal note, 'response' for public reply, 'email' for client email simulation (required)
      * - message: Content of the thread entry (required)
-     * - staffId: ID of staff member making the post (optional)
+     * - staffId: ID of staff member making the post (optional, not used for 'email' type)
      * - alert: Whether to alert participants (default: true)
      * - poster: Name of the poster (default: 'API')
      * - cannedId: ID of canned response to use (optional)
@@ -445,8 +445,7 @@ private function array2XML($object, $data) {
      *   - data: File contents
      *   - encoding: 'base64' if encoded, otherwise raw data assumed
      *
-     * Request fields (Client/User reply simulation):
-     * - as_client: Set to true to simulate a client reply (required for user replies)
+     * Request fields (Email/Client reply simulation - when thread_type='email'):
      * - message: Content of the user reply (required)
      * - userId: ID of the user making the reply (default: ticket owner)
      * - attachments: Array of file attachments (optional, same format as above)
@@ -467,20 +466,21 @@ function addThread($id, $format) {
         // Get request data
         $data = $this->getRequest($format);
 
-        // Check if this is a user/client reply simulation
-        $isClientReply = isset($data['as_client']) && $data['as_client'];
-        
-        if ($isClientReply) {
-            // Handle user reply simulation
-            return $this->addClientReply($ticket, $data, $format);
+        // Support legacy 'as_client' parameter for backward compatibility
+        if (isset($data['as_client']) && $data['as_client']) {
+            $data['thread_type'] = 'email';
         }
 
-        // Continue with staff/API post handling
-        
         // Validate required fields
-        if (!isset($data['thread_type']) || !in_array($data['thread_type'], ['note', 'response']))
-            return $this->exerr(400, __('Missing or invalid "thread_type" - must be "note" or "response"'));
+        if (!isset($data['thread_type']) || !in_array($data['thread_type'], ['note', 'response', 'email']))
+            return $this->exerr(400, __('Missing or invalid "thread_type" - must be "note", "response", or "email"'));
 
+        // Handle email thread type (client/user reply simulation)
+        if ($data['thread_type'] === 'email') {
+            return $this->handleEmailThreadType($ticket, $data, $format);
+        }
+        
+        // Continue with staff/API post handling for note and response types
         if (!isset($data['message']) && !isset($data['cannedId']))
             return $this->exerr(400, __('Either message or cannedId must be provided'));
 
@@ -642,19 +642,19 @@ function addThread($id, $format) {
     }
 
     /**
-     * Handle client/user reply to a ticket
+     * Handle client/user reply to a ticket via email simulation
      * This simulates a user sending an email reply to a ticket
      * 
      * @param Ticket $ticket The target ticket
      * @param array $data Request data
      * @param string $format Response format (json or xml)
      * @return void
      */
-    private function addClientReply($ticket, $data, $format) {
+    private function handleEmailThreadType($ticket, $data, $format) {
         global $ost;
 
         if (!isset($data['message']) || !$data['message'])
-            return $this->exerr(400, __('Message is required for client reply'));
+            return $this->exerr(400, __('Message is required for email thread type'));
 
         // Get the user who is replying
         $user = null;
@@ -674,7 +674,7 @@ private function addClientReply($ticket, $data, $format) {
         }
 
         if (!$user)
-            return $this->exerr(500, __('Unable to determine user for client reply'));
+            return $this->exerr(500, __('Unable to determine user for email thread type'));
 
         // Format data to mimic an email message
         $emailData = [
@@ -727,7 +727,7 @@ private function addClientReply($ticket, $data, $format) {
             $result = $this->processEmail($emailData);
 
             if (!$result)
-                return $this->exerr(500, __('Failed to add client reply'));
+                return $this->exerr(500, __('Failed to add email reply'));
 
             // Get the thread entry that was just created
             $thread = $ticket->getThread();
@@ -748,7 +748,7 @@ private function addClientReply($ticket, $data, $format) {
                 'ticket_id' => $ticket->getId(),
                 'ticket_number' => $ticket->getNumber(),
                 'thread_id' => $entry->getId(),
-                'thread_type' => 'message', // Client messages are of type 'message'
+                'thread_type' => 'email',
                 'message_id' => $entry->getEmailMessageId(),
                 'timestamp' => $entry->getCreateDate(),
                 'current_status' => [
@@ -783,7 +783,7 @@ private function addClientReply($ticket, $data, $format) {
                 ], $format));
             }
         } catch (Exception $e) {
-            return $this->exerr(500, __('Failed to add client reply: ') . $e->getMessage());
+            return $this->exerr(500, __('Failed to add email reply: ') . $e->getMessage());
         }
     }
 

setup/doc/api/api-thread.md

@@ -6,7 +6,11 @@ This document describes how to use the osTicket API to add new threads (replies
 
 **Endpoint:** `POST /api/tickets/{id}/add_thread.json`
 
-This endpoint allows you to post new replies or internal notes to existing tickets.
+This endpoint allows you to post new replies, internal notes, or simulated client/user email replies to existing tickets. There are three types of thread entries you can create:
+
+1. **Internal Notes** (`thread_type=note`): Staff-only notes not visible to clients
+2. **Staff Responses** (`thread_type=response`): Public replies from staff members
+3. **Client/User Replies** (`thread_type=email`): Simulates an email reply from a client/user
 
 ### Authentication
 
@@ -27,17 +31,19 @@ The API accepts both JSON and XML formats. Make sure to set the appropriate Cont
 
 | Parameter | Type | Description | Required |
 |-----------|------|-------------|----------|
-| thread_type | string | Type of thread entry: 'note' for internal note, 'response' for public reply | Yes |
+| thread_type | string | Type of thread entry: 'note' for internal note, 'response' for public reply, 'email' for client/user reply simulation | Yes |
 | message | string | Content of the thread entry | Yes (unless using cannedId) |
-| staffId | integer | ID of staff member making the post | No |
+| staffId | integer | ID of staff member making the post (not used for 'email' type) | No |
 | alert | boolean | Whether to alert participants | No (default: true) |
-| poster | string | Name of the poster | No (default: 'API') |
-| cannedId | integer | ID of canned response to use | No |
+| poster | string | Name of the poster (default: 'API', not used for 'email' type) | No |
+| cannedId | integer | ID of canned response to use (not used for 'email' type) | No |
 | cannedMode | string | How to use canned response: 'prepend', 'append', 'replace' | No (default: 'replace') |
 | cannedAttachments | boolean | Whether to include canned response attachments | No (default: false) |
-| signature | string | Signature selection: 'none', 'mine', 'dept' | No (default: 'none') |
-| includeSignature | boolean | Whether to include signature | No (default: false) |
-| status_id | integer | ID of the status to set the ticket to | No |
+| signature | string | Signature selection: 'none', 'mine', 'dept' (not used for 'email' type) | No (default: 'none') |
+| includeSignature | boolean | Whether to include signature (not used for 'email' type) | No (default: false) |
+| status_id | integer | ID of the status to set the ticket to (not used for 'email' type) | No |
+| userId | integer | ID of the user making the reply (only for 'email' thread type) | No (default: ticket owner) |
+| as_client | boolean | Legacy parameter for backward compatibility (sets thread_type to 'email' when true) | No |
 | attachments | array | Array of file attachments | No |
 
 #### Attachment Format
@@ -127,11 +133,35 @@ Content-Type: application/json
 }
 ```
 
+#### Simulating a Client/User Reply (Email)
+
+The 'email' thread type simulates a user sending an email reply to the ticket. This is useful for integrations that need to add replies on behalf of clients or users. Unlike the 'note' and 'response' thread types which are posted by staff members, the 'email' thread type is associated with a user (either the ticket owner or a specified user).
+
+```json
+POST /api/tickets/123/add_thread.json
+X-API-Key: 184F66085DA76CDF5300FE2C6E229238
+Content-Type: application/json
+
+{
+  "thread_type": "email",
+  "message": "Thank you for your response. I have another question...",
+  "userId": 5,
+  "attachments": [
+    {
+      "name": "screenshot.png",
+      "type": "image/png",
+      "data": "iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAYAAADgdz34AAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAApgAAAKYB3X3/OAAAABl0RVh0U...",
+      "encoding": "base64"
+    }
+  ]
+}
+```
+
 ### Response
 
 Upon successful creation of a thread entry, the API will respond with a 201 Created status and a JSON or XML response containing details about the created thread.
 
-JSON Response Example:
+#### JSON Response Example for Staff Entry (note/response):
 ```json
 {
   "ticket_id": 123,
@@ -154,6 +184,34 @@ JSON Response Example:
 }
 ```
 
+#### JSON Response Example for Client/User Reply (email):
+```json
+{
+  "ticket_id": 123,
+  "ticket_number": "ABC-123-4567",
+  "thread_id": 457,
+  "thread_type": "email",
+  "message_id": "<def456@osticket.com>",
+  "timestamp": "2023-05-24 11:15:00",
+  "current_status": {
+    "id": 1,
+    "name": "Open",
+    "state": "open"
+  },
+  "user": {
+    "id": 5,
+    "name": "John Doe",
+    "email": "johndoe@example.com"
+  },
+  "attachments": [
+    {
+      "id": 790,
+      "name": "screenshot.png"
+    }
+  ]
+}
+```
+
 ### Error Responses
 
 The API will return appropriate HTTP status codes for different error conditions: