List Threads (v3)

The v3 endpoint returns the real type value for createdBy and assignedTo fields — including system_user for AI-powered system users. The v2 endpoint normalizes system_user to user for backward compatibility.

Threads are by default sorted by createdAt (from newest to oldest).

Request

GET /v3/conversations/123/threads HTTP/1.1
Authorization: Bearer oauth_token

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_embedded" : {
    "threads" : [ {
      "id" : 1234,
      "type" : "customer",
      "status" : "active",
      "state" : "published",
      "action" : {
        "type" : "manual-workflow",
        "text" : "You ran the Assign to Spam workflow",
        "associatedEntities" : { }
      },
      "body" : "this is what i have to say: I love your service.",
      "source" : {
        "type" : "email",
        "via" : "customer"
      },
      "customer" : {
        "id" : 29418,
        "first" : "Vernon",
        "last" : "Bear",
        "photoUrl" : "http://whatever-path-to-url/image.jpg",
        "email" : "vbear@mywork.com"
      },
      "createdBy" : {
        "id" : 29418,
        "type" : "system_user",
        "first" : "Vernon",
        "last" : "Bear",
        "photoUrl" : "http://whatever-path-to-url/image.jpg",
        "email" : "vbear@mywork.com"
      },
      "assignedTo" : {
        "id" : 1234,
        "type" : "team",
        "first" : "Jack",
        "last" : "Sprout",
        "email" : "jack.sprout@gmail.com"
      },
      "savedReplyId" : 10,
      "to" : [ "to1@somewhere.com", "to2@somewhere.com" ],
      "cc" : [ "cc1@somewhere.com", "cc2@somewhere.com" ],
      "bcc" : [ "bcc1@somewhere.com", "bcc2@somewhere.com" ],
      "createdAt" : "2015-06-05T20:18:33Z",
      "openedAt" : "2015-06-07T10:01:25Z",
      "rating" : {
        "customerId" : 1234,
        "rating" : "great",
        "comments" : "Great job!"
      },
      "scheduled" : {
        "scheduledBy" : 4,
        "createdAt" : "2024-06-10T10:20:30Z",
        "scheduledFor" : "2034-06-10T10:20:30Z",
        "unscheduleOnCustomerReply" : false
      },
      "_embedded" : {
        "attachments" : [ {
          "id" : 1234,
          "filename" : "photo1.jpg",
          "mimeType" : "image/jpeg",
          "width" : 600,
          "height" : 800,
          "size" : 20191,
          "state" : "valid",
          "_links" : {
            "self" : {
              "href" : "..."
            },
            "data" : {
              "href" : "..."
            },
            "web" : {
              "href" : "...",
              "deprecation" : "Deprecated in favor of the download endpoint."
            },
            "download" : {
              "href" : "..."
            }
          }
        } ]
      },
      "_links" : {
        "assignedTo" : {
          "href" : "..."
        },
        "createdByUser" : {
          "href" : "..."
        },
        "customer" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "first" : {
      "href" : "..."
    },
    "last" : {
      "href" : "..."
    },
    "page" : {
      "href" : "...",
      "templated" : true
    }
  },
  "page" : {
    "size" : 25,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

Moved or merged conversations

When a conversation is merged with another conversation, it is no longer accessible using the old ID. Get Conversation (v3) endpoint will return a HTTP 301 Moved Permanently status code and the response will contain a Location header with the URI of the new conversation.

This request will return a HTTP 404 Not Found in such case. If you suspect the conversation you are trying to change was merged, call the Get Conversation (v3) endpoint to get a new conversation location.

Response fields

Path Type Description
.id Number Unique identifier
assignedTo Object The user or system user assigned to this thread. The type property can be user, team, or system_user
status String Thread status, accepted values:
active
closed
pending
spam
state String Thread state, accepted values:
bounced
draft
hidden
published
review
.action.type String Internal action type
.action.text String Human friendly description of the action. Applicable for thread type lineitem only
.action.associatedEntities Object Contains IDs of entities associated with the action: workflow, user, inbox, originalConversation.
body String Thread text content
source.type String Originating type of the thread, one of:
api
beacon
channel
chat
consumer
coreapi
csv
cvs
desk
docs
email
emailfwd
heymarket
internal
jira
manual
mobile
notification
orchestration
support
unknown
uservoice
web
workflows
zendesk
source.via String Originating source of the thread, one of:
user
customer
customer Object If thread type is message, this is the customer associated with the conversation. If thread type is customer, this is the the customer who initiated the thread.
createdBy Object Who created this thread. The type property can be user, customer, or system_user.
savedReplyId Number ID of Saved reply that was used to create this Thread
type String Thread type, accepted values:
beaconchat
chat
customer
forwardchild
forwardparent
lineitem
message
note
phone
to Array Email address from the to: field
cc Array Email address from the cc: field
bcc Array Email address from the bcc: field
createdAt String Creation date
openedAt String When this thread was viewed by the customer. Only applies to threads with a type of message.
linkedConversationId String The parent or child conversation ID/identifier for a forwarded conversation
rating Object Customer-provided Rating details for the thread. Only applies to threads with a type of message.
scheduled Object Schedule details
_embedded.attachments Array Conversation attachments

Rating Response Fields

Response fields

Path Type Description
customerId Number The ID of the customer who provided the rating
rating String Rating enumeration, one of great, not_good, okay
comments String Optional comment left by the customer

Schedule Response Fields

Response fields

Path Type Description
scheduledBy Number User ID that scheduled the thread
sendAsId Number Original draft author that will be used for sending the scheduled thread.
createdAt String When the thread was scheduled (ISO 8601 date string)
scheduledFor String When the thread will be sent (ISO 8601 date string)
unscheduleOnCustomerReply Boolean Whether a new customer reply should automatically unschedule the thread.

Attachment Response Fields

Response fields

Path Type Description
[].id Number Unique identifier
[].filename String File name
[].mimeType String Mime type
[].width Number Width in pixels - not guaranteed to be present
[].height Number Height in pixels - not guaranteed to be present
[].size Number Size in bytes - not guaranteed to be present
[].state String Attachment state, accepted values:
valid
virus
Relation Description
web Link to the attachment in the web application for easier download. Deprecated in favor of “download” link.
data Link to Get Data endpoint
download Link to download an attachment file endpoint

Person type values

Type Description
user A regular Help Scout user
customer A customer
team A team
system_user A system user (e.g. AI agent)
↑Back to top