Get Messages

Requires the `messages:read` permission.

Abhinav Raut · Last updated Sep 28, 2026

GET /api/v1/conversations/{uuid}/messages

Requires the messages:read permission.

Authentication

Use an agent API key and secret.

Parameters

Name	Location	Type	Required	Description
uuid	path	string	Yes	Conversation UUID
page	query	integer	No	Page number (defaults to 1) default: 1 minimum: 1
page_size	query	integer	No	Number of items per page (defaults to 30, max 500) default: 30 minimum: 1 maximum: 500
private	query	boolean	No	Filter by private messages (internal notes). If not provided, returns all messages.
type	query	array of string (enum)	No	Filter by message type. Can be specified multiple times (e.g., ?type=incoming&type=outgoing). If not provided, returns all messages.

Responses

200

Messages retrieved successfully

Content type: application/json.

Field	Type	Required	Description
status	string	No	example: "success"
data	object	No
data.results	array of object	No
data.results[].id	integer	No
data.results[].created_at	string (date-time)	No
data.results[].updated_at	string (date-time)	No
data.results[].uuid	string	No
data.results[].type	string (enum)	No	enum: ["incoming", "outgoing", "activity"]
data.results[].status	string (enum)	No	enum: ["pending", "sent", "received", "failed"]
data.results[].conversation_id	integer	No
data.results[].conversation_uuid	string	No
data.results[].content	string	No
data.results[].text_content	string	No
data.results[].content_type	string (enum)	No	enum: ["html", "text"]
data.results[].private	boolean	No
data.results[].sender_id	integer	No
data.results[].sender_type	string (enum)	No	enum: ["agent", "contact"]
data.results[].meta	object	No	nullable: true
data.results[].meta.to	array of string	No
data.results[].meta.to[]	string
data.results[].meta.cc	array of string	No
data.results[].meta.cc[]	string
data.results[].meta.bcc	array of string	No
data.results[].meta.bcc[]	string
data.results[].meta.from	array of string	No
data.results[].meta.from[]	string
data.results[].meta.subject	string	No
data.results[].attachments	array of object	No
data.results[].attachments[].name	string	No
data.results[].attachments[].size	integer	No
data.results[].attachments[].content	string (byte)	No	nullable: true
data.results[].attachments[].content_id	string	No
data.results[].attachments[].content_type	string	No
data.results[].attachments[].disposition	string (enum)	No	enum: ["inline", "attachment"]
data.results[].attachments[].uuid	string	No
data.results[].attachments[].url	string	No
data.results[].attachments[].thumbnail_url	string	No
data.results[].author	object	No
data.results[].author.id	integer	No
data.results[].author.first_name	string	No
data.results[].author.last_name	string	No
data.results[].author.email	string (email)	No	nullable: true
data.results[].author.avatar_url	string	No	nullable: true
data.results[].author.availability_status	string	No
data.results[].author.type	string (enum)	No	enum: ["agent", "contact", "visitor", "ai_assistant"]
data.results[].author.last_active_at	string (date-time)	No	nullable: true
data.total	integer	No
data.per_page	integer	No
data.total_pages	integer	No
data.page	integer	No

401

Unauthorized

Content type: application/json.

Field	Type	Required	Description
status	string	No	example: "error"
message	string	No	Error message example: "Invalid request"
data	unspecified	No	Additional error data nullable: true
error_type	string (enum)	No	enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

403

Forbidden

Content type: application/json.

Field	Type	Required	Description
status	string	No	example: "error"
message	string	No	Error message example: "Invalid request"
data	unspecified	No	Additional error data nullable: true
error_type	string (enum)	No	enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

404

Not found

Content type: application/json.

Field	Type	Required	Description
status	string	No	example: "error"
message	string	No	Error message example: "Invalid request"
data	unspecified	No	Additional error data nullable: true
error_type	string (enum)	No	enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

500

Internal server error

Content type: application/json.

Field	Type	Required	Description
status	string	No	example: "error"
message	string	No	Error message example: "Invalid request"
data	unspecified	No	Additional error data nullable: true
error_type	string (enum)	No	enum: ["GeneralException", "PermissionException", "InputException", "DataException", "NetworkException", "NotFoundException", "ConflictException", "UnauthorizedException", "RateLimitException"]

Specification

Download the complete OpenAPI specification.

