Reference
Inbox Reads
Conversations, threads, search, media, collections and labels
Reads need MESSAGES_READ; internal notes need NOTES_WRITE; unmasked identity needs PII_READ. See Reading the inbox.
activeLabels
Query
ScopeMESSAGES_READ
Returns
_idString!nameString!organisationIdString!colorString!activeBoolean!archivedBoolean!isSystemBoolean!descriptionStringcreatedAtDateTime!updatedAtDateTime!query {
activeLabels { _id name organisationId color active }
}allMedia
Query
ScopeMESSAGES_READ
Returns
_idString!urlString!typeMediaType!filenameStringwidthFloatheightFloatfileSizeFloatdurationFloatsupportsStreamingBooleandisableContentTypeDetectionBooleanperformerStringtitleStringmimeTypeStringthumbnailThumbnailframes[Thumbnail!]isAnimatedBooleanisVideoBooleanemojiStringsetNameStringcustomEmojiIdStringstickerTypeStringneedsRepaintingBooleanprocessedContentStringProcessed/extracted text content for knowledge base
isProcessedBooleanWhether file processing is complete for knowledge base
query {
allMedia { _id url type filename width }
}apiSearchChatMessages
Queryexpensive
ScopeMESSAGES_READ
Search messages inside one chat of your organisation (API key, messages:read).
Arguments
SearchMessagesInput
chatIdStringFilter by specific chat ID
collectionIdOrSlugStringFilter by collection ID or slug to search within matching chats
Filter by rules (for preview before saving a collection). Takes precedence over collectionIdOrSlug.
conversationIdStringFilter to all threads of this conversation
PaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
apiSearchChatMessages(chatId: "…", input: { … }, pagination: { … }) { data nextCursor previousCursor hasNext hasPrevious }
}apiSearchMessages
Queryexpensive
ScopeMESSAGES_READ
Search messages across your organisation (API key, messages:read).
Arguments
paginationPaginateMessagesInputSearchMessagesInput
chatIdStringFilter by specific chat ID
collectionIdOrSlugStringFilter by collection ID or slug to search within matching chats
Filter by rules (for preview before saving a collection). Takes precedence over collectionIdOrSlug.
conversationIdStringFilter to all threads of this conversation
PaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
apiSearchMessages(input: { … }, pagination: { … }) { data nextCursor previousCursor hasNext hasPrevious }
}chat
Query
ScopeMESSAGES_READ
Arguments
chatIdString!RequiredcollectionIdOrSlugStringReturns
_idString!chatIdFloatexternalChatIdStringbusinessConnectionIdStringexternalUserIdStringtypeChatType!titleStringusernameStringfirstNameStringlastNameStringisForumBooleanlastMessageMessagelastMessageAtDateTimeprofilePeoplechannelIdentityChannelIdentityintegrationIdStringIntegration ID (use integration field for full details)
createdAtDateTimeupdatedAtDateTimeunReadCountFloatengagedBooleanTrue once the conversation has real engagement (a visitor inbound message OR a human-operator message).
false = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.isBlockedBooleanverified[String!]isAIActiveBooleanstatusChatStatusquery {
chat(chatId: "…", collectionIdOrSlug: "…") { _id chatId externalChatId businessConnectionId externalUserId }
}chatCollection
Query
ScopeMESSAGES_READ
Arguments
idOrSlugString!RequiredReturns
_idString!nameString!slugString!descriptionStringiconStringcolorStringpositionFloat!isSystemBoolean!systemKeyStringisVisibleBoolean!isLockedBoolean!planLockedBoolean!rules[CollectionRule!]!createdByStringchatCountFloatcreatedAtDateTime!updatedAtDateTime!query {
chatCollection(idOrSlug: "…") { _id name slug description icon }
}chatCollectionCounts
Queryexpensive
ScopeMESSAGES_READ
Arguments
collectionIds[String!]!RequiredReturns
query {
chatCollectionCounts(collectionIds: "…") { collectionId count }
}chatCollections
Query
ScopeMESSAGES_READ
Arguments
includeSystemBoolean!Defaults to
true.includeHiddenBoolean!Defaults to
false.Returns
_idString!nameString!slugString!descriptionStringiconStringcolorStringpositionFloat!isSystemBoolean!systemKeyStringisVisibleBoolean!isLockedBoolean!planLockedBoolean!rules[CollectionRule!]!createdByStringchatCountFloatcreatedAtDateTime!updatedAtDateTime!query {
chatCollections(includeSystem: false, includeHidden: false) { _id name slug description icon }
}collectionChatCount
Query
ScopeMESSAGES_READ
Arguments
collectionIdOrSlugString!RequiredReturns
Float!query {
collectionChatCount(collectionIdOrSlug: "…")
}collectionChats
Query
ScopeMESSAGES_READ
Arguments
GetCursorPaginatedInput
cursorStringlimitIntbeforeBooleanGetSortedInput
sortByString!RequiredsortOrderString!RequiredReturns
query {
collectionChats(collectionIdOrSlug: "…", pagination: { … }, sort: { … }) { previousCursor nextCursor hasPrevious hasNext data }
}collectionConversations
Query
ScopeMESSAGES_READ
Arguments
GetCursorPaginatedInput
cursorStringlimitIntbeforeBooleanGetSortedInput
sortByString!RequiredsortOrderString!RequiredReturns
query {
collectionConversations(collectionIdOrSlug: "…", pagination: { … }, sort: { … }) { previousCursor nextCursor hasPrevious hasNext data }
}conversation
Query
ScopeMESSAGES_READ
Arguments
idID!RequiredReturns
_idString!createdAtDateTime!updatedAtDateTime!unReadCountIntengagedBooleanTrue once the conversation has real engagement (a visitor inbound message OR a human-operator message).
false = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.lastMessageMessagelastMessageAtDateTimelastActivityAtDateTimestatusConversationStatusthreads[Chat!]!primaryThreadChat!analytics[PeopleFieldValue!]!channels[ConversationChannel!]!threadStatusConversationStatusisBlockedBoolean!The contact PERSON-level block flag (People IS_BLOCKED), not a single thread chat-level override. Drives the conversation-level block toggle label.
hasBlockedThreadBoolean!True when ANY thread of the conversation is blocked (the thread UNION) - i.e. the conversation is a member of its org
blocked collection. Drives the inbox row / conversation header block mark. Distinct from isBlocked (the person-level flag driving the block toggle, read from one representative thread).assignedToUserRollup: the common operator across open threads, else null (see assignees).
assignees[User!]!Distinct operators across the open threads (empty=none, 1=agree, several=diverge).
assignedStatusChatAssignmentStatusConversation-level connection state - PENDING when assignedTo set, else null; CONNECTED is per-thread-only.
channelGroups[ConversationChannelGroup!]!query {
conversation(id: "…") { _id createdAt updatedAt unReadCount engaged }
}conversationMedia
Query
ScopeMESSAGES_READ
Arguments
PaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
conversationMedia(conversationId: "…", pagination: { … }, mediaTypes: […]) { data nextCursor previousCursor hasNext hasPrevious }
}conversationMediaCounts
Query
ScopeMESSAGES_READ
Arguments
conversationIdString!RequiredReturns
query {
conversationMediaCounts(conversationId: "…") { type count }
}conversationMessages
Query
ScopeMESSAGES_READ
Arguments
PaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
conversationMessages(conversationId: "…", pagination: { … }, messageId: "…") { data nextCursor previousCursor hasNext hasPrevious }
}conversationNotes
Query
ScopeNOTES_WRITE
Arguments
conversationIdString!RequiredpaginationPaginateMessagesInputPaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
conversationNotes(conversationId: "…", pagination: { … }) { data nextCursor previousCursor hasNext hasPrevious }
}getChatMedia
Query
ScopeMESSAGES_READ
Arguments
PaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
getChatMedia(chatId: "…", pagination: { … }, mediaTypes: […]) { data nextCursor previousCursor hasNext hasPrevious }
}getChatMediaCounts
Query
ScopeMESSAGES_READ
Arguments
chatIdString!RequiredReturns
query {
getChatMediaCounts(chatId: "…") { type count }
}getChatNotes
Query
ScopeNOTES_WRITE
Arguments
chatIdString!RequiredpaginationPaginateMessagesInputPaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
getChatNotes(chatId: "…", pagination: { … }) { data nextCursor previousCursor hasNext hasPrevious }
}getMessages
Query
ScopeMESSAGES_READ
Arguments
PaginateMessagesInput
cursorStringisBeforeBooleanlimitInt!RequiredReturns
data[Message!]!nextCursorStringpreviousCursorStringhasNextBoolean!hasPreviousBoolean!unreadCountFloattotalMessagesFloatTotal count of messages matching the query (only for search)
totalChatsFloatTotal count of chats matching the filters (only for search)
query {
getMessages(chatId: "…", pagination: { … }, messageId: "…") { data nextCursor previousCursor hasNext hasPrevious }
}inboxCounts
Queryexpensive
ScopeMESSAGES_READ
Returns
query {
inboxCounts { all mine mentions perCollection }
}label
Query
ScopeMESSAGES_READ
Arguments
idString!RequiredReturns
_idString!nameString!organisationIdString!colorString!activeBoolean!archivedBoolean!isSystemBoolean!descriptionStringcreatedAtDateTime!updatedAtDateTime!query {
label(id: "…") { _id name organisationId color active }
}labels
Query
ScopeMESSAGES_READ
Arguments
includeArchivedBoolean!Defaults to
false.Returns
_idString!nameString!organisationIdString!colorString!activeBoolean!archivedBoolean!isSystemBoolean!descriptionStringcreatedAtDateTime!updatedAtDateTime!query {
labels(includeArchived: false) { _id name organisationId color active }
}searchChats
Queryexpensive
ScopeMESSAGES_READ
Arguments
SearchChatsInput
collectionIdOrSlugStringFilter by collection ID or slug to search within matching chats
Filter by rules (for preview before saving a collection). Combined with collection rules if collectionIdOrSlug is also provided.
GetCursorPaginatedInput
cursorStringlimitIntbeforeBooleanGetSortedInput
sortByString!RequiredsortOrderString!RequiredReturns
data[Chat!]!previousCursorStringnextCursorStringhasPreviousBoolean!hasNextBoolean!totalCountIntTotal count of chats matching the filters (only on first page)
query {
searchChats(input: { … }, pagination: { … }, sort: { … }) { data previousCursor nextCursor hasPrevious hasNext }
}searchConversations
Queryexpensive
ScopeMESSAGES_READ
Arguments
SearchChatsInput
collectionIdOrSlugStringFilter by collection ID or slug to search within matching chats
Filter by rules (for preview before saving a collection). Combined with collection rules if collectionIdOrSlug is also provided.
GetCursorPaginatedInput
cursorStringlimitIntbeforeBooleanGetSortedInput
sortByString!RequiredsortOrderString!RequiredReturns
data[Conversation!]!previousCursorStringnextCursorStringhasPreviousBoolean!hasNextBoolean!totalCountIntTotal count of conversations matching the filters (only on first page)
query {
searchConversations(input: { … }, pagination: { … }, sort: { … }) { data previousCursor nextCursor hasPrevious hasNext }
}sendConversationNote
Mutation
ScopeNOTES_WRITE
Arguments
CreateCombinedMessageInput
createdAtDateTimedeliveryStatusMessageDeliveryStatusDelivery status - defaults based on message direction
replyToMessageStringmentions[ID!]internalBooleanPost as an internal note without a mention (team-only, never sent to the customer).
textStringbuttons[MessageButtonInput!]replyToButtonIdStringkeyboardTypeStringflowTitleStringmedia[String!]captionStringshowCaptionAboveMediaBooleanhasMediaSpoilerBooleanmediaGroupIdStringisMediaGroupBooleanmediaGroup[String!]Returns
_idString!messageIdFloatexternalMessageIdStringtypeMessageType!fromMessageSenderUnionchatChat!directionMessageDirection!sentFromChannelBooleantextStringmediaGroup[MediaGroupMessage!]media[Media!]captionStringshowCaptionAboveMediaBooleanhasMediaSpoilerBooleancontactContactlocationMessageLocationunsupportedMessageUnsupportedproducts[MessageProduct!]pollMessagePolldiceMessageDicegameMessageGamebuttons[MessageButton!]sources[MessageSource!]replyToMessageMessagemutation {
sendConversationNote(conversationId: "…", input: { … }, chatId: "…", actingUserId: "…") { _id messageId externalMessageId type from }
}threadsPage
Query
ScopeMESSAGES_READ
Arguments
SocialPaginationInput
cursorStringlimitInt!RequiredReturns
threads[Chat!]!nextCursorStringOpaque cursor for the next page; absent when this is the last page.
hasNextBoolean!query {
threadsPage(conversationId: "…", pagination: { … }, filter: ALL, peopleId: "…") { threads nextCursor hasNext }
}