List Threads

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

Request

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

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "_embedded" : {
    "threads" : [ {
      "id" : 1234,
      "type" : "customer",
      "status" : "active",
      "state" : "published",
      "action" : {
        "type" : "manual-workflow",
        "text" : "You ran the Assign to Spam workflow"
      },
      "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" : "customer",
        "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",
      "_embedded" : {
        "attachments" : [ {
          "id" : 1234,
          "filename" : "photo1.jpg",
          "mimeType" : "image/jpeg",
          "width" : 600,
          "height" : 800,
          "size" : 20191,
          "_links" : {
            "data" : {
              "href" : "..."
            },
            "self" : {
              "href" : "..."
            }
          }
        } ]
      },
      "_links" : {
        "assignedTo" : {
          "href" : "..."
        },
        "createdByCustomer" : {
          "href" : "..."
        },
        "customer" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "..."
    },
    "last" : {
      "href" : "..."
    },
    "page" : {
      "href" : "...",
      "templated" : true
    },
    "self" : {
      "href" : "..."
    }
  },
  "page" : {
    "size" : 50,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

Moved or merged conversations

When a conversation is moved to a new mailbox or it is merged with another conversation, it is no longer accessible using the old ID. Get Conversation 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 moved or merged, call the Get Conversation endpoint to get a new conversation location.

Response fields

Path Type Description
[].id Number Unique identifier
[].assignedTo Object The user assigned to this thread.
[].status String Thread status, possible values:
active
closed
nochange
pending
spam
[].state String Thread state, possible values:
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
[].body String Thread text content
[].source.type String Source of the thread
[].source.via String Who created the thread - 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 will specify whether it was created by a user or a customer.
[].savedReplyId Number ID of Saved reply that was used to create this Thread
[].type String Thread type, possible 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.

Thread Type

lineitem represents a change of state on the conversation. This could include, but not limited to, the conversation was assigned, the status changed, the conversation was moved from one mailbox to another, etc. A line item won’t have a body, to/cc/bcc lists, or attachments. When a conversation is forwarded, a new conversation is created to represent the forwarded conversation.

forwardparent is the type set on the thread of the original conversation that initiated the forward event.

forwardchild is the type set on the first thread of the new forwarded conversation.

Thread State

A state of underreview means the thread has been stopped by Traffic Cop and is waiting to be confirmed (or discarded) by the person that created the thread.

A state of hidden means the thread was hidden (or removed) from customer-facing emails.

Thread Status

Thread status is only updated when there is a status change. Otherwise, the status will be set to nochange.