Sign in

v51

latestOpenAPI 3.0.1MITraw.githubusercontent.com2026-08-01150230854.3 KB
Conversations
Custom Object Instances

Update a conversation

You can update an existing conversation.

{% admonition type="info" name="Replying and other actions" %} If you want to reply to a coveration or take an action such as assign, unassign, open, close or snooze, take a look at the reply and manage endpoints. {% /admonition %}

{% admonition type="info" %} This endpoint handles both conversation updates and custom object associations.

See update a conversation with an association to a custom object instance in the request/response examples to see the custom object association format. {% /admonition %}

{% admonition type="danger" name="Breaking change: duplicate custom attribute names" %} The PUT /conversations/{id} endpoint now returns a 400 INVALID_PARAMETER error when the request includes custom_attributes and your workspace contains multiple non-archived conversation custom attributes with the same name. Previously, the update would silently apply to a non-deterministic attribute. To resolve, rename or archive the duplicate attribute in your workspace settings, then retry the request. {% /admonition %}

put/conversations/{conversation_id}

Path parameters

conversation_idinteger required

The id of the conversation to target

Query parameters

display_asstring

Set to plaintext to retrieve conversation messages in plain text.

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

readboolean

Mark a conversation as read within Intercom.

titlestring

The title given to the conversation

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.

company_idstring

The ID of the company that the conversation is associated with. The unique identifier for the company which is given by Intercom. Set to nil to remove company.

Example request

{
  "read": true,
  "title": "Conversation Title",
  "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."
  },
  "company_id": "5f4d3c1c-7b1b-4d7d-a97e-6095715c6632"
}

Response

update a conversation with an association to a custom object instance

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"
        }
      ]
    }
  }
}