Front Conversations API

openapi: 3.0.0
info:
  version: 1.0.0
  title: Channel Accounts Conversations API
  contact:
    name: Front Platform
    url: https://community.front.com
servers:
- url: https://api2.frontapp.com
security:
- http: []
tags:
- name: Conversations
paths:
  /conversations:
    get:
      summary: List conversations
      operationId: list-conversations
      description: 'List the conversations in the company in reverse chronological order (most recently updated first). The order will respect your company''s [bump settings](https://help.front.com/t/y729th/customize-when-conversations-bump-up), which determine when conversations bump to the top. For more advanced filtering, see the [search endpoint](https://dev.frontapp.com/reference/conversations#search-conversations).



        Required scope: `conversations:read`'
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/conversationQuery'
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/sortByConversations'
      - $ref: '#/components/parameters/sortOrder'
      responses:
        '200':
          $ref: '#/components/responses/listOfConversations'
      x-required-scopes:
      - conversations:read
    post:
      summary: Create discussion conversation
      operationId: create-conversation
      description: 'Create a new [conversation](https://dev.frontapp.com/reference/conversations#creating-a-new-conversation) that only supports comments (known as discussions in Front). If you want to create a conversation that supports messages, use the [Create message](https://dev.frontapp.com/reference/post_channels-channel-id-messages) endpoint. If you want to add a comment to an existing conversation, use the [Add comment](https://dev.frontapp.com/reference/post_conversations-conversation-id-comments) endpoint.


        Required scope: `conversations:write`'
      tags:
      - Conversations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateConversation'
      responses:
        '201':
          $ref: '#/components/responses/conversation'
      x-required-scopes:
      - conversations:write
  /conversations/search/{query}:
    get:
      summary: Search conversations
      operationId: search-conversations
      description: 'Search for conversations. Response will include a count of total matches and an array of conversations in descending order by last activity.

        See the [search syntax documentation](https://dev.frontapp.com/docs/search-1) for usage examples.

        **Note:** This endpoint is subject to [proportional rate limiting](https://dev.frontapp.com/docs/rate-limiting#additional-proportional-limiting) at 40% of your company''s rate limit.



        Required scope: `conversations:read`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: query
        required: true
        description: Search query string. See [Search](https://dev.frontapp.com/docs/search-1) topic for usage details.
        schema:
          type: string
          default: inbox:inb_123 tag:tag_345
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          $ref: '#/components/responses/listOfConversationSearchResults'
      x-required-scopes:
      - conversations:read
  /conversations/{conversation_id}:
    get:
      summary: Get conversation
      operationId: get-conversation-by-id
      description: 'Fetch a conversation.



        Required scope: `conversations:read`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      responses:
        '200':
          $ref: '#/components/responses/conversation'
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:read
    patch:
      summary: Update conversation
      operationId: update-conversation
      description: 'Update a conversation.


        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversation'
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
        '400':
          description: Invalid input, such as invalid custom fields
      x-required-scopes:
      - conversations:write
    delete:
      summary: Delete conversation
      operationId: delete-conversation
      description: 'Permanently delete a conversation. The conversation must have status "trashed"

        (in the trash) before it can be permanently deleted. This action cannot be undone.



        Required scope: `conversations:delete`'
      x-required-scopes:
      - conversations:delete
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      responses:
        '204':
          description: No content
        '400':
          description: Conversation must have status "trashed" before it can be permanently deleted
        '403':
          description: Token lacks the required `conversations:delete` scope
        '404':
          description: Conversation not found
  /conversations/{conversation_id}/assignee:
    put:
      summary: Update conversation assignee
      operationId: update-conversation-assignee
      description: 'Assign or unassign a conversation.


        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversationAssignee'
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
  /conversations/{conversation_id}/events:
    get:
      summary: List conversation events
      operationId: list-conversation-events
      description: 'List the events that occured for a conversation in reverse chronological order (newest first). The order will respect your company''s [bump settings](https://help.front.com/t/y729th/customize-when-conversations-bump-up), which determine when conversations bump to the top.


        Required scope: `events:*:read`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      responses:
        '200':
          $ref: '#/components/responses/listOfEvents'
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - events:*:read
  /conversations/{conversation_id}/followers:
    get:
      summary: List conversation followers
      operationId: list-conversation-followers
      description: 'List the teammates following a conversation.


        Required scope: `teammates:read`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      responses:
        '200':
          $ref: '#/components/responses/listOfTeammates'
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - teammates:read
    post:
      summary: Add conversation followers
      operationId: add-conversation-followers
      description: 'Adds teammates to the list of followers of a conversation.


        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      - in: query
        name: ignore_errors
        description: Whether to ignore invalid teammate IDs and continue adding valid ones.
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                teammate_ids:
                  description: IDs of the teammate to add to the followers list. Alternatively, you can supply the teammates as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
                  type: array
                  maxItems: 50
                  items:
                    type: string
              required:
              - teammate_ids
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
    delete:
      summary: Delete conversation followers
      operationId: delete-conversation-followers
      description: 'Removes teammates from the list of followers of a conversation.


        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                teammate_ids:
                  description: IDs of the teammate to remove from the followers list. Alternatively, you can supply the teammates as a [resource alias](https://dev.frontapp.com/docs/resource-aliases-1).
                  type: array
                  maxItems: 50
                  items:
                    type: string
              required:
              - teammate_ids
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
  /conversations/{conversation_id}/inboxes:
    get:
      summary: List conversation inboxes
      operationId: list-conversation-inboxes
      description: 'List the inboxes in which a conversation is listed.


        Required scope: `inboxes:read`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      responses:
        '200':
          $ref: '#/components/responses/listOfInboxes'
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - inboxes:read
  /conversations/{conversation_id}/links:
    post:
      summary: Add conversation link
      operationId: add-conversation-link
      description: 'Adds one or more links to a conversation

        For more information on links, see the [Links](https://dev.frontapp.com/reference/links) topic.



        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                link_ids:
                  description: Link IDs to add. Either link_ids or link_external_urls must be specified but not both
                  type: array
                  maxItems: 10
                  items:
                    type: string
                link_external_urls:
                  description: Link external URLs to add. Creates links if necessary. Either link_ids or link_external_urls must be specified but not both
                  type: array
                  maxItems: 10
                  items:
                    type: string
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
    delete:
      summary: Remove conversation links
      operationId: remove-conversation-links
      description: 'Removes one or more links to a conversation.

        For more information on links, see the [Links](https://dev.frontapp.com/reference/links) topic.



        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                link_ids:
                  description: Link IDs to remove.
                  type: array
                  maxItems: 10
                  items:
                    type: string
              required:
              - link_ids
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
  /conversations/{conversation_id}/messages:
    get:
      summary: List conversation messages
      operationId: list-conversation-messages
      description: 'List the messages in a conversation in reverse chronological order (newest first).


        Required scope: `messages:read`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      - $ref: '#/components/parameters/limit'
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/sortByConversationMessages'
      - $ref: '#/components/parameters/sortOrder'
      responses:
        '200':
          $ref: '#/components/responses/listOfMessages'
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - messages:read
  /conversations/{conversation_id}/reminders:
    patch:
      summary: Update conversation reminders
      operationId: update-conversation-reminders
      description: 'Snooze or unsnooze a conversation for the provided user.

        For private conversations, reminders can only be created and edited through the API for teammates that own the conversation.

        For shared conversations, reminders created and edited through the API are shared for all teammates within the shared inbox(es) that the conversation belongs to.



        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateConversationReminders'
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
  /conversations/{conversation_id}/tags:
    post:
      summary: Add conversation tag
      operationId: add-conversation-tag
      description: 'Adds one or more tags to a conversation


        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        description: Tag IDs to add
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagIds'
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
    delete:
      summary: Remove conversation tag
      operationId: remove-conversation-tag
      description: 'Removes one or more tags to a conversation


        Required scope: `conversations:write`'
      tags:
      - Conversations
      parameters:
      - in: path
        name: conversation_id
        required: true
        description: The conversation ID
        schema:
          type: string
          default: cnv_123
      requestBody:
        description: Tag IDs to remove
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TagIds'
      responses:
        '204':
          description: No content
        '301':
          description: If the conversation has been merged, the response redirects you to the merged conversation.
      x-required-scopes:
      - conversations:write
components:
  schemas:
    TagResponse:
      type: object
      description: A tag is a label that can be used to classify conversations.
      required:
      - _links
      - id
      - name
      - description
      - highlight
      - is_private
      - is_visible_in_conversation_lists
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/tags/tag_2oxhvy
            related:
              type: object
              properties:
                conversations:
                  type: string
                  description: Link to tag conversations
                  example: https://yourCompany.api.frontapp.com/tags/tag_2oxhvy/conversations
                owner:
                  type: string
                  nullable: true
                  description: Link to tag owner
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6jydq
                parent_tag:
                  type: string
                  nullable: true
                  description: Link to parent tag
                  example: https://yourCompany.api.frontapp.com/tags/tag_3h07ym
                children:
                  type: string
                  nullable: true
                  description: Link to tag children
                  example: https://yourCompany.api.frontapp.com/tags/tag_2oxhvy/children
        id:
          type: string
          description: Unique identifier of the tag
          example: tag_2oxhvy
        name:
          type: string
          description: Name of the tag
          example: Warehouse task
        description:
          type: string
          nullable: true
          description: Description of the tag
          example: Sitting on your biscuit, never having to risk it
        highlight:
          type: string
          nullable: true
          description: Highlight color or emoji of the tag. Null if the tag does not have a highlight.
          example: null
        is_private:
          type: boolean
          description: Whether or not the tag is individual
          example: false
        is_visible_in_conversation_lists:
          type: boolean
          description: Whether the tag is visible in conversation lists.
          example: true
        created_at:
          type: number
          description: Timestamp of tag create creation
          example: 1682538996.583
        updated_at:
          type: number
          description: Timestamp of the last tag update
          example: 1699575875.186
    UpdateConversation:
      properties:
        assignee_id:
          type: string
          description: ID of the teammate to assign the conversation to. Set it to null to unassign.
        inbox_id:
          type: string
          description: ID of the inbox to move the conversation to.
        status:
          type: string
          description: New status of the conversation
          enum:
          - archived
          - open
          - deleted
          - spam
        status_id:
          type: string
          description: Unique identifier of the status to set the conversation to. Only one of status and status_id should be provided. Ticketing must be enabled for the company to use this field.
          example: sts_123
        tag_ids:
          type: array
          description: List of all the tag IDs replacing the old conversation tags
          items:
            $ref: '#/components/schemas/ResourceID'
        custom_fields:
          description: Custom fields for this conversation. If you want to keep all custom fields the same when updating this resource, do not include any custom fields in the update. If you want to update custom fields, make sure to include all custom fields, not just the fields you want to add or update. If you send only the custom fields you want to update, the other custom fields will be erased. You can retrieve the existing custom fields before making the update to note the current fields. Send as an object of key:value pairs where the key is the custom field name and the value is the custom field value.
          $ref: '#/components/schemas/CustomFieldParameter'
    ResourceID:
      type: string
    TagIds:
      type: object
      required:
      - tag_ids
      properties:
        tag_ids:
          type: array
          items:
            $ref: '#/components/schemas/ResourceID'
    CommentResponse:
      type: object
      required:
      - _links
      - id
      - author
      - body
      - attachments
      - is_pinned
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/comments/com_1ywg3f2
            related:
              type: object
              properties:
                conversation:
                  type: string
                  description: Link to comment's conversation
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_y4xb93i
                mentions:
                  type: string
                  description: Link to comment mentions
                  example: https://yourCompany.api.frontapp.com/comments/com_1ywg3f2/mentions
                comment_replied_to:
                  nullable: true
                  type: string
                  description: Link to the comment that is being replied to.
                  example: https://yourCompany.api.frontapp.com/comments/com_1ywg3f2
        id:
          type: string
          description: Unique identifier of the comment
          example: com_1ywg3f2
        author:
          description: Teammate who wrote the comment
          $ref: '#/components/schemas/TeammateResponse'
        body:
          type: string
          description: Content of the comment
          example: Sometimes I'll start a sentence and I don't even know where it's going. I just hope I find it along the way.
        posted_at:
          type: number
          description: The timestamp when the comment was posted
          example: 1698943401.378
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: List of files attached to the comment
        is_pinned:
          type: boolean
          description: Whether or not the comment is pinned in its conversation
          example: true
    ConversationResponse:
      type: object
      required:
      - _links
      - id
      - subject
      - status
      - ticket_ids
      - assignee
      - recipient
      - tags
      - links
      - custom_fields
      - is_private
      - scheduled_reminders
      - metadata
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q
            related:
              type: object
              properties:
                events:
                  type: string
                  description: Link to conversation events
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/events
                followers:
                  type: string
                  description: Link to conversation followers
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/followers
                messages:
                  type: string
                  description: Link to conversation messages
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/messages
                comments:
                  type: string
                  description: Link to conversation comments
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/comments
                inboxes:
                  type: string
                  description: Link to conversation inboxes
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q/inboxes
                last_message:
                  type: string
                  description: Link to last message of the conversation
                  example: https://yourCompany.api.frontapp.com/messages/msg_1q15qmtq?referer=conversation
        id:
          type: string
          description: Unique identifier of the conversation
          example: cnv_yo1kg5q
        subject:
          type: string
          description: Subject of the message for email message
          example: How to prank Dwight Schrute
        status:
          type: string
          description: Status of the conversation
          enum:
          - archived
          - unassigned
          - deleted
          - assigned
          example: assigned
        status_id:
          type: string
          description: Unique identifier of the conversation status category, only present if ticketing is enabled
          example: sts_5x
        status_category:
          type: string
          description: Status category of the conversation
          enum:
          - open
          - waiting
          - resolved
          example: resolved
        ticket_ids:
          type: array
          description: List of ticket ids associated with the conversation
          items:
            type: string
          example:
          - TICKET-1
        assignee:
          nullable: true
          $ref: '#/components/schemas/TeammateResponse'
          description: Partial representation of the teammate assigned to the conversation
        recipient:
          nullable: true
          $ref: '#/components/schemas/RecipientResponse'
          description: Main recipient of the conversation
        tags:
          type: array
          description: List of the tags for this conversation
          items:
            $ref: '#/components/schemas/TagResponse'
        links:
          type: array
          description: List of the links for this conversation
          items:
            $ref: '#/components/schemas/LinkResponse'
        custom_fields:
          description: Custom fields for this conversation
          $ref: '#/components/schemas/CustomFieldParameter'
        created_at:
          type: number
          description: Timestamp at which the conversation was created.
          example: 1701292649.333
        updated_at:
          type: number
          description: Timestamp at which the conversation was last updated.
          example: 1701292649.333
        waiting_since:
          type: number
          description: Timestamp of the oldest unreplied message.
          example: 1701292649.333
        is_private:
          type: boolean
          description: Whether or not the conversation is private
          example: true
        scheduled_reminders:
          type: array
          description: List of scheduled (non-expired and non-canceled) reminders for this conversation
          items:
            $ref: '#/components/schemas/Reminder'
        metadata:
          type: object
          description: Optional metadata about the conversation
          properties:
            external_conversation_ids:
              type: array
              description: List of external_ids for partner channel associated with the conversation. Only present for partner channel token authenticated requests.
              example:
              - JS3949
              - JS9403
              items:
                type: string
    Attachment:
      type: object
      required:
      - id
      - url
      - filename
      - content_type
      - size
      - metadata
      properties:
        id:
          type: string
          description: The unique identifier of the attachment.
          example: fil_3q8a7mby
        filename:
          type: string
          description: Name of the attached file
          example: Andy_Anger_Management_Certificate.png
        url:
          type: string
          description: URL to download the attached file
          example: https://yourCompany.api.frontapp.com/download/fil_3q8a7mby
        content_type:
          type: string
          description: Content type of the attached file in [MIME format](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types). Note that some attachments types may not be supported.
          example: image/png
        size:
          type: integer
          description: Size (in byte) of the attached file
          example: 4405
        metadata:
          description: Attachment metadata
          type: object
          properties:
            is_inline:
              type: boolean
              description: Whether or not the attachment is part of the message body
              example: true
            cid:
              type: string
              description: Unique identifier used to link an attachment to where it is used in the message body
              example: 526b45586d0e6b1c484afab63d1ef0be
    Reminder:
      type: object
      required:
      - _links
      properties:
        _links:
          type: object
          properties:
            related:
              type: object
              properties:
                owner:
                  type: string
                  description: Link to conversation owner
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a
        created_at:
          type: number
          description: Timestamp at which the conversation reminder has been created
          example: 1701806790.536
        scheduled_at:
          type: number
          description: Timestamp that the conversation reminder has been scheduled for
          example: 170187

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/front/refs/heads/main/openapi/front-conversations-api-openapi.yml