freshworks Messages API

openapi: 3.2.0
info:
  title: Freshworks Freshchat Messages API
  description: The Freshchat API provides programmatic access to the Freshchat messaging platform for managing customer conversations and engagement. It supports operations for conversations, messages, agents, channels, and users. The API enables developers to automate customer communication workflows, integrate Freshchat with external systems, and build custom messaging solutions on top of the Freshchat platform. Authentication is handled via API tokens obtained from the Freshchat admin panel.
  version: '2.0'
  contact:
    name: Freshworks Support
    url: https://support.freshchat.com/
  termsOfService: https://www.freshworks.com/terms/
servers:
- url: https://{domain}.freshchat.com/v2
  description: Freshchat Production Server (Standalone)
  variables:
    domain:
      default: yourdomain
      description: Your Freshchat account name
- url: https://{domain}.myfreshworks.com/v2
  description: Freshchat Production Server (Freshsales Suite)
  variables:
    domain:
      default: yourdomain
      description: Your Freshworks bundle alias
security:
- bearerAuth: []
tags:
- name: Messages
  description: Send and retrieve messages within conversations.
paths:
  /conversations/{conversation_id}/messages:
    get:
      operationId: listConversationMessages
      summary: List messages in a conversation
      description: Retrieves all messages within a specific conversation, ordered by creation time.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/ConversationIdParam'
      - $ref: '#/components/parameters/PageParam'
      - $ref: '#/components/parameters/ItemsPerPageParam'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  messages:
                    type: array
                    items:
                      $ref: '#/components/schemas/Message'
                  links:
                    $ref: '#/components/schemas/PaginationLinks'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    post:
      operationId: sendMessage
      summary: Send a message in a conversation
      description: Sends a new message in an existing conversation. The message can be sent on behalf of an agent or the system.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/ConversationIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessageCreate'
      responses:
        '200':
          description: Message sent successfully
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  responses:
    BadRequest:
      description: The request body or parameters are invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code.
        message:
          type: string
          description: Human-readable error message.
    MessageCreate:
      type: object
      required:
      - message_parts
      - actor_type
      - actor_id
      properties:
        message_type:
          type: string
          description: Type of message.
          enum:
          - normal
          - private
          default: normal
        actor_type:
          type: string
          description: Type of actor sending the message.
          enum:
          - user
          - agent
        actor_id:
          type: string
          description: ID of the actor sending the message.
        message_parts:
          type: array
          description: Parts composing the message content.
          items:
            type: object
            properties:
              text:
                type: object
                properties:
                  content:
                    type: string
                    description: Text content.
    PaginationLinks:
      type: object
      properties:
        next_page:
          type: string
          format: uri
          description: URL for the next page of results.
        prev_page:
          type: string
          format: uri
          description: URL for the previous page of results.
    Message:
      type: object
      properties:
        id:
          type: string
          description: Unique ID of the message.
        message_type:
          type: string
          description: Type of message (normal, private, system).
          enum:
          - normal
          - private
          - system
        actor_type:
          type: string
          description: Type of actor who sent the message (user, agent, system).
          enum:
          - user
          - agent
          - system
        actor_id:
          type: string
          description: ID of the actor.
        message_parts:
          type: array
          description: Parts that compose the message content.
          items:
            type: object
            properties:
              text:
                type: object
                properties:
                  content:
                    type: string
                    description: Text content of the message part.
              image:
                type: object
                properties:
                  url:
                    type: string
                    format: uri
                    description: URL of the image.
        reply_parts:
          type: array
          description: Response enablers for agent or bot messages allowing quick replies.
          items:
            type: object
        created_time:
          type: string
          format: date-time
          description: Timestamp when the message was created.
  parameters:
    PageParam:
      name: page
      in: query
      description: Page number for pagination.
      schema:
        type: integer
        minimum: 1
        default: 1
    ConversationIdParam:
      name: conversation_id
      in: path
      required: true
      description: The ID of the conversation.
      schema:
        type: string
    ItemsPerPageParam:
      name: items_per_page
      in: query
      description: Number of items per page.
      schema:
        type: integer
        minimum: 1
        maximum: 50
        default: 20
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication. Obtain the API token from the Freshchat admin settings panel.
externalDocs:
  description: Freshchat API Documentation
  url: https://developers.freshchat.com/api/