Search conversations

Request

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.

Optimizing search queries

Search queries can be complex, so optimizing them can help the performance of your search. Use the AND and OR operators to combine multiple filters to get the exact results you need and utilize pagination to limit the number of results returned. The default is 20 results per page and maximum is 150. See the pagination section for more details on how to use the starting_after param.

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

Accepted Fields

Most keys listed in the conversation model are 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"). The source.body field is unique as the search will not be performed against the entire value, but instead against every element of the value separately. For example, when searching for a conversation with a "I need support" body - the query should contain a = operator with the value "support" for such conversation to be returned. A query with a = operator and a "need support" value will not yield a result.

Field	Type
id	Integer
type	String
created_at	Date (Unix timestamp in seconds)
updated_at	Date (Unix timestamp in seconds)
source.type	String Accepted fields are `conversation`, `email`, `facebook`, `instagram`, `phone_call`, `phone_switch`, `push`, `sms`, `twitter` and `whatsapp`.
source.id	Integer
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	Integer
team_assignee_id	Integer
channel_initiated	String
open	Boolean
read	Boolean
state	String
waiting_since	Date (Unix timestamp in seconds)
snoozed_until	Date (Unix timestamp in seconds)
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 in seconds)
statistics.first_assignment_at	Date (Unix timestamp in seconds)
statistics.first_admin_reply_at	Date (Unix timestamp in seconds)
statistics.first_close_at	Date (Unix timestamp in seconds)
statistics.last_assignment_at	Date (Unix timestamp in seconds)
statistics.last_assignment_admin_reply_at	Date (Unix timestamp in seconds)
statistics.last_contact_reply_at	Date (Unix timestamp in seconds)
statistics.last_admin_reply_at	Date (Unix timestamp in seconds)
statistics.last_close_at	Date (Unix timestamp in seconds)
statistics.last_closed_by_id	Integer
statistics.count_reopens	Integer
statistics.count_assignments	Integer
statistics.count_conversation_parts	Integer
conversation_rating.requested_at	Date (Unix timestamp in seconds)
conversation_rating.replied_at	Date (Unix timestamp in seconds)
conversation_rating.score	Integer
conversation_rating.remark	String
conversation_rating.contact_id	String
conversation_rating.admin_id	String
ai_agent_participated	Boolean
ai_agent.resolution_state	String
ai_agent.last_answer_type	String
ai_agent.rating	Integer
ai_agent.rating_remark	String
ai_agent.source_type	String
ai_agent.source_title	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 in seconds)	Greater than
>=	Integer Date (Unix timestamp in seconds)	Greater than or equal to
<	Integer Date (Unix timestamp in seconds)	Lower than
<=	Integer Date (Unix timestamp in seconds)	Lower than or equal to
~	String	Contains
!~	String	Doesn't Contain
^	String	Starts With
$	String	Ends With

Tickets are only included in the results if the access token has the read_tickets scope. Without it, tickets are left out and no error is returned.

Sorting

Results are sorted by updated_at, newest first. To sort differently, add a sort object to the request body with a field and an order of ascending or descending. field is required whenever sort is sent, and must be one of the fields in the table above, other than type, state, source.subject, source.body, source.author.id, source.author.type, source.author.name, source.author.email, conversation_rating.remark, ai_agent.rating_remark and ai_agent.source_title, which can't be sorted. A missing field, or one that isn't searchable, returns a 400 error with the code invalid_field.

Security

bearerAuth

Query

include_monitorsboolean

If set to true, the response will include a monitor_evaluations array on each conversation with the latest QA monitor evaluation for each monitor that has evaluated it.

Default:false

Example:include_monitors=true

include_scorecardsboolean

If set to true, the response will include a scorecards array on each conversation with any QA scorecard results.

Default:false

Example:include_scorecards=true

Intercom-Versionstring(intercom_version)

Intercom API version.
If you omit the header, the API uses the version set in your app package, and 1.0 if none is set.

Enum:"1.0""1.1""1.2""1.3""1.4""2.0""2.1""2.2""2.3""2.4"

Example:Preview

Bodyapplication/json

querySingle filter search request (object) or multiple filter search request (object)required

One of:

Search using Intercoms Search APIs with a single filter.

paginationobject or null(Pagination: Starting After)

sortobject

How to sort the results. Without it, the endpoint's default order is used.

curl -i -X POST \
  'https://api.intercom.io/conversations/search?include_monitors=true&include_scorecards=true' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Intercom-Version: Preview' \
  -d '{
    "query": {
      "operator": "AND",
      "value": [
        {
          "field": "created_at",
          "operator": ">",
          "value": "1306054154"
        }
      ]
    },
    "pagination": {
      "per_page": 5
    }
  }'

Responses

successful

Bodyapplication/json

typestring

Always conversation.list

Value:"conversation.list"

Example:"conversation.list"

conversationsArray of objects(Conversation List Item)

The list of conversation objects

total_countinteger

A count of the total number of objects.

Example:12345

pagesobject or null(Cursor based pages)

Cursor-based pagination is a technique used in the Intercom API to navigate through large amounts of data. A "cursor" or pointer is used to keep track of the current position in the result set, allowing the API to return the data in small chunks or "pages" as needed.

Response

{
  "type": "conversation.list",
  "pages": {
    "type": "pages",
    "page": 1,
    "per_page": 5,
    "total_pages": 1
  },
  "total_count": 1,
  "conversations": [
    { … }
  ]
}