Get Mentioned Conversations

Get conversations where the current user, or a team they belong to, was mentioned in a private note. `mentioned_message_uuid` on each item points to the mention. Requires the `conversations:read` permission.

Abhinav Raut · Last updated Oct 23, 2026

GET /api/v1/conversations/mentioned

Get conversations where the current user, or a team they belong to, was mentioned in a private note. mentioned_message_uuid on each item points to the mention. Requires the conversations:read permission.

Authentication

Use an agent API key and secret.

Parameters

All parameters are query parameters. All parameters are optional.

Name	Type	Description
page	integer	Page number (defaults to 1) default: 1 minimum: 1
page_size	integer	Number of items per page (defaults to 30, max 500) default: 30 minimum: 1 maximum: 500
order	string (enum)	Sort direction (case-insensitive). Defaults to `desc`. enum: ["asc", "desc"]
order_by	string (enum)	Field to sort by, as `model.field`. Defaults to `conversations.last_message_at`. default: "conversations.last_message_at" enum: ["conversations.status_id", "conversations.priority_id", "conversations.assigned_team_id", "conversations.assigned_user_id", "conversations.inbox_id", "conversations.last_message_at", "conversations.last_interaction_at", "conversations.last_interaction_sender", "conversations.created_at", "conversations.waiting_since", "conversations.next_sla_deadline_at", "conversations.snoozed_until", "conversations.sla_policy_id", "conversation_statuses.id", "conversation_statuses.name", "users.email", "users.external_user_id", "inboxes.channel"]
filters	string	JSON-encoded filter. Either an array of conditions that are AND-ed, e.g. `[{"model":"conversations","field":"status_id","operator":"equals","value":"1"}]`, or a group `{"logic":"AND","rules":[...]}` with at most one level of nested groups. Operators: `equals`, `not equals`, `greater than`, `less than`, `set`, `not set`, `in`, `between`, `contains`, `ilike`, `not contains`. Filterable fields: `conversations` (status_id, priority_id, assigned_team_id, assigned_user_id, inbox_id, last_message_at, last_interaction_at, last_interaction_sender, created_at, waiting_since, next_sla_deadline_at, snoozed_until, sla_policy_id, tags), `conversation_statuses` (id, name), `users` (email, external_user_id), `inboxes` (channel).

Responses

200

Mentioned conversations retrieved successfully

Content type: application/json.

All fields are optional.

Field	Type	Description
status	string	example: "success"
data	object
data.results	array of object
data.results[].id	integer
data.results[].created_at	string (date-time)
data.results[].updated_at	string (date-time)
data.results[].uuid	string
data.results[].reference_number	string
data.results[].waiting_since	string (date-time)	nullable: true
data.results[].contact	object
data.results[].contact.created_at	string (date-time)
data.results[].contact.updated_at	string (date-time)
data.results[].contact.first_name	string
data.results[].contact.last_name	string
data.results[].contact.email	string (email)	nullable: true
data.results[].contact.avatar_url	string	nullable: true
data.results[].inbox_channel	string (enum)	enum: ["email", "livechat"]
data.results[].inbox_name	string
data.results[].sla_policy_id	integer	nullable: true
data.results[].first_reply_at	string (date-time)	nullable: true
data.results[].last_reply_at	string (date-time)	nullable: true
data.results[].resolved_at	string (date-time)	nullable: true
data.results[].last_resolved_at	string (date-time)	When the conversation last moved to a resolved status nullable: true
data.results[].subject	string	nullable: true
data.results[].last_message	string	nullable: true
data.results[].last_message_at	string (date-time)	nullable: true
data.results[].last_message_sender	string (enum)	enum: ["contact", "agent"] nullable: true
data.results[].last_interaction	string	nullable: true
data.results[].last_interaction_at	string (date-time)	nullable: true
data.results[].last_interaction_sender	string (enum)	enum: ["contact", "agent"] nullable: true
data.results[].next_sla_deadline_at	string (date-time)	nullable: true
data.results[].priority_id	integer	nullable: true
data.results[].assigned_user_id	integer	nullable: true
data.results[].assigned_team_id	integer	nullable: true
data.results[].assignee	object	Assigned agent, or null when no agent is assigned. nullable: true
data.results[].assignee.id	integer
data.results[].assignee.first_name	string
data.results[].assignee.last_name	string
data.results[].assignee.avatar_url	string	nullable: true
data.results[].assignee.type	string (enum)	enum: ["agent", "ai_assistant"]
data.results[].assignee.availability_status	string (enum)	enum: ["online", "away", "away_manual", "offline", "away_and_reassigning"]
data.results[].unread_message_count	integer
data.results[].status	string	nullable: true
data.results[].priority	string	nullable: true
data.results[].first_response_deadline_at	string (date-time)	nullable: true
data.results[].resolution_deadline_at	string (date-time)	nullable: true
data.results[].applied_sla_id	integer	nullable: true
data.results[].next_response_deadline_at	string (date-time)	nullable: true
data.results[].next_response_met_at	string (date-time)	nullable: true
data.results[].mentioned_message_uuid	string	UUID of the message the current agent was mentioned in, set only for mention lists nullable: true
data.total	integer
data.per_page	integer
data.total_pages	integer
data.page	integer

401

Unauthorized

Content type: application/json.

All fields are optional.

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

403

Forbidden

