For changes that have been updated across all versions, see the Unversioned changes page.
There are breaking changes in this version, which are detailed below.
We've added a new ticket.resolved webhook topic that fires when a ticket's state transitions to resolved.
Breaking Change Details:
The ticket.resolved and ticket.closed webhook topics now have distinct behaviors:
- ticket.resolved - Fires when a ticket's state transitions to "resolved". This is a state-based event.
- ticket.closed - Fires when a ticket conversation is closed. This is separate from state transitions.
API Versioning: In API versions prior to 2.15, the ticket.closed webhook fired when tickets transitioned to "resolved" state. For backward compatibility, both webhooks may fire in certain scenarios when using older API versions. When using API version 2.15 or later, these webhooks have distinct behaviors as described above.
If you have existing integrations that rely on ticket.closed to detect resolved tickets, you should migrate to using the new ticket.resolved topic.
The AI Agent resolution_state enum value abandoned has been renamed to negative_feedback for improved clarity. This represents the state when a user leaves negative feedback to the AI Agent.
Previous value: abandoned New value: negative_feedback
The AI Agent resolution_state enum value routed_to_team has been renamed to escalated for improved clarity.
Previous value: routed_to_team New value: escalated
The AI Agent resolution_state enum now includes a new value procedure_handoff. This represents conversations where the Fin AI Agent used a procedure configured to escalate the conversation.
New value: procedure_handoff
The event_details field on conversation parts now supports additional part types:
New Part Types:
conversation_tags_updated- Tags added/removed from conversationssnoozed- Snooze timing with human-readable duration and custom timestampspriority_changed- Priority state transitions (priority/not_priority)conversation_sla_applied_by_rule- SLA via modern Operator workflowsconversation_sla_applied_by_workflow- SLA via legacy Inbox Rulesconversation_sla_target_missed- SLA breach detailsconversation_sla_paused- SLA status at pause timeconversation_sla_unpaused- SLA info when unpausedconversation_sla_removed- SLA removal infoconversation_attribute_updated_by_user- User-initiated CDA updates
Enhanced Part Types:
conversation_attribute_updated_by_admin- Now includespreviousfield to track CDA value history
conversation.company.updated
- Fires when a company is added to or updated on a conversation
- Requires the "Read conversations" permission
Event Details:
- Topic Name:
conversation.company.updated - Description: Triggered when a company association is updated on a conversation
- Required Scope: Read conversations
- Object: Returns the full Conversation object with updated company association
api.request.completed
- Fires when a successful v3 API request is completed
- Requires the "Read API activity logs" permission
- Useful for monitoring and auditing API usage
You can now add a company to a conversation using the Conversations API. This allows you to associate business context with customer conversations.
The Conversation API now includes a company field in all conversation responses. This field contains the full company object associated with the conversation, making it easier to access company information without additional API calls. This field is nullable and will be populated when available.
Example Response:
{
"type": "conversation",
"id": "1295",
"company": {
"type": "company",
"id": "5f4d3c1c-7b1b-4d7d-a97e-6095715c6632",
"name": "Example Company Inc.",
"company_id": "6"
},
// ... other conversation fields
}- Added
notesfield to all company API endpoint responses
Support for the language_override field has been added to both the create contact and update contact endpoints in the Contacts API.
The language_override field allows you to set a preferred language for a contact. When set, Intercom uses this language for Fin AI and the Messenger interface, overriding the browser's language setting.
Field details:
- Accepts ISO 639-1 two-letter language codes (e.g.,
"en","fr","de","es") - Invalid language codes are automatically set to
null
The conversation_rating field in conversation responses now returns the latest completed rating (a rating with a rating_index value) instead of the latest rating overall. If no completed ratings exist for a conversation, the API falls back to returning the latest rating overall.
New API endpoints for managing Fin Voice configurations and interactions.
New API endpoints for exporting workflow configurations programmatically.
Email message metadata now includes a message_id field for better tracking and correlation of email communications.
We've added a new Brands API that provides read access to workspace brands configuration.
New Endpoints:
GET /brands- List all brands for the workspaceGET /brands/{id}- Retrieve a specific brand by ID
The brand object includes id, name, is_default flag to identify the primary brand, associated help_center_id, and default_address_settings_id for email settings.
We've added a new Emails API that provides read access to sender email address settings configured in your workspace.
New Endpoints:
GET /emails- List all email settings for the workspaceGET /emails/{id}- Retrieve a specific email setting by ID
The email setting object includes email, verified status, domain, associated brand_id, forwarding_enabled flag, and forwarded_email_last_received_at timestamp.
Help Center API responses now include two new fields for custom domain support:
url- The URL for the help center, if you have a custom domain then this will show the URL using the custom domain. (e.g.,https://intercom.help/mycompany)custom_domain- Custom domain configured for the help center (e.g.,help.mycompany.com)