---
title: "List all conversations"
method: GET
path: "/conversations"
tags: ["Conversations"]
---

# List all conversations

`GET /conversations`

You can fetch a list of all conversations.

You can optionally request the result page size and the cursor to start after to fetch the result.
{% admonition type="warning" name="Pagination" %}
  You can use pagination to limit the number of results returned. The default is `20` results per page.
  See the [pagination section](https://developers.intercom.com/docs/build-an-integration/learn-more/rest-apis/pagination/#pagination-for-list-apis) for more details on how to use the `starting_after` param.
{% /admonition %}

## Query parameters

- `per_page` integer
- `starting_after` string

## 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.

## Response `200`

successful

- ConversationList — Conversations are how you can communicate with users in Intercom. They are created when a contact replies to an outbound message, or when one admin directly sends a message to a single contact.
  - `type` 'conversation.list' — Always conversation.list
  - `conversations` ConversationListItem[] — The list of conversation objects
    - `type` string — Always conversation.
    - `id` string — The id representing the conversation.
    - `title` string, nullable — The title given to the conversation.
    - `created_at` integer — The time the conversation was created.
    - `updated_at` integer — The last time the conversation was updated.
    - `waiting_since` integer, nullable — The last time a Contact responded to an Admin. In other words, the time a customer started waiting for a response. Set to null if last reply is from an Admin.
    - `snoozed_until` integer, nullable — If set this is the time in the future when this conversation will be marked as open. i.e. it will be in a snoozed state until this time. i.e. it will be in a snoozed state until this time.
    - `open` boolean — Indicates whether a conversation is open (true) or closed (false).
    - `state` 'open' | 'closed' | 'snoozed' — Can be set to "open", "closed" or "snoozed".
    - `read` boolean — Indicates whether a conversation has been read.
    - `priority` 'priority' | 'not_priority' — If marked as priority, it will return priority or else not_priority.
    - `admin_assignee_id` integer, nullable — The id of the admin assigned to the conversation. If it's not assigned to an admin it will return null.
    - `team_assignee_id` integer, nullable — The id of the team assigned to the conversation. If it's not assigned to a team it will return null.
    - `tags` Tags — A list of tags objects associated with a conversation
      - `type` 'tag.list' — The type of the object
      - `tags` Tag[] — A list of tags objects associated with the conversation.
        - `type` string — value is "tag"
        - `id` string — The id of the tag
        - `name` string — The name of the tag
        - `applied_at` integer, nullable — The time when the tag was applied to the object. Only present when the tag is returned as part of a tagging operation on a contact, conversation, or ticket.
        - `applied_by` Reference — reference to another object
          - `type` string
          - `id` string, nullable
    - `conversation_rating` ConversationRating, nullable — The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.
      - `rating` integer — The rating, between 1 and 5, for the conversation.
      - `remark` string — An optional field to add a remark to correspond to the number rating
      - `created_at` integer — The time the rating was requested in the conversation being rated.
      - `updated_at` integer — The time the rating was last updated.
      - `contact` ContactReference — reference to contact object
        - `type` 'contact' — always contact
        - `id` string — The unique identifier for the contact which is given by Intercom.
        - `external_id` string, nullable — The unique identifier for the contact which is provided by the Client.
      - `teammate` Reference — reference to another object
        - `type` string
        - `id` string, nullable
    - `source` ConversationSource — The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated.
      - `type` 'conversation' | 'email' | 'facebook' | 'instagram' | 'phone_call' | 'phone_switch' | 'push' | 'sms' | 'twitter' | 'whatsapp' — This includes conversation, email, facebook, instagram, phone_call, phone_switch, push, sms, twitter and whatsapp.
      - `id` string — The id representing the message.
      - `delivered_as` string — The conversation's initiation type. Possible values are customer_initiated, campaigns_initiated (legacy campaigns), operator_initiated (Custom bot), automated (Series and other outbounds with dynamic audience message) and admin_initiated (fixed audience message, ticket initiated by an admin, group email).
      - `subject` string — Optional. The message subject. For Twitter, this will show a generic message regarding why the subject is obscured.
      - `body` string — The message body, which may contain HTML. For Twitter, this will show a generic message regarding why the body is obscured.
      - `author` ConversationPartAuthor — The object who initiated the conversation, which can be a Contact, Admin or Team. Bots and campaigns send messages on behalf of Admins or Teams. For Twitter, this will be blank.
        - `type` string — The type of the author
        - `id` string — The id of the author
        - `name` string, nullable — The name of the author
        - `email` string, email — The email of the author
        - `from_ai_agent` boolean — If this conversation part was sent by the AI Agent
        - `is_ai_answer` boolean — If this conversation part body was generated by the AI Agent
      - `attachments` PartAttachment[] — A list of attachments for the part.
        - `type` string — The type of attachment
        - `name` string — The name of the attachment
        - `url` string — The URL of the attachment
        - `content_type` string — The content type of the attachment
        - `filesize` integer — The size of the attachment
        - `width` integer — The width of the attachment
        - `height` integer — The height of the attachment
      - `url` string, nullable — The URL where the conversation was started. For Twitter, Email, and Bots, this will be blank.
      - `redacted` boolean — Whether or not the source message has been redacted. Only applicable for contact initiated messages.
    - `contacts` ConversationContacts — The list of contacts (users or leads) involved in this conversation. This will only contain one customer unless more were added via the group conversation feature.
      - `type` 'contact.list'
      - `contacts` ContactReference[] — The list of contacts (users or leads) involved in this conversation. This will only contain one customer unless more were added via the group conversation feature.
        - `type` 'contact' — always contact
        - `id` string — The unique identifier for the contact which is given by Intercom.
        - `external_id` string, nullable — The unique identifier for the contact which is provided by the Client.
    - `teammates` ConversationTeammates, nullable — The list of teammates who participated in the conversation (wrote at least one conversation part).
      - `type` string — The type of the object - `admin.list`.
      - `teammates` Reference[] — The list of teammates who participated in the conversation (wrote at least one conversation part).
        - `type` string
        - `id` string, nullable
    - `custom_attributes` CustomAttributes — An object containing the different custom attributes associated to the conversation as key-value pairs. For relationship attributes the value will be a list of custom object instance models. System-defined attributes such as "CX Score rating" and "CX Score explanation" may also be included.
    - `first_contact_reply` ConversationFirstContactReply, nullable — An object containing information on the first users message. For a contact initiated message this will represent the users original message.
      - `created_at` integer
      - `type` string
      - `url` string, nullable
    - `sla_applied` SlaApplied, nullable — The SLA Applied object contains the details for which SLA has been applied to this conversation. Important: if there are any canceled sla_events for the conversation - meaning an SLA has been manually removed from a conversation, the sla_status will always be returned as null.
      - `type` string — object type
      - `sla_name` string — The name of the SLA as given by the teammate when it was created.
      - `sla_status` 'hit' | 'missed' | 'cancelled' | 'active' — SLA statuses: - `hit`: If there’s at least one hit event in the underlying sla_events table, and no “missed” or “canceled” events for the conversation. - `missed`: If there are any missed sla_events for the conversation and no canceled events. If there’s even a single missed sla event, the status will always be missed. A missed status is not applied when the SLA expires, only the next time a teammate replies. - `active`: An SLA has been applied to a conversation, but has not yet been fulfilled. SLA status is active only if there are no “hit, “missed”, or “canceled” events.
    - `statistics` ConversationStatistics, nullable — A Statistics object containing all information required for reporting, with timestamps and calculated metrics.
      - `type` string
      - `time_to_assignment` integer — Duration until last assignment before first admin reply. In seconds.
      - `time_to_admin_reply` integer — Duration until first admin reply. Subtracts out of business hours. In seconds.
      - `time_to_first_close` integer — Duration until conversation was closed first time. Subtracts out of business hours. In seconds.
      - `time_to_last_close` integer — Duration until conversation was closed last time. Subtracts out of business hours. In seconds.
      - `median_time_to_reply` integer — Median based on all admin replies after a contact reply. Subtracts out of business hours. In seconds.
      - `first_contact_reply_at` integer — Time of first text conversation part from a contact.
      - `first_assignment_at` integer — Time of first assignment after first_contact_reply_at.
      - `first_admin_reply_at` integer — Time of first admin reply after first_contact_reply_at.
      - `first_close_at` integer — Time of first close after first_contact_reply_at.
      - `last_assignment_at` integer — Time of last assignment after first_contact_reply_at.
      - `last_assignment_admin_reply_at` integer — Time of first admin reply since most recent assignment.
      - `last_contact_reply_at` integer — Time of the last conversation part from a contact.
      - `last_admin_reply_at` integer — Time of the last conversation part from an admin.
      - `last_close_at` integer — Time of the last conversation close.
      - `last_closed_by_id` string — The last admin who closed the conversation. Returns a reference to an Admin object.
      - `count_reopens` integer — Number of reopens after first_contact_reply_at.
      - `count_assignments` integer — Number of assignments after first_contact_reply_at.
      - `count_conversation_parts` integer — Total number of conversation parts.
      - `assigned_team_first_response_time` ConversationResponseTime[] — An array of conversation response time objects
        - `team_id` integer — Id of the assigned team.
        - `team_name` string — Name of the assigned Team, null if team does not exist, Unassigned if no team is assigned.
        - `response_time` integer — First response time of assigned team in seconds.
      - `assigned_team_first_response_time_in_office_hours` ConversationResponseTime[] — An array of conversation response time objects within office hours
        - `team_id` integer — Id of the assigned team.
        - `team_name` string — Name of the assigned Team, null if team does not exist, Unassigned if no team is assigned.
        - `response_time` integer — First response time of assigned team in seconds.
      - `handling_time` integer — Time from conversation assignment to conversation close in seconds.
      - `adjusted_handling_time` integer, nullable — Adjusted handling time for conversation in seconds. This is the active handling time excluding idle periods when teammates are not actively working on the conversation.
    - `linked_objects` LinkedObjectList — An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
      - `type` 'list' — Always list.
      - `total_count` integer — The total number of linked objects.
      - `has_more` boolean — Whether or not there are more linked objects than returned.
      - `data` LinkedObject[] — An array containing the linked conversations and linked tickets.
        - `type` 'ticket' | 'conversation' — ticket or conversation
        - `id` string — The ID of the linked object
        - `category` 'Customer' | 'Back-office' | 'Tracker' | 'null', nullable — Category of the Linked Ticket Object.
    - `ai_agent_participated` boolean — Indicates whether the AI Agent participated in the conversation.
    - `ai_agent` AiAgent — Data related to AI Agent involvement in the conversation.
      - `source_type` 'essentials_plan_setup' | 'profile' | 'workflow' | 'workflow_preview' | 'fin_preview', nullable — The type of the source that triggered AI Agent involvement in the conversation.
      - `source_title` string, nullable — The title of the source that triggered AI Agent involvement in the conversation. If this is `essentials_plan_setup` then it will return `null`.
      - `last_answer_type` 'null' | 'ai_answer' | 'custom_answer', nullable — The type of the last answer delivered by AI Agent. If no answer was delivered then this will return `null`
      - `resolution_state` 'assumed_resolution' | 'confirmed_resolution' | 'routed_to_team' | 'abandoned' | 'null', nullable — The resolution state of AI Agent. If no AI or custom answer has been delivered then this will return `null`.
      - `rating` integer, nullable — The customer satisfaction rating given to AI Agent, from 1-5.
      - `rating_remark` string, nullable — The customer satisfaction rating remark given to AI Agent.
      - `created_at` integer, nullable — The time when the AI agent rating was created.
      - `updated_at` integer, nullable — The time when the AI agent rating was last updated.
      - `content_sources` ContentSourcesList
        - `type` 'content_source.list'
        - `total_count` integer — The total number of content sources used by AI Agent in the conversation.
        - `content_sources` ContentSource[] — The content sources used by AI Agent in the conversation.
          - `content_type` 'file' | 'article' | 'external_content' | 'content_snippet' | 'workflow_connector_action' — The type of the content source.
          - `url` string — The internal URL linking to the content source for teammates.
          - `title` string — The title of the content source.
          - `locale` string — The ISO 639 language code of the content source.
  - `total_count` integer — A count of the total number of objects.
  - `pages` CursorPages, nullable — 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.
    - `type` 'pages' — the type of object `pages`.
    - `page` integer — The current page
    - `next` StartingAfterPaging, nullable
      - `per_page` integer — The number of results to fetch per page.
      - `starting_after` string, nullable — The cursor to use in the next request to get the next page of results.
    - `per_page` integer — Number of results per page
    - `total_pages` integer — Total number of pages

## Other responses

- `401` — Unauthorized
- `403` — API plan restricted

---

[API](https://skmtc.net/intercom/apis/intercom-api.md) · [All operations](https://skmtc.net/intercom/apis/intercom-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/intercom/intercom-api/revisions/9517e80f2642/schema)