Compare conversations side by side

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
POST /conversation/compare

Merges messages from several conversations into one timeline, grouped by minute (up to 200 groups per page). Pass the returned next token to get the following page.

Headers

  • organization string Required

    id of the selected (active) organization

application/json

Body Required

  • case string

    Required if caseSlug not present

  • caseSlug string

    Required if case not present

  • conversations array[string] Required

    ID of the conversations to compare

  • startDate string(date-time)
  • endDate string(date-time)
  • sortDirection string

    Values are asc or desc. Default value is asc.

  • nextToken string

Responses

  • 200 application/json
    Hide response attributes Show response attributes object
    • data object Required
      Hide data attributes Show data attributes object
      • next string | null

        Opaque cursor for the next page; null on the last page

      • data array[object]
        Hide data attributes Show data attributes object
        • _id string(date-time)

          Start of the minute

        • date string(date-time)
        • count number
        • messages array[object]
          Hide messages attributes Show messages attributes object
          • text string | 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
            • name string Required
            • nameLowercase string Required
          • deviceType string | null Required
          • sender object Required

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

            Hide sender attributes Show sender attributes object
            • fullName string Required
            • firstName string Required
            • phoneNational array[string] Required
            • 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
              • name string Required
              • convertedName string | null Required
              • transferState number | null Required

                Values are 0, 1, 5, 6, or 7.

              • totalBytes number | null Required
            • initials string Required
            • isEdited boolean | null Required

              True when the contact name was edited after import. When it was not edited the value is usually false, but because of how it is computed it can also be null, an empty string, or missing.

          • receiver object Required

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

            Hide receiver attributes Show receiver attributes object
            • fullName string Required
            • firstName string Required
            • phoneNational array[string] Required
            • 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
              • name string Required
              • convertedName string | null Required
              • transferState number | null Required

                Values are 0, 1, 5, 6, or 7.

              • totalBytes number | null Required
            • initials string Required
            • isEdited boolean | null Required

              True when the contact name was edited after import. When it was not edited the value is usually false, but because of how it is computed it can also be null, an empty string, or missing.

          • isEmpty boolean Required
          • iMessageType string Required

            Values are na, text, text-with-attachment, group_title_action, group_picture_action, location_share_start_stop, group_member_added, group_member_removed, face_time, message-layout, location, link, file_attached, or unsent.

          • isFromMe boolean Required
          • isDelivered boolean Required
          • isDeleted boolean Required
          • isMissingMedia boolean Required
          • isSystemMessage boolean Required
          • attachment object Required

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

            Hide attachment attributes Show attachment attributes object
            • name string Required
            • convertedName string | null Required
            • transferState number | null Required

              Values are 0, 1, 5, 6, or 7.

            • totalBytes number | null Required
          • additionalAttachments array[object] | null Required

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

            Hide additionalAttachments attributes Show additionalAttachments attributes object
            • name string Required
            • convertedName string | null Required
            • transferState number | null Required

              Values are 0, 1, 5, 6, or 7.

            • totalBytes number | null Required
          • date string(date-time) | null Required
          • sentAt string(date-time) | null Required
          • readAt string(date-time) | null Required
          • deletedAt string(date-time) | null Required
          • recoveredAt string(date-time) | null Required
          • parentMessageText string | null Required

            Text of the message this one replies to; null when it is not a reply.

          • parentMessageAttachment object Required
            Hide parentMessageAttachment attributes Show parentMessageAttachment attributes object
            • name string Required
            • convertedName string | null Required
            • transferState number | null Required

              Values are 0, 1, 5, 6, or 7.

            • totalBytes number | null Required
          • parentMessageIndex number | null Required

            Index of the message this one replies to; null when it is not a reply.

          • service string Required
          • mimeType string Required
          • editHistory array[object] | null Required
          • deletedMessagesLogs object | null Required
          • messageIndex number 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
          • ocSharedStatus string | null

            Opposing-council only: how this conversation entry has been shared with the OL. Omitted (null) for non-OC callers.

            Values are shared, pending, or not_gated.

          • collectionCount number Required
          • durationInSeconds number | null Required

            Voicemail length in seconds; null unless the message is a voicemail.

          • callDurationInSeconds number | null Required

            Call length in seconds; null unless the message is a call.

          • callType string Required

            Call direction: 'incoming', 'outgoing', 'rejected' or 'not_connected'; an empty string unless the message is a call.

          • callSource string | null Required
          • conversationId string Required
    • statusCode number Required
    • timestamp string(date-time) Required
