Activities Search API using GraphQL - User Guide

Overview

The searchActivities query allows clients to:

Filter activities using flexible nested AND/OR logic
Apply pagination to control the number of returned results
Sort results by specific fields
Select specific fields to minimize payload size

Default Behavior

If no query parameters are provided, the API will return the top 10 most recent activities based on timestamp in descending order (latest first).

This default behavior helps:

Quickly fetch the latest activity without crafting specific filters
Serve lightweight queries for basic use cases like recent history views

Query Structure

GraphQL

query {
  searchActivities(
    filter: {
        and: [
            {
                key: "timestamp", 
                operator: greater_than, 
                value: "2025-10-17T07:34:26Z"
            },
            {
                key: "timestamp", 
                operator: less_than, 
                value: "2025-10-17T07:34:27Z"
            }
        ]
    }
    pagination: { limit: 5, offset: 0 },
    sort: { sortBy: "timestamp", sortOrder: ASC }
  ) {
    docs {
      id
      timestamp
      activity {
        type
        name
        eventEmitter {
            id
            senderName
            type
        }
        channelSession {
            channelData {
                channelCustomerIdentifier
            }
        }
      }
    }
    totalDocs
    limit
    offset
  }
}

Supported Operators

Operator	Description
`equal_to`	Matches values that are exactly equal
`not_equal_to`	Matches values that are not equal
`greater_than`	Matches values greater than the input
`greater_than_equal_to`	Matches values greater than or equal
`less_than`	Matches values less than the input
`less_than_equal_to`	Matches values less than or equal
`starts_with`	Matches strings that start with the value
`ends_with`	Matches strings that end with the value
`contains`	Matches strings that contain the value

What is a partial text match?

Partial text matches allow searching within string fields using patterns. For example:

starts_with: "Ali" matches "Ali Raza" but not "Raza Ali"
contains: "Ali" matches "Raza Ali" and "Ali Raza"

Partial text matches (using operators like starts_with, ends_with, and contains) are case insensitive. For example, contains: "alex" will match "Alex", "ALEX", or "alexander" equally.

Allowed Filter Fields

Only the following fields can be used in the filter input:

- id
- timestamp
- conversationId
- activity.channelSession.channelData.channelCustomerIdentifier
- activity.name
- activity.type
- activity.data.header.sender.id
- activity.data.header.sender.senderName
- activity.data.header.sender.type
- activity.data.body.type
- activity.data.body.formId
- activity.data.body.formTitle
- activity.data.body.additionalDetail.submissionSource
- activity.data.body.additionalDetail.review.id
- activity.data.body.additionalDetail.agentReviewed.id
- activity.data.body.additionalDetail.agentReviewed.name
- activity.data.body.additionalDetail.formScore

Any attempt to filter using other fields will result in a validation error.

Pagination is applied using the pagination input:

pagination: { limit: 10, offset: 0 }

limit: Maximum number of results to return
offset: Number of results to skip

Sorting

Results can be sorted using the sort input:

sort: { sortBy: "timestamp", sortOrder: DESC }

sortBy: Must be one of the allowed filter fields
sortOrder: Either ASC or DESC

Usage of Timestamps in Filters

Timestamp fields like timestamp can be filtered using various operators (equal_to, greater_than, less_than, etc.). These fields expect values in ISO 8601 format.

You can specify timestamps in two ways:

UTC with 'Z' suffix: This indicates Coordinated Universal Time.
- Example: "2025-07-01T00:00:00Z"
With a timezone offset: This specifies the time and its offset from UTC.
- Example: "2025-07-01T05:00:00+05:00" (For PKT, which is UTC+5)
- Example: "2025-07-01T10:00:00-04:00" (For Eastern Daylight Time, which is UTC-4)

Example Queries

Filter by Id

GraphQL

query {
  searchActivities(
    filter: {
        key: "id", 
        operator: equal_to, 
        value: "68f1f31fa8b8c251e9329e19"
        }
    pagination: { limit: 5, offset: 0 },
    sort: { sortBy: "timestamp", sortOrder: ASC }
  ) {
    docs {
      id
      timestamp
      activity {
        type
        name
        channelSession {
            channelData {
                channelCustomerIdentifier
            }
        }
      }
    }
    totalDocs
    limit
    offset
  }
}

Filter by Timestamp Range

GraphQL

query {
  searchActivities(
    filter: {
        and: [
            {
                key: "timestamp", 
                operator: greater_than, 
                value: "2025-10-17T07:34:26Z"
            },
            {
                key: "timestamp", 
                operator: less_than, 
                value: "2025-10-17T07:34:27Z"
            }
        ]
    }
    pagination: { limit: 5, offset: 0 },
    sort: { sortBy: "timestamp", sortOrder: ASC }
  ) {
    docs {
      id
      timestamp
      activity {
        type
        name
        eventEmitter {
            id
            senderName
            type
        }
        channelSession {
            channelData {
                channelCustomerIdentifier
            }
        }
      }
    }
    totalDocs
    limit
    offset
  }
}

Filter by Sender Name

GraphQL

query {
  searchActivities(
    filter: {
        key: "activity.data.header.sender.senderName",
        operator: equal_to, 
        value: "32432434"
    }
    pagination: { limit: 5, offset: 0 },
    sort: { sortBy: "timestamp", sortOrder: ASC }
  ) {
    docs {
      id
      timestamp
      activity {
        type
        name
        channelSession {
            channelData {
                channelCustomerIdentifier
            }
        }
        data
      }
    }
    totalDocs
    limit
    offset
  }
}

Combined filters: timestamp + type

GraphQL

query {
  searchActivities(
    filter: {
      and: [
        { key: "timestamp", operator: greater_than_equal_to, value: "2025-10-17T07:34:26Z" },
        { key: "activity.type", operator: equal_to, value: "MESSAGE" }
      ]
    }
  ) {
    docs {
      id
      timestamp
      activity {
        type
        name
        channelSession {
            channelData {
                channelCustomerIdentifier
            }
        }
      }
    }
    totalDocs
    limit
    offset
  }
}

Best Practices

Use field projections: Only request fields you need to reduce response size.
Combine AND/OR filters wisely for efficient querying.
Always refer to the allowed filter fields list when designing queries.