List Conversations

List and filter conversations. Use the thread resource link inside the Conversation entity to load conversation threads.

Request

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

Request parameters can be used to filter conversations. All parameters are joined by the AND operator. If you want closed conversations in a specific mailbox, call:


curl https://api.helpscout.net/v2/conversations?mailbox=123&status=closed

You can also exclude data from your search results using the NOT operator, calling:


curl https://api.helpscout.net/v2/conversations?query=(NOT email:“email@domain.com”)

By default only active conversations are listed and they are sorted by createdAt (from newest to oldest). This is equivalent to ?status=active&sortField=createdAt&sortOrder=desc. If you want to list all conversations, use ?status=all

Note: If using the embed=threads parameter with this call, you will see truncated chat threads. This is by design. To view Beacon chat threads in full, call the List Threads endpoint for that conversation instead.

URL Parameters

Parameter Type Examples Description
embed enumeration embed=threads
Allows embedding/loading of sub-entities, allowed values are:
threads
mailbox number mailbox=123
mailbox=123,567
 Filters conversations from a specific mailbox id. Use comma separated values for more mailboxes
folder number folder=993
 Filters conversations from a specific folder id
status enumeration status=active
 Filter conversation by status (defaults to active):
active
all
closed
open
pending
spam
tag string tag=red
tag=red,blue
 Filter conversation by tags. Use comma separated values for more tags
assigned_to number assigned_to=1771
 Filters conversations by assignee id
modifiedSince date modifiedSince=2018-05-04T12:00:03Z
 Filters conversations modified after this timestamp
number number number=123
 Looks up conversation by conversation number
sortField enumeration sortField=createdAt
 Sorts the result by specified field:
createdAt
customerEmail
customerName
mailboxid
modifiedAt
number
score
status
subject
waitingSince
sortOrder enumeration sortOrder=desc
 Sort order, either desc or asc, default is desc
query special query=(number:123)
 Advanced search query. If you use other filtering request parameters, they will be combined with AND operator.For example ?mailbox=567&query=tag:fire effectively means mailbox=567 AND tag=fire.
page number page=1
 Page number
customFieldsByIds special customFieldsByIds=123:blue
customFieldsByIds=123:blue,234:99
 Filters conversations by custom fields, using custom field IDs. This filter must be accompanied by mailbox parameter as well.
Expected format is id:value,id:value

See Custom Fields Search for details

customFieldsByIds

This is a fairly low level search - the values are expected in a fieldId:value format and you can either

  • use multiple customFieldsByIds params like this ?customFieldsByIds=123:green&customFieldsByIds=234:blue
  • or join the values yourself: ?customFieldsByIds=123:green,234:blue.

Rules:

  • the filtering is done via an exact match for all field types with the exception of single line text field - for example a custom field with a number type and ID 123 with the following filter of 123:1000 will only match if the value is precisely 1000
  • single line text fields are searched in full text search manner
  • multiple filters use AND operator - all custom fields filters must match
  • for Dropdown custom field type the value is the dropdown option ID (you can use Mailbox Fields endpoint to fetch all IDs)
  • Multiline custom fields are not supported

Query

You can create complex search queries by combining operators:

?query=(assigned:"spock" AND (customerIds: 123 OR customerIds: 567))

Some characters (particularly + signs in email addresses) are reserved and will need to be encoded. For more info, see this article.

Subject

Example What it does
query=(subject:"rainbow") Searches for conversation subjects that contain the word “rainbow”
query=(subject:"have a question") Searches for conversation subjects that contain the phrase “have a question” (not case sensitive)
query=(subject:"coffee" OR subject:"tea") Searches for conversations with a subject that contain the word “coffee” or the word “tea”
query=(subject:"coffee tea") Searches for conversation subjects that contain the word “coffee” and the word “tea” in no particular order

Tags

Example What it does
query=(tag:"carrots") Searches for conversations that have the tag “carrots”
query=(tag:"dogs love carrots") Searches for conversations that have the tag “dogs love carrots”
query=(tag:"dogs" OR tag:"carrots") Searches for conversations that are tagged with either “dogs” or “carrots”

Mailbox

Example What it does
query=(mailbox:"Orders") Searches the “Orders” mailbox by exact match
query=(mailboxid:100) Searches the mailbox with an id of 100

Modified At

Example What it does
query=(modifiedAt:[2014-02-27T00:00:00Z TO *]) Searches conversations that have been modified since 2014-02-27
query=(modifiedAt:[2014-02-27T00:00:00Z TO 2014-02-27T23:59:59Z]) Searches conversations that were modified on 2014-02-27
query=(modifiedAt:[NOW-1HOUR TO *]) Searches conversations that were modified in the last hour
query=(modifiedAt:[2013-01-01T00:00:00Z TO 2013-12-31T23:59:59Z]) Searches conversations that were modified in 2013
query=(modifiedAt:[2014 TO 2014-12-01]) Searches conversations that were modified from the start of 2014 to the beginning of December, 2014
query=(modifiedAt:2000-11) Searches conversations that were modified in November, 2000

