v51

latestOpenAPI 3.0.1MITraw.githubusercontent.com2026-08-01150230854.3 KB

Conversations

Search 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. {% admonition type="warning" name="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. {% /admonition %}

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	String
created_at	Date (UNIX timestamp)
updated_at	Date (UNIX timestamp)
source.type	String<br>Accepted fields are conversation, email, facebook, instagram, phone_call, phone_switch, push, sms, twitter and whatsapp.
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	Integer
team_assignee_id	Integer
channel_initiated	String
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
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)	Greater (or equal) than
<	Integer Date (UNIX Timestamp)	Lower (or equal) than
~	String	Contains
!~	String	Doesn't Contain
^	String	Starts With
$	String	Ends With

post/conversations/search

Headers

Intercom-Version'1.0' | '1.1' | '1.2' | '1.3' | '1.4' | '2.0' | '2.1' | '2.2' | '2.3' | '2.4' | '2.5' | '2.6' | '2.7' | '2.8' | '2.9' | '2.10' | '2.11' | '2.12' | '2.13' | '2.14'

Intercom API version.</br>By default, it's equal to the version set in the app package.

Example:2.14

Request body

Example request

{
  "query": {
    "field": "created_at",
    "operator": ">"
  },
  "pagination": {
    "per_page": 2,
    "starting_after": "your-cursor-from-response"
  }
}

Response

successful

type'conversation.list'

Always conversation.list

total_countinteger

A count of the total number of objects.

Example response

{
  "type": "conversation.list",
  "conversations": [
    {
      "type": "conversation",
      "id": "1295",
      "title": "Conversation Title",
      "created_at": 1663597223,
      "updated_at": 1663597260,
      "waiting_since": 1663597260,
      "snoozed_until": 1663597260,
      "open": true,
      "state": "open",
      "read": true,
      "priority": "priority",
      "team_assignee_id": 5017691,
      "tags": {
        "type": "tag.list",
        "tags": [
          {
            "type": "tag",
            "id": "123456",
            "name": "Test tag",
            "applied_at": 1663597223,
            "applied_by": {
              "type": "contact",
              "id": "1a2b3c"
            }
          }
        ]
      },
      "conversation_rating": {
        "rating": 5,
        "created_at": 1671028894,
        "updated_at": 1671028894,
        "contact": {
          "type": "contact",
          "id": "5ba682d23d7cf92bef87bfd4",
          "external_id": "70"
        },
        "teammate": {
          "type": "contact",
          "id": "1a2b3c"
        }
      },
      "source": {
        "type": "conversation",
        "id": "3",
        "delivered_as": "operator_initiated",
        "body": "<p>Hey there!</p>",
        "author": {
          "type": "admin",
          "id": "274",
          "name": "Operator",
          "email": "operator+abcd1234@intercom.io",
          "from_ai_agent": true
        },
        "attachments": [
          {
            "type": "upload",
            "name": "example.png",
            "url": "https://picsum.photos/200/300",
            "content_type": "image/png",
            "filesize": 100,
            "width": 100,
            "height": 100
          }
        ]
      },
      "contacts": {
        "type": "contact.list",
        "contacts": [
          {
            "type": "contact",
            "id": "5ba682d23d7cf92bef87bfd4",
            "external_id": "70"
          }
        ]
      },
      "teammates": {
        "type": "admin.list",
        "teammates": [
          {
            "type": "contact",
            "id": "1a2b3c"
          }
        ]
      },
      "custom_attributes": {
        "paid_subscriber": true,
        "monthly_spend": 155.5,
        "team_mates": 9,
        "start_date_iso8601": "2023-03-04T09:46:14Z",
        "end_date_timestamp": 1677923174,
        "CX Score rating": 4,
        "CX Score explanation": "The conversation was resolved quickly and the customer expressed satisfaction with the outcome."
      },
      "first_contact_reply": {
        "created_at": 1663597223,
        "type": "conversation",
        "url": "https://developers.intercom.com/"
      },
      "sla_applied": {
        "type": "conversation_sla_summary",
        "sla_status": "hit"
      },
      "statistics": {
        "type": "conversation_statistics",
        "time_to_assignment": 2310,
        "time_to_admin_reply": 2310,
        "time_to_first_close": 2310,
        "time_to_last_close": 2310,
        "median_time_to_reply": 2310,
        "first_contact_reply_at": 1663597233,
        "first_assignment_at": 1663597233,
        "first_admin_reply_at": 1663597233,
        "first_close_at": 1663597233,
        "last_assignment_at": 1663597233,
        "last_assignment_admin_reply_at": 1663597233,
        "last_contact_reply_at": 1663597233,
        "last_admin_reply_at": 1663597233,
        "last_close_at": 1663597233,
        "last_closed_by_id": "c3po",
        "count_reopens": 1,
        "count_assignments": 1,
        "count_conversation_parts": 1,
        "assigned_team_first_response_time": [
          {
            "team_id": 100,
            "team_name": "Team One",
            "response_time": 2310
          }
        ],
        "assigned_team_first_response_time_in_office_hours": [
          {
            "team_id": 100,
            "team_name": "Team One",
            "response_time": 2310
          }
        ],
        "handling_time": 2310,
        "adjusted_handling_time": 1800
      },
      "linked_objects": {
        "type": "list",
        "total_count": 100,
        "data": [
          {
            "type": "ticket",
            "id": "7583",
            "category": "Customer"
          }
        ]
      },
      "ai_agent_participated": true,
      "ai_agent": {
        "source_type": "workflow",
        "source_title": "My AI Workflow",
        "last_answer_type": "ai_answer",
        "resolution_state": "assumed_resolution",
        "rating": 4,
        "rating_remark": "Very helpful!",
        "created_at": 1663597260,
        "updated_at": 1663597260,
        "content_sources": {
          "type": "content_source.list",
          "total_count": 1,
          "content_sources": [
            {
              "content_type": "content_snippet",
              "url": "/fin-ai-agent/content?content=content_snippet&id=3234924",
              "title": "My internal content snippet",
              "locale": "en"
            }
          ]
        }
      }
    }
  ],
  "total_count": 12345,
  "pages": {
    "type": "pages",
    "page": 1,
    "next": {
      "per_page": 2,
      "starting_after": "your-cursor-from-response"
    },
    "per_page": 2,
    "total_pages": 13
  }
}