Inbox Management
Read state, assignment, status, labels, collections, flows and deletes
State changes need CONVERSATIONS_MANAGE; the deletes need the separate CONVERSATIONS_DELETE. See Managing the inbox.
apiCreateChatCollection
ScopeCONVERSATIONS_MANAGE
Create a rule-based collection (API key, conversations:manage). Same plan limits as members.
Arguments
CreateChatCollectionInput
nameString!RequiredslugStringdescriptionStringiconStringcolorStringpositionFloatReturns
_idString!nameString!slugString!descriptionStringiconStringcolorStringpositionFloat!isSystemBoolean!systemKeyStringisVisibleBoolean!isLockedBoolean!planLockedBoolean!rules[CollectionRule!]!createdByStringchatCountFloatcreatedAtDateTime!updatedAtDateTime!mutation {
apiCreateChatCollection(input: { … }) { _id name slug description icon }
}apiDeleteChat
ScopeCONVERSATIONS_DELETE
Irreversibly delete one chat thread with its messages and media (API key, conversations:delete).
Arguments
chatIdString!RequiredReturns
mutation {
apiDeleteChat(chatId: "…") { messages media }
}apiDeleteChatCollection
ScopeCONVERSATIONS_MANAGE
Delete a non-system collection of your organisation (API key, conversations:manage).
Arguments
idOrSlugString!RequiredReturns
Boolean!mutation {
apiDeleteChatCollection(idOrSlug: "…")
}apiDeleteConversation
ScopeCONVERSATIONS_DELETE
Irreversibly delete a conversation and all its threads (API key, conversations:delete). removePeople:true (needs contacts:erase too) GDPR-ERASES its contacts: their personal data is anonymised everywhere in your organisation (other conversations stay, anonymised) with an erasure log. It is not a wipe of the person.
Arguments
conversationIdString!RequiredremovePeopleBoolean!RequiredReturns
chatsInt!messagesInt!mediaInt!contactsErasedInt!mutation {
apiDeleteConversation(conversationId: "…", removePeople: false) { chats messages media contactsErased }
}apiMoveChatCollection
ScopeCONVERSATIONS_MANAGE
Reorder a collection (API key, conversations:manage). Org is the key org.
Arguments
MoveCollectionInput
collectionIdOrSlugString!RequirednewPositionFloat!RequiredReturns
_idString!nameString!slugString!descriptionStringiconStringcolorStringpositionFloat!isSystemBoolean!systemKeyStringisVisibleBoolean!isLockedBoolean!planLockedBoolean!rules[CollectionRule!]!createdByStringchatCountFloatcreatedAtDateTime!updatedAtDateTime!mutation {
apiMoveChatCollection(input: { … }) { _id name slug description icon }
}apiStartFlowForChat
ScopeCONVERSATIONS_MANAGE
Run a PUBLISHED flow of your organisation in a chat (API key, conversations:manage). Flows are not listable via the API: take the flowId from the dashboard.
Arguments
chatIdString!RequiredflowIdString!RequiredReturns
_idString!chatIdFloatexternalChatIdStringbusinessConnectionIdStringexternalUserIdStringtypeChatType!titleStringusernameStringfirstNameStringlastNameStringisForumBooleanlastMessageMessagelastMessageAtDateTimeprofilePeoplechannelIdentityChannelIdentityintegrationIdStringcreatedAtDateTimeupdatedAtDateTimeunReadCountFloatengagedBooleanfalse = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.isBlockedBooleanverified[String!]isAIActiveBooleanstatusChatStatusmutation {
apiStartFlowForChat(chatId: "…", flowId: "…") { _id chatId externalChatId businessConnectionId externalUserId }
}apiStopFlowForChat
ScopeCONVERSATIONS_MANAGE
Cancel the flow running in a chat (API key, conversations:manage).
Arguments
chatIdString!RequiredReturns
_idString!chatIdFloatexternalChatIdStringbusinessConnectionIdStringexternalUserIdStringtypeChatType!titleStringusernameStringfirstNameStringlastNameStringisForumBooleanlastMessageMessagelastMessageAtDateTimeprofilePeoplechannelIdentityChannelIdentityintegrationIdStringcreatedAtDateTimeupdatedAtDateTimeunReadCountFloatengagedBooleanfalse = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.isBlockedBooleanverified[String!]isAIActiveBooleanstatusChatStatusmutation {
apiStopFlowForChat(chatId: "…") { _id chatId externalChatId businessConnectionId externalUserId }
}apiUpdateChatCollection
ScopeCONVERSATIONS_MANAGE
Update a collection of your organisation (API key, conversations:manage).
Arguments
idOrSlugString!RequiredUpdateChatCollectionInput
nameStringslugStringdescriptionStringiconStringcolorStringisVisibleBooleanReturns
_idString!nameString!slugString!descriptionStringiconStringcolorStringpositionFloat!isSystemBoolean!systemKeyStringisVisibleBoolean!isLockedBoolean!planLockedBoolean!rules[CollectionRule!]!createdByStringchatCountFloatcreatedAtDateTime!updatedAtDateTime!mutation {
apiUpdateChatCollection(idOrSlug: "…", input: { … }) { _id name slug description icon }
}archiveLabel
ScopeCONVERSATIONS_MANAGE
Arguments
idString!RequiredReturns
_idString!nameString!organisationIdString!colorString!activeBoolean!archivedBoolean!isSystemBoolean!descriptionStringcreatedAtDateTime!updatedAtDateTime!mutation {
archiveLabel(id: "…") { _id name organisationId color active }
}assignChatToOperator
ScopeCONVERSATIONS_MANAGE
Arguments
chatIdString!RequiredoperatorIdString!RequiredReturns
_idString!chatIdFloatexternalChatIdStringbusinessConnectionIdStringexternalUserIdStringtypeChatType!titleStringusernameStringfirstNameStringlastNameStringisForumBooleanlastMessageMessagelastMessageAtDateTimeprofilePeoplechannelIdentityChannelIdentityintegrationIdStringcreatedAtDateTimeupdatedAtDateTimeunReadCountFloatengagedBooleanfalse = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.isBlockedBooleanverified[String!]isAIActiveBooleanstatusChatStatusmutation {
assignChatToOperator(chatId: "…", operatorId: "…") { _id chatId externalChatId businessConnectionId externalUserId }
}assignConversationThreads
ScopeCONVERSATIONS_MANAGE
Arguments
conversationIdString!RequiredoperatorIdStringReturns
Int!mutation {
assignConversationThreads(conversationId: "…", operatorId: "…")
}blockConversation
ScopeCONVERSATIONS_MANAGE
Arguments
conversationIdString!RequiredblockedBoolean!RequiredReturns
Int!mutation {
blockConversation(conversationId: "…", blocked: false)
}closeChat
ScopeCONVERSATIONS_MANAGE
Close a chat: sets status to CLOSED, auto-unassigns operator, creates CHAT_CLOSED system message
Arguments
chatIdString!RequiredReturns
_idString!chatIdFloatexternalChatIdStringbusinessConnectionIdStringexternalUserIdStringtypeChatType!titleStringusernameStringfirstNameStringlastNameStringisForumBooleanlastMessageMessagelastMessageAtDateTimeprofilePeoplechannelIdentityChannelIdentityintegrationIdStringcreatedAtDateTimeupdatedAtDateTimeunReadCountFloatengagedBooleanfalse = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.isBlockedBooleanverified[String!]isAIActiveBooleanstatusChatStatusmutation {
closeChat(chatId: "…") { _id chatId externalChatId businessConnectionId externalUserId }
}createLabel
ScopeCONVERSATIONS_MANAGE
Arguments
CreateLabelInput
nameString!RequireddescriptionStringcolorStringactiveBooleanReturns
_idString!nameString!organisationIdString!colorString!activeBoolean!archivedBoolean!isSystemBoolean!descriptionStringcreatedAtDateTime!updatedAtDateTime!mutation {
createLabel(input: { … }) { _id name organisationId color active }
}readAllConversation
ScopeCONVERSATIONS_MANAGE
Arguments
conversationIdString!RequiredReturns
Int!mutation {
readAllConversation(conversationId: "…")
}readAllMessages
ScopeCONVERSATIONS_MANAGE
Mark all messages in a chat as read
Arguments
chatIdString!RequiredReturns
Float!mutation {
readAllMessages(chatId: "…")
}readMessages
ScopeCONVERSATIONS_MANAGE
Bulk mark inbound messages read; returns the count actually transitioned
Arguments
ids[String!]!RequiredReturns
Int!mutation {
readMessages(ids: "…")
}reopenChat
ScopeCONVERSATIONS_MANAGE
Reopen a closed/resolved chat: sets status to IN_PROGRESS and creates a CHAT_REOPENED system message
Arguments
chatIdString!RequiredReturns
_idString!chatIdFloatexternalChatIdStringbusinessConnectionIdStringexternalUserIdStringtypeChatType!titleStringusernameStringfirstNameStringlastNameStringisForumBooleanlastMessageMessagelastMessageAtDateTimeprofilePeoplechannelIdentityChannelIdentityintegrationIdStringcreatedAtDateTimeupdatedAtDateTimeunReadCountFloatengagedBooleanfalse = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.isBlockedBooleanverified[String!]isAIActiveBooleanstatusChatStatusmutation {
reopenChat(chatId: "…") { _id chatId externalChatId businessConnectionId externalUserId }
}restoreLabel
ScopeCONVERSATIONS_MANAGE
Arguments
idString!RequiredReturns
_idString!nameString!organisationIdString!colorString!activeBoolean!archivedBoolean!isSystemBoolean!descriptionStringcreatedAtDateTime!updatedAtDateTime!mutation {
restoreLabel(id: "…") { _id name organisationId color active }
}setConversationAi
ScopeCONVERSATIONS_MANAGE
Arguments
conversationIdString!RequiredenabledBoolean!RequiredReturns
Int!mutation {
setConversationAi(conversationId: "…", enabled: false)
}setMessageLabels
ScopeCONVERSATIONS_MANAGE
Arguments
SetMessageLabelsInput
messageIdString!RequiredlabelIds[String!]!RequiredReturns
_idString!messageIdFloatexternalMessageIdStringtypeMessageType!fromMessageSenderUnionchatChat!directionMessageDirection!sentFromChannelBooleantextStringmediaGroup[MediaGroupMessage!]media[Media!]captionStringshowCaptionAboveMediaBooleanhasMediaSpoilerBooleancontactContactlocationMessageLocationunsupportedMessageUnsupportedproducts[MessageProduct!]pollMessagePolldiceMessageDicegameMessageGamebuttons[MessageButton!]sources[MessageSource!]replyToMessageMessagemutation {
setMessageLabels(input: { … }) { _id messageId externalMessageId type from }
}unassignChat
ScopeCONVERSATIONS_MANAGE
Arguments
chatIdString!RequiredReturns
_idString!chatIdFloatexternalChatIdStringbusinessConnectionIdStringexternalUserIdStringtypeChatType!titleStringusernameStringfirstNameStringlastNameStringisForumBooleanlastMessageMessagelastMessageAtDateTimeprofilePeoplechannelIdentityChannelIdentityintegrationIdStringcreatedAtDateTimeupdatedAtDateTimeunReadCountFloatengagedBooleanfalse = captured/hidden from the operator inbox; absent/unset = visible (legacy rows + all non-web channels). Set explicitly, never defaulted.isBlockedBooleanverified[String!]isAIActiveBooleanstatusChatStatusmutation {
unassignChat(chatId: "…") { _id chatId externalChatId businessConnectionId externalUserId }
}updateChatField
ScopeCONVERSATIONS_MANAGE
Generic mutation to update any chat field by key
Arguments
UpdateChatFieldInput
chatIdString!RequiredvalueJSONblockScopeBlockScopeReturns
Boolean!mutation {
updateChatField(input: { … })
}updateLabel
ScopeCONVERSATIONS_MANAGE
Arguments
idString!RequiredUpdateLabelInput
nameStringdescriptionStringcolorStringactiveBooleanReturns
_idString!nameString!organisationIdString!colorString!activeBoolean!archivedBoolean!isSystemBoolean!descriptionStringcreatedAtDateTime!updatedAtDateTime!mutation {
updateLabel(id: "…", input: { … }) { _id name organisationId color active }
}