freshdesk Conversations API

openapi: 3.1.0
info:
  title: Freshdesk REST Agents Conversations API
  description: The Freshdesk REST API (v2) provides programmatic access to helpdesk data and operations within Freshdesk, a customer support platform by Freshworks. It exposes endpoints for managing tickets, contacts, companies, agents, groups, conversations, products, email configurations, SLA policies, business hours, time entries, satisfaction ratings, solution categories, solution folders, solution articles, and more. The API uses JSON for request and response payloads, supports API key-based authentication, and follows RESTful conventions for CRUD operations.
  version: '2.0'
  contact:
    name: Freshdesk Support
    url: https://support.freshdesk.com/
  termsOfService: https://www.freshworks.com/terms/
servers:
- url: https://{domain}.freshdesk.com/api/v2
  description: Freshdesk Production Server
  variables:
    domain:
      default: yourdomain
      description: Your Freshdesk subdomain, e.g. if your helpdesk URL is acme.freshdesk.com, use acme.
security:
- basicAuth: []
tags:
- name: Conversations
  description: Manage replies, notes, and conversation threads on tickets.
paths:
  /tickets/{ticket_id}/conversations:
    get:
      operationId: listTicketConversations
      summary: List conversations on a ticket
      description: Retrieves all conversations (replies and notes) associated with the specified ticket.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ticketId'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/perPage'
      responses:
        '200':
          description: Successfully retrieved conversations.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/reply:
    post:
      operationId: replyToTicket
      summary: Reply to a ticket
      description: Adds a reply to the specified ticket. The reply is sent as an email to the requester and any CC'd addresses.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ticketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReplyCreate'
      responses:
        '201':
          description: Reply created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/notes:
    post:
      operationId: createNote
      summary: Create a note on a ticket
      description: Adds an internal or public note to the specified ticket. Private notes are visible only to agents.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ticketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NoteCreate'
      responses:
        '201':
          description: Note created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /tickets/{ticket_id}/forward:
    post:
      operationId: forwardTicket
      summary: Forward a ticket
      description: Forwards the specified ticket to one or more email addresses.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/ticketId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - body
              - to_emails
              properties:
                body:
                  type: string
                  description: Content of the forward message in HTML format.
                to_emails:
                  type: array
                  items:
                    type: string
                    format: email
                  description: Email addresses to forward the ticket to.
      responses:
        '201':
          description: Ticket forwarded successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
  /conversations/{conversation_id}:
    put:
      operationId: updateConversation
      summary: Update a conversation
      description: Updates the body of an existing conversation (reply or note).
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/conversationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                body:
                  type: string
                  description: Updated content of the conversation in HTML format.
      responses:
        '200':
          description: Conversation updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Conversation'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteConversation
      summary: Delete a conversation
      description: Deletes a conversation (note) from a ticket. Only notes can be deleted; replies cannot be removed.
      tags:
      - Conversations
      parameters:
      - $ref: '#/components/parameters/conversationId'
      responses:
        '204':
          description: Conversation deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    NoteCreate:
      type: object
      required:
      - body
      properties:
        body:
          type: string
          description: Content of the note in HTML format.
        private:
          type: boolean
          description: Whether the note is private (visible only to agents). Default true.
          default: true
        incoming:
          type: boolean
          description: Whether the note is incoming (from a customer).
          default: false
        notify_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to notify about the note.
    Attachment:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the attachment.
        name:
          type: string
          description: File name of the attachment.
        content_type:
          type: string
          description: MIME type of the attachment.
        size:
          type: integer
          description: File size in bytes.
        attachment_url:
          type: string
          format: uri
          description: URL to download the attachment.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the attachment was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the attachment was last updated.
    ReplyCreate:
      type: object
      required:
      - body
      properties:
        body:
          type: string
          description: Content of the reply in HTML format.
        cc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to CC on the reply.
        bcc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses to BCC on the reply.
    Conversation:
      type: object
      properties:
        id:
          type: integer
          format: int64
          description: Unique identifier of the conversation.
        body:
          type: string
          description: Content of the conversation in HTML format.
        body_text:
          type: string
          description: Content of the conversation in plain text.
        incoming:
          type: boolean
          description: Whether the conversation was incoming (from a customer).
        private:
          type: boolean
          description: Whether the conversation is a private note.
        user_id:
          type: integer
          format: int64
          description: ID of the user who created the conversation.
        ticket_id:
          type: integer
          format: int64
          description: ID of the ticket the conversation belongs to.
        support_email:
          type: string
          format: email
          nullable: true
          description: Support email address used for the conversation.
        to_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses in the To field.
        cc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses CC'd on the conversation.
        bcc_emails:
          type: array
          items:
            type: string
            format: email
          description: Email addresses BCC'd on the conversation.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
          description: Files attached to the conversation.
        source:
          type: integer
          description: Source of the conversation.
        created_at:
          type: string
          format: date-time
          description: Timestamp when the conversation was created.
        updated_at:
          type: string
          format: date-time
          description: Timestamp when the conversation was last updated.
    Error:
      type: object
      properties:
        description:
          type: string
          description: Human-readable error description.
        errors:
          type: array
          items:
            type: object
            properties:
              field:
                type: string
                description: Field that caused the error.
              message:
                type: string
                description: Error message for the field.
              code:
                type: string
                description: Error code.
  responses:
    Unauthorized:
      description: Authentication failed or credentials were not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is invalid or malformed.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  parameters:
    perPage:
      name: per_page
      in: query
      description: Number of results per page (max 100).
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 30
    ticketId:
      name: ticket_id
      in: path
      required: true
      description: Unique identifier of the ticket.
      schema:
        type: integer
        format: int64
    page:
      name: page
      in: query
      description: Page number for paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
    conversationId:
      name: conversation_id
      in: path
      required: true
      description: Unique identifier of the conversation.
      schema:
        type: integer
        format: int64
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: Freshdesk uses API key-based authentication. Pass your API key as the username with any string (e.g. X) as the password using HTTP Basic Authentication.
externalDocs:
  description: Freshdesk API Documentation
  url: https://developers.freshdesk.com/api/