Set a conversation's tags

Add MCP server to your AI tool

Allow AI tools and LLMs to interact with the API documentation portal through MCP.

MCP server URL

https://docs.usehearsay.com/mcp

Standard setup for AI tools providing an mcp.json file

mcp.json
{
  "integrations MCP server": {
    "url": "https://docs.usehearsay.com/mcp"
  }
}

Close
PATCH /case/conversations/{caseId}/{conversationId}/tags

Replaces the tags applied to a conversation and returns the conversation.

Headers

  • organization string Required

    id of the selected (active) organization

Path parameters

  • caseId string Required

    id of the case

  • conversationId string Required

    id of the conversation

application/json

Body Required

  • caseId string Required

    Id of the case the file belongs to. Required so @CaseAccess can authorize the caller (an OC included) on the case.

  • tags array[string] Required

    Array of tag ids or tag names. Replaces the existing tags with this list. Pass an empty array to remove all tags.

    At least 0 but not more than 100 elements.

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • createdAt string(date-time) Required
      • updatedAt string(date-time) Required
      • id string Required
      • messageSharing object Required
      • selectionCoverage object
      • name string Required
      • displayName string Required

        'Conversation with ' unless the name was edited, in which case the edited name as typed.

      • chatName string Required
      • originalDisplayName string Required
      • source string Required

        Values are message, whatsapp, voicemail, call_log, facebook_dump, instagram_dump, threads_dump, or email.

      • linkedContacts array[object] | null Required

        Not loaded by any route, so always null or an empty list.

      • device object Required

        The full record on routes that load it; null (or an empty list) on routes that do not.

        Hide device attributes Show device attributes object
        • createdAt string(date-time) Required
        • updatedAt string(date-time) Required
        • id string Required
        • deviceId string Required
        • serialNumber string Required
        • name string Required
        • type string Required
        • nonDeviceType string | null Required
        • model string Required
        • timeZone string Required
        • osVersion string Required
        • owner object | null Required

          Not loaded by any route, so always null.

        • devicePhoneNumber string Required
        • organizations array[string] Required

          Organization ids

        • extractionCodes array[string] Required

          Extraction code ids

        • availableData object

          Which data types exist for this device (optionally scoped by query filters).

      • avatar object Required

        The full record on routes that load it; null (or an empty list) on routes that do not.

        Hide avatar attributes Show avatar attributes object
        • createdAt string(date-time) Required
        • updatedAt string(date-time) Required
        • id string Required
        • name string Required
        • providerId string Required
        • convertedName string | null Required
        • convertedProviderId string Required
        • provider string Required
        • size number Required

          Size in bytes

        • transferState number | null Required
      • service string Required
      • lastMessageText string Required
      • firstMessageDate string(date-time) | null Required
      • lastMessageDate string(date-time) Required
      • displayNameEditedAt string(date-time) | null Required
      • lastMessageExternalId string Required
      • isGroup boolean Required

        Default value is false.

      • owner object | null Required

        Not loaded by any route, so always null.

      • isReadonly boolean Required
      • lastExportedAt string(date-time) | null Required
      • messagesCount number Required
      • archivedBy object | null Required

        Not loaded by any route, so always null.

      • archivedAt string(date-time) | null Required
      • starredAt string(date-time) | null Required
      • tags array[object] | null Required

        The full record on routes that load it; null (or an empty list) on routes that do not.

        Hide tags attributes Show tags attributes object
        • createdAt string(date-time) Required
        • updatedAt string(date-time) Required
        • id string Required
        • name string Required
        • nameLowercase string Required
        • backgroundColor string Required
        • textColor string Required
        • type string Required

          Values are system, organization, case, or user.

        • severity string Required

          Values are info, warning, or danger.

        • origin string Required

          Values are manual or auto-import.

        • creatorAccessType string | null

          Values are org or opposing_council.

        • isActive boolean Required
      • attachedTags array[object]
        Hide attachedTags attributes Show attachedTags attributes object
        • tagId string Required

          Tag id (Tag._id)

        • tag string Required

          Tag display name (Tag.name)

        • addedBy string Required

          Values are user, ai, auto, auto-import, system, or default.

        • addedById string | null
        • removedAt string(date-time) | null
        • removedBy string | null

          Values are user, ai, auto, auto-import, system, or default.

        • removedById string | null
      • isPlaceholder boolean Required
      • isArchived boolean Required
      • isStarred boolean Required
      • hasAllAttachmentProcessed boolean Required
      • processedAttachmentCount number Required
      • conversationName string Required
      • isNameEdited boolean Required
      • participantCount number Required
    • statusCode number Required
    • timestamp string(date-time) Required
PATCH /case/conversations/{caseId}/{conversationId}/tags
curl \
 --request PATCH 'http://api.example.com/case/conversations/{caseId}/{conversationId}/tags' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "organization: string" \
 --data '{
  "caseId": "string",
  "tags": [
    "string"
  ]
}'
Request examples
# Headers
organization: string

