Front Events API

openapi: 3.2.0
info:
  version: 1.0.0
  title: Channel Accounts Events API
  contact:
    name: Front Platform
    url: https://community.front.com
servers:
- url: https://api2.frontapp.com
security:
- http: []
tags:
- name: Events
paths:
  /events:
    get:
      summary: List events
      operationId: list-events
      description: 'Lists all the detailed events which occurred in the inboxes of the company ordered in reverse chronological order (newest first).

        Refer to the [Events](https://dev.frontapp.com/reference/events) topic for more information, including sorting and filtering.



        Required scope: `events:*:read`'
      tags:
      - Events
      parameters:
      - $ref: '#/components/parameters/activityQuery'
      - in: query
        name: limit
        description: Max number of results per page (max 15)
        schema:
          type: integer
          default: 15
      - $ref: '#/components/parameters/pageToken'
      - $ref: '#/components/parameters/sortByActivities'
      - $ref: '#/components/parameters/sortOrder'
      responses:
        '200':
          $ref: '#/components/responses/listOfEvents'
      x-required-scopes:
      - events:*:read
  /events/{event_id}:
    get:
      summary: Get event
      operationId: get-event
      description: 'Fetch an event.

        Refer to the [Events](https://dev.frontapp.com/reference/events) topic for more information, including sorting and filtering.



        Required scope: `events:*:read`'
      tags:
      - Events
      parameters:
      - in: path
        name: event_id
        required: true
        description: The event ID
        schema:
          type: string
          default: evt_55c8c149
      responses:
        '200':
          $ref: '#/components/responses/event'
      x-required-scopes:
      - events:*:read
components:
  schemas:
    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:
          $ref: '#/components/schemas/TeammateResponse'
          description: Partial representation of the teammate assigned to the conversation
        recipient:
          $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
    LinkResponse:
      type: object
      description: A link used to connect a Front conversation to an external resource.
      required:
      - _links
      - id
      - name
      - type
      - external_url
      - custom_fields
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/links/top_b2wpa
        id:
          type: string
          description: Unique identifier of the link
          example: top_b2wpa
        name:
          type: string
          description: Display name of the link
          example: JIRA-SCRAN-4567
        type:
          type: string
          description: Type of the link. Typically associated with the underlying link provider (if known)
          example: app_2f76b9ac738de158
        external_url:
          type: string
          description: Underlying identifying external URL of the link
          example: https://dundermifflin.atlassian.net/browse/PB-SCRAN-4567
        custom_fields:
          description: Custom fields for this link
          $ref: '#/components/schemas/CustomFieldParameter'
    RecipientResponse:
      type: object
      required:
      - _links
      - name
      - handle
      - role
      properties:
        _links:
          type: object
          properties:
            related:
              type: object
              properties:
                contact:
                  type:
                  - string
                  - 'null'
                  description: Link to recipient contact
                  example: https://yourCompany.api.frontapp.com/contacts/crd_2njtoem
        name:
          type:
          - string
          - 'null'
          description: Name of the recipient.
          example: Phyllis Lapin-Vance
        handle:
          type: string
          description: Handle of the contact. Can be any string used to uniquely identify the contact
          example: purpleboss@limitlesspaper.com
        role:
          type: string
          description: Role of the recipient
          enum:
          - from
          - to
          - cc
          - bcc
          - reply-to
          example: cc
    RuleResponse:
      type: object
      required:
      - _links
      - id
      - name
      - actions
      - is_private
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/rules/rul_58xhq
            related:
              type: object
              properties:
                owner:
                  type:
                  - string
                  - 'null'
                  description: Link to rule owner
                  example: null
        id:
          type: string
          description: Unique identifier of the rule
          example: rul_58xhq
        name:
          type: string
          description: Name of the rule
          example: Scranton new account workflow
        actions:
          type: array
          description: List of the rule's actions description
          items:
            type: string
            example:
            - Assign to Pam
            - Unassign from Michael
            - Tag with Scranton is the Best Branch
            - Tag with Michael is the Best Boss
        is_private:
          type: boolean
          description: Whether or not the rule is individual
          example: false
    EventResponse:
      type: object
      description: An event is created every time something interesting is happening in Front.
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/events/evt_4ckcra8e
        id:
          type: string
          description: Unique identifier of the event
          example: evt_4ckcra8e
        type:
          type: string
          description: Type of event
          enum:
          - assign
          - unassign
          - archive
          - reopen
          - trash
          - restore
          - reminder
          - comment
          - mention
          - inbound
          - outbound
          - out_reply
          - move
          - forward
          - tag
          - untag
          - sending_error
          - message_bounce_error
          - conversations_merged
          - link_added
          - link_removed
          - custom_field_updated
          - macro_triggered
          - topic_identified
          - ticket_status_update
          - call_started
          - call_abandoned
          - call_queued
          - call_on_hold
          - call_resumed
          - call_connected
          - call_missed
          - call_hangup
          - call_transferred
          example: inbound
        emitted_at:
          type: number
          description: The timestamp when the event has been emitted
          example: 1703102616
        source:
          type: object
          description: Event source
          properties:
            _meta:
              type: object
              description: Metadata about the resource
              properties:
                type:
                  description: Type of resource
                  enum:
                  - api
                  - oauth_client
                  - rule
                  - teammate
                  - imap
                  - gmail
                  - reminder
                  - inboxes
                  - recipient
                  example: inboxes
            data:
              description: The resource which triggered the event
              oneOf:
              - $ref: '#/components/schemas/RuleResponse'
              - $ref: '#/components/schemas/TeammateResponse'
              - type: array
                items:
                  $ref: '#/components/schemas/InboxResponse'
        target:
          type: object
          description: Partial representation (type & id) of the event's target
          properties:
            _meta:
              type: object
              description: Metadata about the resource
              properties:
                type:
                  description: Type of resource
                  enum:
                  - teammate
                  - inboxes
                  - message
                  - comment
                  - tag
                  - deleted_conversation_ids
                  - link
                  - custom_field
                  example: inboxes
            data:
              description: The resource which received the event
              oneOf:
              - $ref: '#/components/schemas/TeammateResponse'
              - $ref: '#/components/schemas/InboxResponse'
              - $ref: '#/components/schemas/TagResponse'
              - $ref: '#/components/schemas/CommentResponse'
              - $ref: '#/components/schemas/MessageResponse'
              - $ref: '#/components/schemas/LinkResponse'
        conversation:
          $ref: '#/components/schemas/ConversationResponse'
          description: The conversation on which the event happened
    SignatureResponse:
      type: object
      required:
      - _links
      - id
      - name
      - body
      - sender_info
      - is_private
      - is_visible_for_all_teammate_channels
      - is_default
      - channel_ids
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/signatures/sig_6rrv2
            related:
              type: object
              properties:
                owner:
                  type: string
                  description: Link to signature's owner (either a team or teammate)
                  example: https://yourCompany.api.frontapp.com/teams/tim_k30
        id:
          type: string
          description: Unique identifier of the signature
          example: sig_6rrv2
        name:
          type:
          - string
          - 'null'
          description: Name of the signature
          example: Finer Things Club signature
        body:
          type: string
          description: Body of the signature
          example: <div>—<br />{{user.name}}<br />No paper, no plastic, and no work talk allowed<br /></div>
        sender_info:
          type:
          - string
          - 'null'
          description: Sender info of the signature
          example:
            '[object Object]': null
        is_visible_for_all_teammate_channels:
          type: boolean
          description: Whether or not the signature is available in teammate channels.
          example: true
        is_default:
          type: boolean
          description: Whether the signature is the default signature for the team or teammate.
          example: false
        is_private:
          type: boolean
          description: Whether the signature is private to the teammate.
          example: true
        channel_ids:
          type:
          - array
          - 'null'
          items:
            type: string
            description: List of channels the signature is available in. If belonging to a teammate, represents all channels this can be used in. If belonging to a team, represents all team channels this can be used in. If null, there are no restrictions.
            example: null
    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: 1701874800
        updated_at:
          type: number
          description: Timestamp at which the conversation reminder has been updated
          example: 1701806790.536
    InboxResponse:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6
            related:
              type: object
              properties:
                teammates:
                  type: string
                  description: Link to inbox teammates
                  example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6/teammates
                conversations:
                  type: string
                  description: Link to inbox conversations
                  example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6/conversations
                channels:
                  type: string
                  description: Link to inbox channels
                  example: https://yourCompany.api.frontapp.com/inboxes/inb_1ix6/channels
                owner:
                  type: string
                  description: Link to inbox owner
                  example: https://yourCompany.api.frontapp.com/teams/tim_k30
        id:
          type: string
          description: Unique identifier for the inbox
          example: inb_1ix6
        name:
          type: string
          description: Name of the inbox
          example: The Dundies
        is_private:
          type: boolean
          description: Whether or not the inbox is individual
          example: false
        is_public:
          type: boolean
          description: Whether or not the inbox is available to all members of a team by default
          example: true
        custom_fields:
          description: Custom fields for this inbox
          $ref: '#/components/schemas/CustomFieldParameter'
    TeammateResponse:
      type: object
      description: A teammate is a user in Front.
      required:
      - _links
      - id
      - email
      - username
      - first_name
      - last_name
      - license_type
      - is_admin
      - is_available
      - is_blocked
      - type
      - custom_fields
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a
            related:
              type: object
              properties:
                inboxes:
                  type: string
                  description: Link to teammate's inboxes
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a/inboxes
                conversations:
                  type: string
                  description: Link to teammate's conversations
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6r55a/conversations
                botSource:
                  type: string
                  description: Link to the source resource of the bot (e.g. rule)
                  example: https://yourCompany.api.frontapp.com/rules/rul_6r55a
        id:
          type: string
          description: Unique identifier of the teammate
          example: tea_6r55a
        email:
          type: string
          description: Email address of the teammate
          example: michael.scott@dundermifflin.com
        username:
          type: string
          description: Username of the teammate (used for "@" mentions)
          example: PrisonMike
        first_name:
          type: string
          description: First name of the teammate
          example: Michael
        last_name:
          type: string
          description: Last name of the teammate
          example: Scott
        is_admin:
          type: boolean
          description: Whether or not the teammate is an admin in your company
          example: true
        is_available:
          type: boolean
          description: Whether or not the teammate is available
          example: false
        is_blocked:
          type: boolean
          description: Whether or not the teammate account has been blocked
          example: false
        type:
          type: string
          description: "Type of the teammate, normal teammates are denoted as \"user\", while visitors are denoted as \"visitor\".\nBot users are denoted by their parent resource type.\nThe following bot types are available:\n  * rule: acting on behalf of a Rule, author of comments and drafts\n  * macro: acting on behalf of a Macro, author of comments and drafts\n  * API: acting on behalf of OAuth clients\n  * integration: acting on behalf of an Integration\n  * CSAT: used for authoring CSAT response comments\n"
          enum:
          - user
          - visitor
          - rule
          - macro
          - API
          - integration
          - CSAT
        custom_fields:
          description: Custom fields for this teammate
          $ref: '#/components/schemas/CustomFieldParameter'
    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:
                  type:
                  - string
                  - 'null'
                  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
    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
                  - 'null'
                  description: Link to tag owner
                  example: https://yourCompany.api.frontapp.com/teammates/tea_6jydq
                parent_tag:
                  type:
                  - string
                  - 'null'
                  description: Link to parent tag
                  example: https://yourCompany.api.frontapp.com/tags/tag_3h07ym
                children:
                  type:
                  - string
                  - 'null'
                  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
          - 'null'
          description: Description of the tag
          example: Sitting on your biscuit, never having to risk it
        highlight:
          type:
          - string
          - 'null'
          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
    MessageResponse:
      type: object
      properties:
        _links:
          type: object
          properties:
            self:
              type: string
              description: Link to resource
              example: https://yourCompany.api.frontapp.com/messages/msg_1q15qmtq
            related:
              type: object
              properties:
                conversation:
                  type: string
                  description: Link to message conversation
                  example: https://yourCompany.api.frontapp.com/conversations/cnv_yo1kg5q
                message_replied_to:
                  type: string
                  description: Link to message this message replied to
                  example: https://yourCompany.api.frontapp.com/messages/msg_2y67qldq
                message_seen:
                  type: string
                  description: Link to message seen information
                  example: https://yourCompany.api.frontapp.com/messages/msg_1q15qmtq/seen
        id:
          type: string
          description: Unique identifier of the message
          example: msg_1q15qmtq
        message_uid:
          type: string
          description: Secondary unique identifier of a message. Generated by Front on message creation. Learn more at about the [message UID](https://dev.frontapp.com/reference/messages#creating-a-new-message).
          example: 1eab543f84a0785f7b6b8967cck18f4d
        type:
          type: string
          description: Type of the message
          enum:
          - call
          - custom
          - email
          - facebook
          - front_chat
          - googleplay
          - intercom
          - internal
          - phone-call
          - sms
          - tweet
          - tweet_dm
          - whatsapp
          - yalo_wha
          example: email
        is_inbound:
          type: boolean
          description: Whether or not the message has been received or sent
          example: false
        draft_mode:
          type:
          - string
          - 'null'
          description: If the message is a draft, describes the draft mode. Can be 'private' (draft is visible to the author only) or 'shared' (draft is visible to all teammates with access to the conversation).
          enum:
          - shared
          - private
          example: shared
        error_type:
          type: string
          description: Type of the error when the draft failed to be sent
          example: null
        version:
          type: string
          description: The current version of the message in Front
          example: 551ba368f3e7803cce51503ee3e58ef0-26028-1701804863304-945c
        created_at:
          type: number
          description: The timestamp when the message was sent or received
          example: 1701292639
        subject:
          type: string
          description: Subject of the message
          example: Jim's pranks are getting out of hand
        blurb:
          type: string
          description: Preview of the message body
          example: It's high time we discuss the pranking culture in the office
        author:
          $ref: '#/components/schemas/TeammateResponse'
          description: Front teammate who sent this message
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/RecipientResponse'
        body:
          type: string
          description: Body of the message
          example: <p>Hi there,</p><p>I wanted to let you know that I'm suggesting an update to <a href='https://dundermifflin.com/privacy/pranks'>Dunder Mifflin's Pranking Policy</a> to provide non-humorous employees greater control over their well-being in the office.</p>
        text:
          type: string
          description: Text version of the body for email messages
          example: Hi there,\n\nI wanted to let you know that I'm suggesting an update to Dunder Mifflin's Pranking Policy (https://dundermifflin.com/privacy/pranks) to provide non-humorous employees greater control over their well-being in the office.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: List of files attached to the message
        signature:
          $ref: '#/components/schemas/SignatureResponse'
          description: The signature attached to this message
        metadata:
          type: object
          description: Optional metadata about the message
          properties:
            intercom_url:
              type: string
              description: For `intercom` messages only. URL of the Intercom conversation the message is coming from.
              example: http://intercom.com
            duration:
              type: integer
              description: For `truly-call` messages only. Length of the call in seconds.
              example: 189
            have_been_answered:
              type: boolean
              description: For `truly-call` messages only. Whether or not the call have been answered.
              example: false
            external_id:
              type: string
              description: For `tweet` or 'custom' (partner channel token authenticated) messages only. Unique message identifier in the underlying provider (Twitter or Partner). For custom messages, only present for partner channel token authenticated requests.
              example: dkd84992kdu

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