Intercom API (unofficial showcase)
POST/conversations/{id}/merge

Merge a conversation into another conversation

Merges a secondary conversation into a primary conversation, closing the secondary and linking it to the surviving primary thread. Supply the secondary conversation ID in the path and the primary conversation ID in merge_into_conversation_id; the merge requires write_conversations, and also write_tickets when the secondary conversation is a ticket. The response contains the primary conversation.

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

2 parameters · 1 body field
idstringrequired
The identifier of the secondary conversation to merge into the primary conversation.
Intercom-Versionstringoptional
The API version to use. Defaults to 2.17 when omitted; supported versions include 1.0–1.4 and 2.0–2.6.
Allowed:1.01.11.21.31.42.02.12.22.32.42.52.6Default:2.17

Payload identifying the primary conversation that will survive the merge.

merge_into_conversation_idintegerrequired
The ID of the primary (target) conversation to merge into.

5 status codes
200Returns the primary conversation that survives the merge.
typestringoptional
Always conversation.
idstringoptional
The id representing the conversation.
titlestringoptional
The title given to the conversation.
created_atintegeroptional
The time the conversation was created.
updated_atintegeroptional
The last time the conversation was updated.
waiting_sinceintegeroptional
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_untilintegeroptional
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.
openbooleanoptional
Indicates whether a conversation is open (true) or closed (false).
statestringoptional
Can be set to "open", "closed" or "snoozed".
Allowed:openclosedsnoozed
readbooleanoptional
Indicates whether a conversation has been read.
prioritystringoptional
The priority level of the conversation. Returns one of none, low, medium, high, or urgent.
Allowed:nonelowmediumhighurgent
admin_assignee_idintegeroptional
The id of the admin assigned to the conversation. If it's not assigned to an admin it will return 0.
team_assignee_idintegeroptional
The id of the team assigned to the conversation. If it's not assigned to a team it will return 0.
companyobjectoptional
Companies allow you to represent organizations using your product. Each company will have its own description and be associated with contacts. You can fetch, create, update and list companies.
tagsobjectoptional
A list of tags objects associated with a conversation
conversation_ratingobjectoptional
The Conversation Rating object which contains information on the rating and/or remark added by a Contact and the Admin assigned to the conversation.
sourceobjectoptional
The type of the conversation part that started this conversation. Can be Contact, Admin, Campaign, Automated or Operator initiated.
contactsobjectoptional
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.
teammatesobjectoptional
The list of teammates who participated in the conversation (wrote at least one conversation part).
custom_attributesobjectoptional
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. Attributes that Intercom generates — such as "CX Score rating", "CX Score explanation", "AI Topic and Subtopic" and "CX Score reasons" — may also be included. Two of them, "AI Topic and Subtopic" and "CX Score reasons", carry lists of objects as their values, and are returned in responses only — they cannot be set on a write request.
first_contact_replyobjectoptional
An object containing information on the first users message. For a contact initiated message this will represent the users original message.
sla_appliedobjectoptional
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.
statisticsobjectoptional
A Statistics object containing all information required for reporting, with timestamps and calculated metrics.
conversation_partsobjectoptional
A list of Conversation Part objects for each part message in the conversation. This is only returned when Retrieving a Conversation, and ignored when Listing all Conversations. There is a limit of 500 parts.
linked_objectsobjectoptional
An object containing metadata about linked conversations and linked tickets. Up to 1000 can be returned.
ai_agent_participatedbooleanoptional
Indicates whether the AI Agent participated in the conversation.
ai_agentobjectoptional
Data related to AI Agent involvement in the conversation.
sales_agent_participatedbooleanoptional
Indicates whether the Sales Agent participated in the conversation.
sales_agentobjectoptional
Data related to Sales Agent involvement in the conversation.
channelobjectoptional
The channel through which the conversation was initiated and its current channel.
external_referencesarray<ConversationExternalReference>optional
References linking this conversation to records in an external helpdesk or CRM system. Populated for Fin Standalone workspaces synced from an external platform; an empty array otherwise. Sorted alphabetically by `type` and capped at 20 entries.
monitor_evaluationsarray<ConversationMonitorEvaluation>optional
QA monitor evaluations that flagged this conversation. Only included when `include_monitors=true` is passed as a query parameter.
scorecardsarray<ConversationScorecard>optional
QA scorecard results for this conversation. Only included when `include_scorecards=true` is passed as a query parameter.
400Returned when the merge request is invalid.

One documented failure

  • parameter_invalid

    merge_into_conversation_id must be a valid integer conversation ID

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
401Returned when the request is unauthenticated.

One documented failure

  • token_unauthorized

    Not authorized to access resource

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
403Returned when the authenticated user lacks the required OAuth scope.

One documented failure

  • forbidden

    Forbidden request

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects
422Returned when the conversation merge fails.

One documented failure

  • merge_failed

    Primary conversation not found

typestringrequired
The type is error.list
request_idstringoptional
errorsarray<object>required
An array of one or more error objects

Error handling

A 400 indicates invalid merge input, a 401 indicates missing or invalid authentication, and a 403 indicates insufficient permissions; merging requires write_conversations, plus write_tickets when the secondary is a ticket. A 422 indicates that the merge failed. The id path parameter must identify the secondary conversation, and merge_into_conversation_id must identify the primary conversation.