Created At

Example What it does
query=(createdAt:[2014-02-27T00:00:00Z TO *]) Searches conversations that have been created since 2014-02-27
query=(createdAt:[2014-02-27T00:00:00Z TO 2014-02-27T23:59:59Z]) Searches conversations that were created on 2014-02-27
query=(createdAt:[NOW-1HOUR TO *]) Searches conversations that were created in the last hour
query=(createdAt:[2013-01-01T00:00:00Z/YEAR TO 2014-01-01T00:00:00Z/YEAR]) Searches conversations that were created in 2013

Email

Example What it does
query=(email:"john@appleseed.com") Searches conversations where the mailjohn@appleseed.com is either in to, cc, bcc fields or it’s one of the emails in a customer profile.
query=(email:(john@appleseed.com OR vbear@mywork.com)) Searches conversations using the fields mentioned above, but returns results for multiple emails or customers

Body

Example What it does
query=(body:"what a beautiful day") Searches conversation threads for the phrase, “what a beautiful day”
query=(body:"what a day" OR body:"how about tomorrow") Searches conversation threads for the phrases “what a day” or “how about tomorrow”

Other

Example What it does
query=(customerIds:100) Returns conversations (across all mailboxes) belonging to the given customer
query=(number:1234) Searches for conversation #1234
query=(id:123456) Searches for the unique conversation ID
query=(assigned:"spock") Searches for conversations assigned to Spock
query=(attachments:true) Searches for conversations with attachments
query=(assigned:"Unassigned") Searches for unassigned conversations

Response

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

{
  "_embedded" : {
    "conversations" : [ {
      "id" : 10,
      "number" : 12,
      "threads" : 2,
      "type" : "email",
      "folderId" : 11,
      "status" : "closed",
      "state" : "published",
      "subject" : "Help",
      "preview" : "Preview",
      "mailboxId" : 13,
      "assignee" : {
        "id" : 99,
        "type" : "user",
        "first" : "Mr",
        "last" : "Robot",
        "email" : "none@nowhere.com"
      },
      "createdBy" : {
        "id" : 12,
        "type" : "customer",
        "email" : "bear@acme.com"
      },
      "createdAt" : "2012-03-15T22:46:22Z",
      "closedBy" : 14,
      "closedByUser" : {
        "id" : 14,
        "type" : "user",
        "first" : "Clo",
        "last" : "Ser",
        "photoUrl" : "pic.jpg",
        "email" : "closer@closers.com"
      },
      "closedAt" : "2012-03-16T14:07:23Z",
      "userUpdatedAt" : "2012-03-16T14:07:23Z",
      "customerWaitingSince" : {
        "time" : "2012-07-24T20:18:33Z",
        "friendly" : "20 hours ago"
      },
      "source" : {
        "type" : "email",
        "via" : "customer"
      },
      "tags" : [ {
        "id" : 9150,
        "color" : "#929499",
        "tag" : "vip"
      } ],
      "cc" : [ "bear@normal.com" ],
      "bcc" : [ "bear@secret.com" ],
      "primaryCustomer" : {
        "id" : 238604,
        "type" : "customer",
        "first" : "Rob",
        "last" : "Robertovic",
        "email" : "rob@acme.com"
      },
      "snooze" : {
        "snoozedBy" : 4,
        "snoozedUntil" : "2024-06-03T12:00:00Z",
        "unsnoozeOnCustomerReply" : true
      },
      "nextEvent" : {
        "time" : "2024-06-03T12:00:00Z",
        "eventType" : "snooze",
        "userId" : 4,
        "cancelOnCustomerReply" : true
      },
      "customFields" : [ {
        "id" : 8,
        "name" : "Account Type",
        "value" : "8518",
        "text" : "Free"
      }, {
        "id" : 6688,
        "name" : "Account Status",
        "value" : "33077",
        "text" : "Trial"
      } ],
      "_embedded" : {
        "threads" : [ ]
      },
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "mailbox" : {
          "href" : "..."
        },
        "primaryCustomer" : {
          "href" : "..."
        },
        "createdByCustomer" : {
          "href" : "..."
        },
        "closedBy" : {
          "href" : "..."
        },
        "threads" : {
          "href" : "..."
        },
        "assignee" : {
          "href" : "..."
        },
        "web" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "self" : {
      "href" : "..."
    },
    "first" : {
      "href" : "..."
    },
    "last" : {
      "href" : "..."
    },
    "page" : {
      "href" : "...",
      "templated" : true
    }
  },
  "page" : {
    "size" : 25,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

Response fields

Path Type Description
_embedded.conversations Array Conversation objects
↑Back to top
© Help Scout 2024