Content type: application/json.

Response fields match the 401 response.

500

Internal server error

Content type: application/json.

Response fields match the 401 response.

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/mentioned:
    get:
      tags:
        - Conversations
      summary: Get Mentioned Conversations
      description: >-
        Get conversations where the current user, or a team they belong to, was
        mentioned in a private note. `mentioned_message_uuid` on each item
        points to the mention. Requires the `conversations:read` permission.
      operationId: handleGetMentionedConversations
      parameters:
        - 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: order
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
          description: Sort direction (case-insensitive). Defaults to `desc`.
        - name: order_by
          in: query
          required: false
          schema:
            type: string
            enum:
              - conversations.status_id
              - conversations.priority_id
              - conversations.assigned_team_id
              - conversations.assigned_user_id
              - conversations.inbox_id
              - conversations.last_message_at
              - conversations.last_interaction_at
              - conversations.last_interaction_sender
              - conversations.created_at
              - conversations.waiting_since
              - conversations.next_sla_deadline_at
              - conversations.snoozed_until
              - conversations.sla_policy_id
              - conversation_statuses.id
              - conversation_statuses.name
              - users.email
              - users.external_user_id
              - inboxes.channel
            default: conversations.last_message_at
          description: >-
            Field to sort by, as `model.field`. Defaults to
            `conversations.last_message_at`.
        - name: filters
          in: query
          required: false
          schema:
            type: string
          description: >-
            JSON-encoded filter. Either an array of conditions that are AND-ed,
            e.g.
            `[{"model":"conversations","field":"status_id","operator":"equals","value":"1"}]`,
            or a group `{"logic":"AND","rules":[...]}` with at most one level of
            nested groups. Operators: `equals`, `not equals`, `greater than`,
            `less than`, `set`, `not set`, `in`, `between`, `contains`, `ilike`,
            `not contains`. Filterable fields: `conversations` (status_id,
            priority_id, assigned_team_id, assigned_user_id, inbox_id,
            last_message_at, last_interaction_at, last_interaction_sender,
            created_at, waiting_since, next_sla_deadline_at, snoozed_until,
            sla_policy_id, tags), `conversation_statuses` (id, name), `users`
            (email, external_user_id), `inboxes` (channel).
      responses:
        '200':
          description: Mentioned conversations retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConversationListResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          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:
    ConversationListResponse:
      type: object
      properties:
        status:
          type: string
          example: success
        data:
          type: object
          properties:
            results:
              type: array
              items:
                $ref: '#/components/schemas/ConversationListItem'
            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
    ConversationListItem:
      type: object
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        uuid:
          type: string
        reference_number:
          type: string
        waiting_since:
          type: string
          format: date-time
          nullable: true
        contact:
          $ref: '#/components/schemas/ContactSummary'
        inbox_channel:
          type: string
          enum:
            - email
            - livechat
        inbox_name:
          type: string
        sla_policy_id:
          type: integer
          nullable: true
        first_reply_at:
          type: string
          format: date-time
          nullable: true
        last_reply_at:
          type: string
          format: date-time
          nullable: true
        resolved_at:
          type: string
          format: date-time
          nullable: true
        last_resolved_at:
          type: string
          format: date-time
          nullable: true
          description: When the conversation last moved to a resolved status
        subject:
          type: string
          nullable: true
        last_message:
          type: string
          nullable: true
        last_message_at:
          type: string
          format: date-time
          nullable: true
        last_message_sender:
          type: string
          nullable: true
          enum:
            - contact
            - agent
        last_interaction:
          type: string
          nullable: true
        last_interaction_at:
          type: string
          format: date-time
          nullable: true
        last_interaction_sender:
          type: string
          nullable: true
          enum:
            - contact
            - agent
        next_sla_deadline_at:
          type: string
          format: date-time
          nullable: true
        priority_id:
          type: integer
          nullable: true
        assigned_user_id:
          type: integer
          nullable: true
        assigned_team_id:
          type: integer
          nullable: true
        assignee:
          $ref: '#/components/schemas/ConversationAssignee'
        unread_message_count:
          type: integer
        status:
          type: string
          nullable: true
        priority:
          type: string
          nullable: true
        first_response_deadline_at:
          type: string
          format: date-time
          nullable: true
        resolution_deadline_at:
          type: string
          format: date-time
          nullable: true
        applied_sla_id:
          type: integer
          nullable: true
        next_response_deadline_at:
          type: string
          format: date-time
          nullable: true
        next_response_met_at:
          type: string
          format: date-time
          nullable: true
        mentioned_message_uuid:
          type: string
          nullable: true
          description: >-
            UUID of the message the current agent was mentioned in, set only for
            mention lists
    ContactSummary:
      type: object
      properties:
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        first_name:
          type: string
        last_name:
          type: string
        email:
          type: string
          format: email
          nullable: true
        avatar_url:
          type: string
          nullable: true
    ConversationAssignee:
      type: object
      nullable: true
      description: Assigned agent, or null when no agent is assigned.
      properties:
        id:
          type: integer
        first_name:
          type: string
        last_name:
          type: string
        avatar_url:
          type: string
          nullable: true
        type:
          type: string
          enum:
            - agent
            - ai_assistant
        availability_status:
          type: string
          enum:
            - online
            - away
            - away_manual
            - offline
            - away_and_reassigning
  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`