# Payload
{
  "caseId": "string",
  "tags": [
    "string"
  ]
}
Response examples (200)
{
  "data": {
    "createdAt": "2026-01-15T14:30:00.000Z",
    "updatedAt": "2026-01-15T14:30:00.000Z",
    "id": "507f1f77bcf86cd799439011",
    "messageSharing": {
      "sharedMessageCount": 320,
      "totalMessageCount": 1200,
      "totalReportedAt": "2026-01-15T14:30:00.000Z"
    },
    "selectionCoverage": {
      "app": "message",
      "conversationId": 42,
      "mode": "selected_messages",
      "selectedMessageCount": 320,
      "eligibleMessageCount": 1200,
      "includedMessageCount": 320,
      "omittedEligibleMessageCount": 880,
      "selectedNotIncludedCount": 0,
      "totalMessageCount": 1200,
      "deviceConversation": "507f1f77bcf86cd799439011",
      "ingestionStatus": "completed",
      "ingestedMessageCount": 320,
      "verifiedAt": "2026-01-15T14:30:00.000Z",
      "completedAt": "2026-01-15T14:30:00.000Z",
      "failedAt": null,
      "isPartial": true,
      "coverage": "selected_messages",
      "eligibleScope": "after_date_and_incremental_filters",
      "uploadAttemptId": "a3e6a3ab-2c6e-469c-a3ae-ab1e926c93c2",
      "deviceBackupId": "65a1b2c3d4e5f6a7b8c9d0e2",
      "reportOrder": "2026-01-15T14:30:00.000Z:65a1b2c3d4e5f6a7b8c9d0e2"
    },
    "name": "Jane Doe",
    "displayName": "Conversation with Jane Doe",
    "chatName": "+15555550100",
    "originalDisplayName": "Jane Doe",
    "source": "message",
    "linkedContacts": [
      {}
    ],
    "device": {
      "createdAt": "2026-01-15T14:30:00.000Z",
      "updatedAt": "2026-01-15T14:30:00.000Z",
      "id": "507f1f77bcf86cd799439011",
      "deviceId": "3F2504E0-4F89-11D3-9A0C-0305E82C3301",
      "serialNumber": "F2LXK0QJHG7F",
      "name": "Jane's iPhone",
      "type": "ios",
      "nonDeviceType": "string",
      "model": "iPhone 15",
      "timeZone": "America/New_York",
      "osVersion": "18.0",
      "owner": {},
      "devicePhoneNumber": "+15555550100",
      "organizations": [
        "507f1f77bcf86cd799439011"
      ],
      "extractionCodes": [
        "507f1f77bcf86cd799439013"
      ],
      "availableData": {
        "messages": true,
        "calls": false
      }
    },
    "avatar": {
      "createdAt": "2026-01-15T14:30:00.000Z",
      "updatedAt": "2026-01-15T14:30:00.000Z",
      "id": "507f1f77bcf86cd799439011",
      "name": "photo.heic",
      "providerId": "uploads/507f1f77bcf86cd799439011/photo.heic",
      "convertedName": "photo.jpg",
      "convertedProviderId": "uploads/507f1f77bcf86cd799439011/photo.jpg",
      "provider": "s3",
      "size": 204800,
      "transferState": 42.0
    },
    "service": "iMessage",
    "lastMessageText": "See you at 6",
    "firstMessageDate": "2025-03-01T09:00:00.000Z",
    "lastMessageDate": "2026-01-15T14:30:00.000Z",
    "displayNameEditedAt": "2026-05-04T09:42:00Z",
    "lastMessageExternalId": "58231",
    "isGroup": false,
    "owner": {},
    "isReadonly": false,
    "lastExportedAt": "2026-05-04T09:42:00Z",
    "messagesCount": 320,
    "archivedBy": {},
    "archivedAt": "2026-05-04T09:42:00Z",
    "starredAt": "2026-05-04T09:42:00Z",
    "tags": [
      {
        "createdAt": "2026-01-15T14:30:00.000Z",
        "updatedAt": "2026-01-15T14:30:00.000Z",
        "id": "507f1f77bcf86cd799439011",
        "name": "Important",
        "nameLowercase": "important",
        "backgroundColor": "#FDE68A",
        "textColor": "#92400E",
        "type": "system",
        "severity": "info",
        "origin": "manual",
        "creatorAccessType": "org",
        "isActive": true
      }
    ],
    "attachedTags": [
      {
        "tagId": "507f1f77bcf86cd799439011",
        "tag": "Important",
        "addedBy": "user",
        "addedById": "507f1f77bcf86cd799439012",
        "removedAt": "2026-05-04T09:42:00Z",
        "removedBy": "user",
        "removedById": "string"
      }
    ],
    "isPlaceholder": false,
    "isArchived": false,
    "isStarred": false,
    "hasAllAttachmentProcessed": true,
    "processedAttachmentCount": 12,
    "conversationName": "Conversation with Jane Doe",
    "isNameEdited": false,
    "participantCount": 2
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}