POST /conversation/compare
curl \
 --request POST 'http://api.example.com/conversation/compare' \
 --header "Authorization: Bearer $ACCESS_TOKEN" \
 --header "Content-Type: application/json" \
 --header "organization: string" \
 --data '{
  "case": "string",
  "caseSlug": "string",
  "conversations": [
    "string"
  ],
  "startDate": "2026-05-04T09:42:00Z",
  "endDate": "2026-05-04T09:42:00Z",
  "sortDirection": "asc",
  "nextToken": "string"
}'
Request examples
# Headers
organization: string

# Payload
{
  "case": "string",
  "caseSlug": "string",
  "conversations": [
    "string"
  ],
  "startDate": "2026-05-04T09:42:00Z",
  "endDate": "2026-05-04T09:42:00Z",
  "sortDirection": "asc",
  "nextToken": "string"
}
Response examples (200)
{
  "data": {
    "next": "eyJkYXRlIjoiMjAyNi0wMS0xNVQxNDozMTowMC4wMDBaIn0",
    "data": [
      {
        "_id": "2026-05-04T09:42:00Z",
        "date": "2026-05-04T09:42:00Z",
        "count": 3,
        "messages": [
          {
            "text": "See you at 6",
            "tags": [
              {
                "name": "Important",
                "nameLowercase": "important"
              }
            ],
            "deviceType": "ios",
            "sender": {
              "fullName": "Jane Doe",
              "firstName": "Jane",
              "phoneNational": [
                "(555) 555-0100"
              ],
              "avatar": {
                "name": "IMG_0001.HEIC",
                "convertedName": "IMG_0001_display.png",
                "transferState": 5,
                "totalBytes": 2483120
              },
              "initials": "JD",
              "isEdited": false
            },
            "receiver": {
              "fullName": "Jane Doe",
              "firstName": "Jane",
              "phoneNational": [
                "(555) 555-0100"
              ],
              "avatar": {
                "name": "IMG_0001.HEIC",
                "convertedName": "IMG_0001_display.png",
                "transferState": 5,
                "totalBytes": 2483120
              },
              "initials": "JD",
              "isEdited": false
            },
            "isEmpty": false,
            "iMessageType": "na",
            "isFromMe": true,
            "isDelivered": true,
            "isDeleted": false,
            "isMissingMedia": false,
            "isSystemMessage": false,
            "attachment": {
              "name": "IMG_0001.HEIC",
              "convertedName": "IMG_0001_display.png",
              "transferState": 5,
              "totalBytes": 2483120
            },
            "additionalAttachments": [
              {
                "name": "IMG_0001.HEIC",
                "convertedName": "IMG_0001_display.png",
                "transferState": 5,
                "totalBytes": 2483120
              }
            ],
            "date": "2026-01-15T14:30:00.000Z",
            "sentAt": "2026-01-15T14:30:00.000Z",
            "readAt": "2026-01-15T14:30:00.000Z",
            "deletedAt": "2026-05-04T09:42:00Z",
            "recoveredAt": "2026-05-04T09:42:00Z",
            "parentMessageText": "Are we still on for dinner?",
            "parentMessageAttachment": {
              "name": "IMG_0001.HEIC",
              "convertedName": "IMG_0001_display.png",
              "transferState": 5,
              "totalBytes": 2483120
            },
            "parentMessageIndex": 41,
            "service": "iMessage",
            "mimeType": "image/jpeg",
            "editHistory": [
              {
                "date": "2026-01-15T14:30:00.000Z",
                "text": "See you at 7"
              }
            ],
            "deletedMessagesLogs": {
              "total": 2,
              "minDate": "2026-01-15T14:05:00.000Z",
              "maxDate": "2026-01-15T14:20:00.000Z",
              "deletedMessages": []
            },
            "messageIndex": 42,
            "attachedTags": [
              {
                "tagId": "507f1f77bcf86cd799439011",
                "tag": "Important",
                "addedBy": "user",
                "addedById": "507f1f77bcf86cd799439012",
                "removedAt": "2026-05-04T09:42:00Z",
                "removedBy": "user",
                "removedById": "string"
              }
            ],
            "ocSharedStatus": "shared",
            "collectionCount": 1,
            "durationInSeconds": 32,
            "callDurationInSeconds": 125,
            "callType": "incoming",
            "callSource": "phone",
            "conversationId": "65a1b2c3d4e5f6a7b8c9d0e2"
          }
        ]
      }
    ]
  },
  "statusCode": 200,
  "timestamp": "2026-01-15T10:15:00.000Z"
}