OpenAPI definition for this endpoint

openapi: 3.0.0
info:
  title: Libredesk API
  description: >-
    REST API documentation for Libredesk helpdesk system.


    ## Authentication


    The Libredesk API supports two authentication methods:


    ### 1. Basic Authentication

    Use your API key and secret with Basic authentication:

    ```

    Authorization: Basic <base64_encoded_api_key:api_secret>

    ```


    ### 2. Token Authentication  

    Use your API key and secret with token authentication:

    ```

    Authorization: token api_key:api_secret

    ```


    To obtain API credentials, generate them from your agent profile in the
    Libredesk dashboard.
  version: 1.0.0
servers:
  - url: http://localhost:8080
    description: Local development server
security:
  - basicAuth: []
  - tokenAuth: []
paths:
  /api/v1/conversations/{uuid}/messages:
    get:
      tags:
        - Conversations
      summary: Get Messages
      description: Requires the `messages:read` permission.
      operationId: handleGetMessages
      parameters:
        - name: uuid
          in: path
          required: true
          schema:
            type: string
          description: Conversation UUID
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            default: 1
          description: Page number (defaults to 1)
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 30
          description: Number of items per page (defaults to 30, max 500)
        - name: private
          in: query
          required: false
          schema:
            type: boolean
          description: >-
            Filter by private messages (internal notes). If not provided,
            returns all messages.
        - name: type
          in: query
          required: false
          schema:
            type: array
            items:
              type: string
              enum:
                - incoming
                - outgoing
                - activity
          style: form
          explode: true
          description: >-
            Filter by message type. Can be specified multiple times (e.g.,
            ?type=incoming&type=outgoing). If not provided, returns all
            messages.
      responses:
        '200':
          description: Messages retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessageListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - basicAuth: []
        - tokenAuth: []
components:
  schemas:
    MessageListResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/Message'
            total:
              type: integer
            per_page:
              type: integer
            total_pages:
              type: integer
            page:
              type: integer
    ErrorResponse:
      type: object
      description: Error response format
      properties:
        status:
          type: string
          example: error
        message:
          type: string
          description: Error message
          example: Invalid request
        data:
          nullable: true
          description: Additional error data
        error_type:
          type: string
          enum:
            - GeneralException
            - PermissionException
            - InputException
            - DataException
            - NetworkException
            - NotFoundException
            - ConflictException
            - UnauthorizedException
            - RateLimitException
    Message:
      type: object
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        uuid:
          type: string
        type:
          type: string
          enum:
            - incoming
            - outgoing
            - activity
        status:
          type: string
          enum:
            - pending
            - sent
            - received
            - failed
        conversation_id:
          type: integer
        conversation_uuid:
          type: string
        content:
          type: string
        text_content:
          type: string
        content_type:
          type: string
          enum:
            - html
            - text
        private:
          type: boolean
        sender_id:
          type: integer
        sender_type:
          type: string
          enum:
            - agent
            - contact
        meta:
          type: object
          properties:
            to:
              type: array
              items:
                type: string
            cc:
              type: array
              items:
                type: string
            bcc:
              type: array
              items:
                type: string
            from:
              type: array
              items:
                type: string
            subject:
              type: string
          nullable: true
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/Attachment'
        author:
          $ref: '#/components/schemas/MessageAuthor'
    Attachment:
      type: object
      properties:
        name:
          type: string
        size:
          type: integer
        content:
          type: string
          format: byte
          nullable: true
        content_id:
          type: string
        content_type:
          type: string
        disposition:
          type: string
          enum:
            - inline
            - attachment
        uuid:
          type: string
        url:
          type: string
        thumbnail_url:
          type: string
    MessageAuthor:
      type: object
      properties:
        id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
          nullable: true
        avatar_url:
          type: string
          nullable: true
        availability_status:
          type: string
        type:
          type: string
          enum:
            - agent
            - contact
            - visitor
            - ai_assistant
        last_active_at:
          type: string
          format: date-time
          nullable: true
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        Basic authentication using base64 encoded API key and secret. Format:
        `Authorization: Basic <base64(api_key:api_secret)>`
    tokenAuth:
      type: apiKey
      name: Authorization
      in: header
      description: >-
        Token authentication using API key and secret. Format: `Authorization:
        token api_key:api_secret`

Was this article helpful?