Search for conversations

You can search for multiple conversations by the value of their attributes in order to fetch exactly which ones you want.

To search for conversations, you need to send a POST request to https://api.intercom.io/conversations/search. This will accept a query object in the body which will define your filters in order to search for conversations.

Search with single filter

You should provide the following parameters within a query object:

Parameter	Required?	Description
field	Yes	The fields associated to a conversation that you can search for. See all accepted fields.
operator	Yes	The operator that you want to compare by. See all accepted operators below.
value	Yes	The value you want to search by.

Search with multiple filters

You can search with multiple filters by combining a list of single filter objects within a value array and saying whether you want to ensure all given values match (AND), or only one of these match (OR). The query object should contain these parameters.

Parameter	Required?	Description
operator	Yes	The operator (`AND` or `OR`) by which to query the combined values.
value	Yes	An array of single query objects.

Only checking if one value matches?

If you're only using OR to check that one matches out of the values, you could instead use IN as the operator in a single filter query. You could also use NIN to say that it does not match one of the values.

Nesting & Limitations

You can nest these filters in order to get even more granular insights that pinpoint exactly what you need. Example: (1 OR 2) AND (3 OR 4).\There are some limitations to the amount of multiple's there can be:\_ There's a limit of max 2 nested filters_ There's a limit of max 15 filters for each AND or OR group

Outbound Messages vs Conversations

By default, an outbound message will not be considered part of a conversation until the contact responds. This means that outbound messages will not appear in the search results for this endpoint unless the contact has replied.\Messages can be created to be part of a conversation immediately via the Create a Message endpoint and setting the create_conversation_without_contact_reply to true.

Example Request (Single Filter)

Request

{ \"query\":  {    \"field\": \"updated_at\",    \"operator\": \">\",    \"value\": 1560436784  }}

Example Request (Multiple Filters)

{ \"query\":  {    \"operator\": \"AND\",    \"value\": [      {        \"field\": \"statistics.time_to_admin_reply\",        \"operator\": \">\",        \"value\": 1000      },       {        \"field\": \"admin_assignee_id\",        \"operator\": \"=\",        \"value\": \"1627383\"      },      {        \"field\": \"open\",        \"operator\": \"=\",        \"value\": true      }    ]  }}

{ \"query\":  {    \"field\": \"tags\",    \"operator\": \"IN\",    \"value\": [\"feature-request\", \"bug\", \"confusion\"]  }}

Example Request (Nested Filters)

Request

{ \"query\":  {    \"operator\": \"AND\",    \"value\": [      {        \"operator\": \"OR\",        \"value\": [          {            \"field\": \"updated_at\",            \"operator\": \">\",            \"value\": 1560436650          },           {            \"field\": \"conversation_rating.rating\",            \"operator\": \"=\",            \"value\": 1          }        ]      },      {        \"operator\": \"OR\",        \"value\": [          {            \"field\": \"updated_at\",            \"operator\": \">\",            \"value\": 1560436650          },           {            \"field\": \"conversation_rating.rating\",            \"operator\": \"=\",            \"value\": 2          }        ]      }    ]  }}

Example Errors

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": null,
  "errors": [
      {
        "code": "bad_request",
        "message": "bad 'random_param' parameter"
      }
  ]
}

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": null,
  "errors": [
    {
      "code": "invalid_query",
      "message": "Invalid query. Ensure 'field', 'operator', 'value' are present for field queries. Ensure 'operator' and 'value' for composite queries."
    }
  ]
}

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": null,
  "errors": [
    {
      "code": "invalid_value",
      "message": "123 is not a valid string"
    }
  ]
}

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": null,
  "errors": [
    {
      "code": "invalid_field",
      "message": "not_a_field is not a valid field"
    }
  ]
}

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": null,
  "errors": [
    {
      "code": "invalid_values",
      "message": "Value depth exceeds 10 items"
    }
  ]
}

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": null,
  "errors": [
    {
      "code": "invalid_value",
      "message": "Number of elements in composite query is greater than 15, please try again with a smaller list"
    }
  ]
}

HTTP/1.1 400 BAD REQUEST
{
  "type": "error.list",
  "request_id": null,
  "errors": [
    {
      "code": "invalid_operator",
      "message": "Composite operators must be of type AND or OR "
    }
  ]
}

Accepted Fields

Most keys listed as part of the The conversation model is searchable, whether writeable or not. The value you search for has to match the accepted type, otherwise the query will fail (ie. as created_at accepts a date, the value cannot be a string such as "foorbar").

Field	Type
id	String
created_at	Date (UNIX timestamp)
updated_at	Date (UNIX timestamp)
source.type	String
source.id	String
source.delivered_as	String
source.subject	String
source.body	String
source.author.id	String
source.author.type	String
source.author.name	String
source.author.email	String
source.url	String
contact_ids	String
teammate_ids	String
admin_assignee_id	String
team_assignee_id	String
channel_initiated	String Accepted fields are `conversation`, `push`, `facebook`, `twitter` and `email`.
open	Boolean
read	Boolean
state	String
waiting_since	Date (UNIX timestamp)
snoozed_until	Date (UNIX timestamp)
tag_ids	String
priority	String
statistics.time_to_assignment	Integer
statistics.time_to_admin_reply	Integer
statistics.time_to_first_close	Integer
statistics.time_to_last_close	Integer
statistics.median_time_to_reply	Integer
statistics.first_contact_reply_at	Date (UNIX timestamp)
statistics.first_assignment_at	Date (UNIX timestamp)
statistics.first_admin_reply_at	Date (UNIX timestamp)
statistics.first_close_at	Date (UNIX timestamp)
statistics.last_assignment_at	Date (UNIX timestamp)
statistics.last_assignment_admin_reply_at	Date (UNIX timestamp)
statistics.last_contact_reply_at	Date (UNIX timestamp)
statistics.last_admin_reply_at	Date (UNIX timestamp)
statistics.last_close_at	Date (UNIX timestamp)
statistics.last_closed_by_id	String
statistics.count_reopens	Integer
statistics.count_assignments	Integer
statistics.count_conversation_parts	Integer
conversation_rating.requested_at	Date (UNIX timestamp)
conversation_rating.replied_at	Date (UNIX timestamp)
conversation_rating.score	Integer
conversation_rating.remark	String
conversation_rating.contact_id	String
conversation_rating.admin_d	String

Accepted Operators

The table below shows the operators you can use to define how you want to search for the value. The operator should be put in as a string ("="). The operator has to be compatible with the field's type (eg. you cannot search with > for a given string value as it's only compatible for integer's and dates).

Operator	Valid Types	Description
=	All	Equals
!=	All	Doesn't Equal
IN	All	In Shortcut for `OR` queries Values most be in Array
NIN	All	Not In Shortcut for `OR !` queries Values must be in Array
>	Integer Date (UNIX Timestamp)	Greater (or equal) than
<	Integer Date (UNIX Timestamp)	Lower (or equal) than
~	String	Contains
!~	String	Doesn't Contain
^	String	Starts With
$	String	Ends With

Response

A JSON payload with a list of Conversations Model that match the search query, with a total_count integer saying how many models have been returned.

Search for conversations

Search with single filter

Search with multiple filters

Example Request (Single Filter)

Request

Example Request (Multiple Filters)

Example Request (Nested Filters)

Request

Example Errors

Accepted Fields

Accepted Operators

Response

Was this page helpful?