Sign in

v51

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

Manage a conversation

For managing conversations you can:

  • Close a conversation
  • Snooze a conversation to reopen on a future date
  • Open a conversation which is snoozed or closed
  • Assign a conversation to an admin and/or team.
post/conversations/{conversation_id}/parts

Path parameters

conversation_idstring required

The identifier for the conversation as given by Intercom.

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

OR
OR
OR

Example request

{
  "message_type": "close",
  "type": "admin",
  "admin_id": "12345",
  "body": " This conversation is now closed!"
}

Response

Assign a conversation

typestring

Always conversation.

idstring

The id representing the conversation.

titlestring nullable

The title given to the conversation.

created_atinteger

The time the conversation was created.

updated_atinteger

The last time the conversation was updated.

waiting_sinceinteger 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_untilinteger 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.

openboolean

Indicates whether a conversation is open (true) or closed (false).

state'open' | 'closed' | 'snoozed'

Can be set to "open", "closed" or "snoozed".

readboolean

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_idinteger nullable

The id of the admin assigned to the conversation. If it's not assigned to an admin it will return null.

team_assignee_idinteger nullable

The id of the team assigned to the conversation. If it's not assigned to a team it will return null.

custom_attributesCustomAttributes

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.

ai_agent_participatedboolean

Indicates whether the AI Agent participated in the conversation.

Example response

{
  "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
  },
  "conversation_parts": {
    "type": "conversation_part.list",
    "conversation_parts": [
      {
        "type": "conversation_part",
        "id": "3",
        "part_type": "comment",
        "body": "<p>Okay!</p>",
        "created_at": 1663597223,
        "updated_at": 1663597260,
        "notified_at": 1663597260,
        "assigned_to": {
          "type": "contact",
          "id": "1a2b3c"
        },
        "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
          }
        ],
        "external_id": "abcd1234",
        "email_message_metadata": {
          "subject": "Question about my order",
          "email_address_headers": [
            {
              "type": "from",
              "email_address": "jdoe@example.com",
              "name": "Joe Example"
            }
          ]
        },
        "metadata": {
          "quick_reply_uuid": "123e4567-e89b-12d3-a456-426614174000"
        },
        "state": "open",
        "tags": [
          {
            "type": "tag",
            "id": "123456",
            "name": "Test tag"
          }
        ],
        "event_details": {
          "workflow": {
            "name": "Workflow 1"
          },
          "attribute": {
            "name": "flight_category"
          },
          "value": {
            "name": "vip_status"
          }
        },
        "app_package_code": "test-integration"
      }
    ],
    "total_count": 1
  },
  "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"
        }
      ]
    }
  }
}