GraphQL API reference
This section describes every query and mutation available through the GraphQL API and to a connected AI assistant, with their arguments and the data they return.
Operations an external caller may not run are not part of this API and are not listed: billing changes, AI provider credentials, workspace and account changes, the access key itself, and deleting conversations or visitor data.
General rules:
- The endpoint answers introspection queries, so GraphQL tools can load the schema themselves.
- Page-size arguments (perPage, first) accept at most 100. A larger value is refused with the code
REQUEST_TOO_LARGE. - A credential with read access only can run queries, but no mutation.
- Time values are ISO 8601 timestamps. UUID values are identifiers such as
3d1c4826-e219-4230-9833-41bef2be80ea. - A mutation that fails for a business reason still answers with HTTP 200 and returns the reason in its error field (see Error).
Dashboard queries
The numbers shown on the eChat Dashboard.
Queries that take a period argument accept one of the DashboardPeriod values: WEEK (the last 7 days), TWO_WEEKS (the last 14 days, the default) or MONTH (the last 30 days). Each period includes today.
dashboardStats
Returns today's activity on the store.
Output (DashboardStats):
| Field | Description | Data Type |
|---|---|---|
| activeSessions | Visitor sessions that are active right now. | Int! |
| todayChats | Conversations started today that have at least one message. | Int! |
| yesterdayChats | Conversations started yesterday. | Int! |
| todayVisitors | New visitors seen today. | Int! |
| todayMessages | Messages sent today, by visitors and by the chatbot. | Int! |
| lastWidgetSeenAt | When the chat widget last reported a page view from the store. Empty if it never has. | Time |
dashboardPeriodStats
Returns the totals for a period.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| period | The period to count. Defaults to TWO_WEEKS. | DashboardPeriod! |
Output (PeriodStats):
| Field | Description | Data Type |
|---|---|---|
| visitors | New visitors in the period. | Int! |
| messages | Messages sent in the period. | Int! |
dashboardVisitorsByCountry
Returns the 10 countries with the most visitors in the period.
Arguments: period (DashboardPeriod!), as in dashboardPeriodStats.
Output ([CountryStat!]!):
| Field | Description | Data Type |
|---|---|---|
| name | Country name. | String! |
| code | Two-letter country code. | String! |
| visitors | Visitors from this country in the period. | Int! |
dashboardChatsByCountry
Returns the 10 countries with the most conversations in the period.
Arguments: period (DashboardPeriod!), as in dashboardPeriodStats.
Output ([CountryChatStat!]!):
| Field | Description | Data Type |
|---|---|---|
| name | Country name. | String! |
| code | Two-letter country code. | String! |
| chats | Conversations from this country in the period. | Int! |
dashboardDailyVolume
Returns the number of conversations per day in the period.
Arguments: period (DashboardPeriod!), as in dashboardPeriodStats.
Output ([DailyVolumeStat!]!):
| Field | Description | Data Type |
|---|---|---|
| date | The day, as YYYY-MM-DD. | String! |
| chats | Conversations started on that day. | Int! |
dashboardTopPages
Returns the 10 store pages where the most visitors had the chat widget loaded in the period.
Arguments: period (DashboardPeriod!), as in dashboardPeriodStats.
Output ([PageStat!]!):
| Field | Description | Data Type |
|---|---|---|
| pageTitle | Title of the store page. | String! |
| url | Address of the store page. | String! |
| visitors | Distinct visitors on this page. | Int! |
dashboardTokensUsage
Returns how many AI tokens the chatbot used in the period, in total and per day.
Arguments: period (DashboardPeriod!), as in dashboardPeriodStats.
Output (TokensUsageStats):
| Field | Description | Data Type |
|---|---|---|
| totalTokens | Tokens used in the whole period. | Int! |
| dailyTokens | Tokens per day, with a split per AI provider. See DailyTokensStat. | [DailyTokensStat!]! |
Conversation queries
The chat history shown on the History page.
conversations
Returns a page of conversations. Only conversations with at least one message are returned.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| page | Page number, starting from 1. | Int |
| perPage | Conversations per page. Defaults to 20, at most 100. | Int |
| filters | Narrows the list. See ConversationFiltersInput. | ConversationFiltersInput |
| sorting | Sort order. See ConversationSortingInput. | ConversationSortingInput |
Output (ChatConversationConnection):
| Field | Description | Data Type |
|---|---|---|
| edges | The conversations on this page. Each edge holds a cursor and a node (ChatConversation). | [ChatConversationEdge!]! |
| totalCount | Conversations matching the filters, on all pages. | Int! |
| currentPage | The page returned. | Int! |
| totalPages | Number of pages. | Int! |
conversation
Returns one conversation with its visitor, session and messages. Returns null if no conversation has this ID.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The conversation ID. | UUID! |
Output: ChatConversation.
conversationMessages
Returns the messages of one conversation, oldest first.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| conversationId | The conversation ID. | UUID! |
Output: a list of ChatMessage.
conversationCountries
Returns the countries the store's conversations came from. Use the codes in the countryCodes filter of conversations.
Output ([ConversationCountry!]!):
| Field | Description | Data Type |
|---|---|---|
| code | Two-letter country code. | String! |
| name | Country name. | String! |
conversationCorrections
Returns the chatbot answers in a conversation that someone has already corrected with an FAQ entry or a guidance rule.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| conversationId | The conversation ID. | UUID! |
Output ([MessageCorrection!]!):
| Field | Description | Data Type |
|---|---|---|
| messageId | The corrected chatbot message. | UUID! |
| kind | What the correction is: FAQ (an FAQ entry) or RULE (a guidance rule). | CorrectionKind! |
| recordId | ID of the FAQ entry or the guidance rule. | UUID! |
| title | The FAQ question, or the name of the guidance rule. | String! |
visitorDataByEmail
Shows how much data eChat holds for a visitor with this email address. Nothing is deleted. Use it to answer a customer's data access request.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| The visitor's email address. | String! |
Output (VisitorDataMatch):
| Field | Description | Data Type |
|---|---|---|
| conversations | Conversations of visitors with this email. | Int! |
| messages | Messages in those conversations. | Int! |
messageStats
Kept for compatibility. Always returns zero in good, bad and total.
Knowledge base queries
The documents and categories shown on the Knowledge Base page.
documents
Returns a page of knowledge base documents.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| page | Page number, starting from 1. | Int |
| perPage | Documents per page. Defaults to 50, at most 100. | Int |
| filters | Narrows the list. See DocumentFiltersInput. | DocumentFiltersInput |
| sorting | Sort order. See DocumentSortingInput. | DocumentSortingInput |
Output (DocumentConnection):
| Field | Description | Data Type |
|---|---|---|
| edges | The documents on this page. Each edge holds a cursor and a node (Document). | [DocumentEdge!]! |
| totalCount | Documents matching the filters, on all pages. | Int! |
| currentPage | The page returned. | Int! |
| totalPages | Number of pages. | Int! |
document
Returns one document with its full text. Returns null if no document has this ID.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The document ID. | UUID! |
Output: Document.
categories
Returns all knowledge base categories.
Output: a list of Category.
knowledgeBaseEmpty
Returns true when the knowledge base has no documents yet.
FAQ queries
The entries on the FAQ page.
faqs
Returns a page of FAQ entries.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| page | Page number, starting from 1. | Int |
| perPage | Entries per page. Defaults to 50, at most 100. | Int |
| filters | Narrows the list. See FaqFiltersInput. | FaqFiltersInput |
Output (FaqConnection):
| Field | Description | Data Type |
|---|---|---|
| edges | The entries on this page. Each edge holds a cursor and a node (Faq). | [FaqEdge!]! |
| totalCount | Entries matching the filters, on all pages. | Int! |
| currentPage | The page returned. | Int! |
| totalPages | Number of pages. | Int! |
faq
Returns one FAQ entry. Returns null if no entry has this ID.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The FAQ entry ID. | UUID! |
Output: Faq.
Guidance queries
The rules on the Guidance page.
guidances
Returns guidance rules. This list is paged with a cursor: pass the endCursor of one page as after to get the next.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| first | Rules to return. Defaults to 50, at most 100. | Int |
| after | Return the rules after this cursor. | String |
| filters | Narrows the list. See GuidanceFiltersInput. | GuidanceFiltersInput |
| sorting | Sort order. See GuidanceSortingInput. | GuidanceSortingInput |
Output (GuidanceConnection):
| Field | Description | Data Type |
|---|---|---|
| edges | The rules returned. Each edge holds a cursor and a node (Guidance). | [GuidanceEdge!]! |
| pageInfo | Whether more rules follow, and the cursors. See PageInfo. | PageInfo! |
| totalCount | Rules matching the filters. | Int! |
guidance
Returns one guidance rule. Returns null if no rule has this ID.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The rule ID. | UUID! |
Output: Guidance.
Settings and account queries
settings
Returns the chatbot and widget settings from the Settings page. The AI provider key is never returned: openaiKey is always empty.
Output: Settings.
aiConfigured
Returns true when the workspace has a working AI provider configured, so the chatbot can answer.
providers
Returns the AI providers eChat supports and their models. The workspace's own provider keys are not part of this API.
Output ([ProviderInfo!]!):
| Field | Description | Data Type |
|---|---|---|
| id | Provider code. | String! |
| label | Provider name. | String! |
| models | Models of this provider. Each has a spec (model code) and a label (name). | [ProviderModelOption!]! |
account
Returns the eChat account and the workspaces in it. Each connected store is one workspace.
Output (AccountInfo):
| Field | Description | Data Type |
|---|---|---|
| account | The account: id, name and handle. | Account! |
| workspaces | Workspaces in the account. See AccountWorkspace. | [AccountWorkspace!]! |
| mergeSuggestions | Other accounts that hold workspaces of the same store, offered for merging. | [AccountSummary!]! |
| strays | Always empty. | [AccountWorkspace!]! |
billingInfo
Returns the plan and billing details of the workspace as a JSON object under the key billing.
Output (BillingInfo):
| Field | Description | Data Type |
|---|---|---|
| data | Billing details, as JSON. | JSON |
Knowledge base mutations
saveDocument
Creates a knowledge base document, or updates one when id is given.
Input (DocumentInput):
| Field | Description | Data Type |
|---|---|---|
| id | ID of the document to update. Leave it out to create a new one. | UUID |
| categoryId | Category the document belongs to. | UUID |
| identifier | A unique key of the document, such as shipping-policy. | String! |
| name | Document title. | String! |
| body | Document text. Markdown is supported. | String |
| visibility | Who the document is available to. Use ALL. | String! |
Output (DocumentSavePayload):
| Field | Description | Data Type |
|---|---|---|
| document | The saved document. See Document. | Document |
| error | Why the document was not saved. Empty on success. | Error |
deleteDocument
Deletes a knowledge base document.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The document ID. | UUID! |
Output: BooleanPayload.
saveCategory
Creates a knowledge base category, or updates one when id is given.
Input (CategoryInput):
| Field | Description | Data Type |
|---|---|---|
| id | ID of the category to update. Leave it out to create a new one. | UUID |
| parentID | Parent category, for a subcategory. | UUID |
| identifier | A unique key of the category. | String |
| name | Category name. | String |
| description | Category description. | String |
| visibility | Who the category is available to. Use ALL. | String |
Output (CategorySavePayload):
| Field | Description | Data Type |
|---|---|---|
| category | The saved category. See Category. | Category |
| error | Why the category was not saved. Empty on success. | Error |
deleteCategory
Deletes a knowledge base category.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The category ID. | UUID! |
Output: BooleanPayload.
FAQ mutations
saveFaq
Creates an FAQ entry, or updates one when id is given.
Input (FaqInput):
| Field | Description | Data Type |
|---|---|---|
| id | ID of the entry to update. Leave it out to create a new one. | UUID |
| question | What a customer asks. | String! |
| answer | What the chatbot should answer. | String! |
| status | enabled or disabled. The chatbot uses enabled entries only. | String! |
| sourceConversationID | The conversation the entry corrects, if any. | UUID |
| sourceMessageID | The chatbot message the entry corrects, if any. | UUID |
Output (FaqSavePayload):
| Field | Description | Data Type |
|---|---|---|
| faq | The saved entry. See Faq. | Faq |
| error | Why the entry was not saved. Empty on success. | Error |
deleteFaq
Deletes an FAQ entry.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The FAQ entry ID. | UUID! |
Output: BooleanPayload.
Guidance mutations
saveGuidance
Creates a guidance rule, or updates one when id is given.
Input (GuidanceInput):
| Field | Description | Data Type |
|---|---|---|
| id | ID of the rule to update. Leave it out to create a new one. | UUID |
| name | Rule name. | String! |
| slug | Short code the chatbot uses to address the rule. Leave it out and one is made from the name. | String |
| trigger | When the rule applies, such as "Customer wants to return an item". | String! |
| instructions | What the chatbot should do when the rule applies. | String! |
| status | enabled or disabled. | String! |
| sourceConversationID | The conversation the rule corrects, if any. | UUID |
| sourceMessageID | The chatbot message the rule corrects, if any. | UUID |
Output (GuidanceSavePayload):
| Field | Description | Data Type |
|---|---|---|
| guidance | The saved rule. See Guidance. | Guidance |
| error | Why the rule was not saved. Empty on success. | Error |
deleteGuidance
Deletes a guidance rule.
Arguments:
| Field | Description | Data Type |
|---|---|---|
| id | The rule ID. | UUID! |
Output: BooleanPayload.
Settings and support mutations
saveSettings
Changes the chatbot and widget settings. Only the fields you send are changed.
Two fields of the input are refused over this API, and a request that sets either of them is rejected as a whole: openaiKey (the AI provider key) and conversationRetentionDays (shortening it deletes conversations). Change them in the eChat backend.
Input (SettingsInput):
| Field | Description | Data Type |
|---|---|---|
| assistant | Chatbot behavior. See AssistantSettingInput. | AssistantSettingInput |
| chat | Widget look and behavior. See ChatSettingInput. | ChatSettingInput |
| errorNotificationEmails | Addresses that get an email when the chatbot stops answering because of an AI provider problem. | [String!] |
| errorNotificationsEnabled | Turns those emails on or off. | Boolean |
| hideWidgetWhenKbEmpty | Hides the chat widget while the knowledge base has no documents. | Boolean |
Output: BooleanPayload.
submitSupportTicket
Sends a message to Mirasvit support on behalf of the workspace.
Input (SupportTicketInput):
| Field | Description | Data Type |
|---|---|---|
| replyTo | Email address for the answer. | String! |
| subject | Subject of the message. | String! |
| message | Text of the message. | String! |
Output: BooleanPayload.
Not available over this API
The schema also lists uploadDocument and uploadImage. They need a file upload, which this API does not accept. To add a document, send its text with saveDocument.
Types
ChatConversation
| Field | Description | Data Type |
|---|---|---|
| id | Conversation ID. | UUID! |
| instanceId | Workspace ID. | UUID! |
| status | Conversation status. See ConversationStatus. | ConversationStatus! |
| createdAt | When the conversation started. | Time! |
| updatedAt | When the conversation last changed: a new message or a status change. | Time! |
| endedAt | When the conversation ended. Empty while it is open. | Time |
| messageCount | Number of messages. | Int! |
| totalTokens | AI tokens the chatbot used in this conversation. | Int! |
| providerTokens | Tokens per AI provider: provider and tokens. | [ProviderTokens!] |
| session | Where the visitor was. See ChatConversationSession. | ChatConversationSession |
| visitor | Who the visitor is. See ChatConversationVisitor. | ChatConversationVisitor |
| messages | The messages, oldest first. See ChatMessage. | [ChatMessage!]! |
ChatConversationSession
| Field | Description | Data Type |
|---|---|---|
| countryCode | Two-letter code of the visitor's country. | String! |
| countryName | The visitor's country. | String! |
| city | The visitor's city. | String! |
| pageCount | Store pages the visitor opened. | Int! |
ChatConversationVisitor
| Field | Description | Data Type |
|---|---|---|
| id | Visitor ID. | UUID! |
| name | Visitor name, if the visitor gave one. | String! |
| Visitor email, if the visitor gave one. | String! | |
| phone | Visitor phone, if the visitor gave one. | String! |
ChatMessage
| Field | Description | Data Type |
|---|---|---|
| id | Message ID. | UUID! |
| conversationId | Conversation the message belongs to. | UUID! |
| body | Message text, as the visitor saw it. | String! |
| originalBody | Message text as it was first written. | String |
| senderType | Who sent it. See MessageSenderType. | MessageSenderType! |
| senderName | Name shown for the sender, such as the chatbot's name. | String! |
| isReceived | The message was delivered. | Boolean! |
| isRead | The message was read. | Boolean! |
| createdAt | When the message was sent. | Time! |
| productCards | Products the chatbot showed in the message. See ProductCard. | [ProductCard!]! |
| attachments | Files attached to the message. See ChatAttachment. | [ChatAttachment!]! |
ProductCard
| Field | Description | Data Type |
|---|---|---|
| sku | Product SKU. | String! |
| name | Product name. | String! |
| url | Product page address. | String! |
| image | Product image address. | String! |
| price | Price shown on the card. | String! |
| regularPrice | Price before a discount, when the product is on sale. | String! |
| priceFrom | Lowest price, for a product with a price range. | String! |
| priceTo | Highest price, for a product with a price range. | String! |
| currency | Currency code. | String! |
| blurb | Short text the chatbot wrote about the product. | String! |
ChatAttachment
| Field | Description | Data Type |
|---|---|---|
| id | Attachment ID. | UUID! |
| name | File name. | String! |
| type | File type, such as image/png. | String! |
| size | File size in bytes. | Int! |
| downloadURL | Address to download the file. | String! |
ConversationFiltersInput
All fields are optional. Filters you send are combined.
| Field | Description | Data Type |
|---|---|---|
| statuses | Conversation statuses to include. Without it, TRIGGERED conversations are left out. | [ConversationStatus!] |
| createdAtFrom, createdAtTo | Conversations started in this time range. | Time |
| updatedAtFrom, updatedAtTo | Conversations changed in this time range. Use updatedAtFrom for an incremental sync. | Time |
| countryCodes | Two-letter codes of visitor countries. See conversationCountries. | [String!] |
| pageCountMin, pageCountMax | Range of store pages the visitor opened. | Int |
| messageCountMin, messageCountMax | Range of messages in the conversation. | Int |
| totalTokensMin, totalTokensMax | Range of AI tokens used. | Int |
| visitorEmail | Conversations of the visitor with this email, matched case-insensitively. | String |
ConversationSortingInput
| Field | Description | Data Type |
|---|---|---|
| field | Sort by: CREATED_AT, UPDATED_AT, ENDED_AT, PAGE_COUNT, MESSAGE_COUNT, TOTAL_TOKENS or DURATION. | ConversationSortField! |
| direction | ASC or DESC. | SortDirection! |
ConversationStatus
| Value | Description |
|---|---|
| OPEN | The conversation is going on. |
| CLOSED | The conversation has ended. eChat closes a conversation after 30 minutes without a new message. |
| TRIGGERED | Not used by current eChat versions. Left out of conversations unless you ask for it in statuses. |
| OFFLINE | Not used by current eChat versions. |
MessageSenderType
| Value | Description |
|---|---|
| VISITOR | The store visitor. |
| AI | The chatbot. |
| AGENT | A person answering in the chat. |
| SYSTEM | An automatic notice. |
Document
| Field | Description | Data Type |
|---|---|---|
| id | Document ID. | UUID! |
| categoryId | Category the document belongs to. | UUID |
| identifier | Unique key. Synced documents use a prefix for their source, such as product.24-MB01 or cms_page.about-us. | String! |
| name | Document title. | String! |
| body | Document text. | String! |
| visibility | Who the document is available to. | String! |
DocumentFiltersInput
| Field | Description | Data Type |
|---|---|---|
| searchQuery | Text to find in the document name or identifier. A SKU finds its product. | String |
| categoryId | Only documents of this category. | UUID |
DocumentSortingInput
| Field | Description | Data Type |
|---|---|---|
| field | Sort by NAME. | DocumentSortField! |
| direction | ASC or DESC. | SortDirection! |
Category
| Field | Description | Data Type |
|---|---|---|
| id | Category ID. | UUID! |
| parentID | Parent category. Empty for a top-level category. | UUID |
| identifier | Unique key of the category. | String! |
| name | Category name. | String! |
| description | Category description. | String! |
| level | Depth in the category tree. | Int! |
| visibility | Who the category is available to. | String! |
| sortOrder | Position among its sibling categories. | Int! |
| syncProvider | The sync that created the category, such as products or CMS pages. Empty for a category created by hand. | String! |
| createdAt | When the category was created. | Time! |
| updatedAt | When the category last changed. | Time! |
| documents | Documents in the category. See documents for the fields. | DocumentConnection! |
Faq
| Field | Description | Data Type |
|---|---|---|
| id | FAQ entry ID. | UUID! |
| question | What a customer asks. | String! |
| answer | What the chatbot answers. | String! |
| status | enabled or disabled. | String! |
| sourceConversationID | The conversation the entry corrects. Empty for an entry written on the FAQ page. | UUID |
| sourceMessageID | The chatbot message the entry corrects. | UUID |
| createdAt | When the entry was created. | Time! |
| updatedAt | When the entry last changed. | Time! |
FaqFiltersInput
| Field | Description | Data Type |
|---|---|---|
| searchQuery | Text to find in the question or the answer. | String |
| status | enabled or disabled. | String |
Guidance
| Field | Description | Data Type |
|---|---|---|
| id | Rule ID. | UUID! |
| name | Rule name. | String! |
| slug | Short code the chatbot uses to address the rule. | String! |
| trigger | When the rule applies. | String! |
| instructions | What the chatbot does when the rule applies. | String! |
| status | enabled or disabled. | String! |
| sourceConversationID | The conversation the rule corrects. Empty for a rule written on the Guidance page. | UUID |
| sourceMessageID | The chatbot message the rule corrects. | UUID |
| createdAt | When the rule was created. | Time! |
| updatedAt | When the rule last changed. | Time! |
GuidanceFiltersInput
| Field | Description | Data Type |
|---|---|---|
| searchQuery | Text to find in the rule. | String |
| status | enabled or disabled. | String |
GuidanceSortingInput
| Field | Description | Data Type |
|---|---|---|
| field | Sort by NAME. | GuidanceSortField! |
| direction | ASC or DESC. | SortDirection! |
PageInfo
| Field | Description | Data Type |
|---|---|---|
| hasNextPage | More items follow this page. | Boolean! |
| hasPreviousPage | Items come before this page. | Boolean! |
| startCursor | Cursor of the first item on this page. | String |
| endCursor | Cursor of the last item. Pass it as after. | String |
Settings
| Field | Description | Data Type |
|---|---|---|
| openaiKey | Always empty over this API. | String! |
| providerStatus | Whether the AI provider works. See ProviderStatusType. | ProviderStatusType! |
| reconcileStatus | Whether a sync was stopped to protect documents. See ReconcileStatusType. | ReconcileStatusType! |
| assistant | Chatbot behavior. See AssistantSetting. | AssistantSetting! |
| chat | Widget look and behavior. See ChatSettingType. | ChatSettingType! |
| primaryEmail | Contact email of the workspace owner. | String! |
| fullName | Full name of the workspace owner. | String! |
| firstName | First name of the workspace owner. | String! |
| lastName | Last name of the workspace owner. | String! |
| phone | Phone of the workspace owner. | String! |
| notificationEmails | Addresses that get eChat notifications. | [String!] |
| errorNotificationEmails | Addresses that get an email when the chatbot stops answering because of an AI provider problem. | [String!] |
| errorNotificationsEnabled | Those emails are turned on. | Boolean! |
| hideWidgetWhenKbEmpty | The chat widget is hidden while the knowledge base has no documents. | Boolean! |
| conversationRetentionDays | Days a conversation is kept after its last activity. 0 keeps it until deleted. | Int! |
AssistantSetting
The same fields, all optional, make up AssistantSettingInput.
| Field | Description | Data Type |
|---|---|---|
| basePrompt | The chatbot's main instructions. | String! |
| instructions | Additional instructions for the chatbot. | String! |
| toneOfVoice | How the chatbot speaks to customers. | String! |
| language | Language code the chatbot answers in, such as de. | String! |
AssistantSettingInput
The fields of AssistantSetting, all optional.
ChatSettingType
The same fields, all optional, make up ChatSettingInput.
| Field | Description | Data Type |
|---|---|---|
| isActive | The chat widget is shown on the store. | Boolean! |
| chatWindow | The chat window. See ChatWindowSetting. | ChatWindowSetting! |
| chatButton | The button that opens the chat. See ChatButtonSetting. | ChatButtonSetting! |
| conversation | Conversation options. See ConversationSetting. | ConversationSetting! |
ChatSettingInput
The fields of ChatSettingType, all optional.
ChatWindowSetting
| Field | Description | Data Type |
|---|---|---|
| position | Where the window opens on the page. | String! |
| primaryColor | Main color of the window. | String! |
| title | Window title. | String! |
| subtitle | Line under the title. | String! |
| invitationMessage | Message that invites the visitor to chat. | String! |
| linkTarget | Where links in chat messages open. | String! |
ChatButtonSetting
| Field | Description | Data Type |
|---|---|---|
| position | Where the button is on the page. | String! |
| primaryColor | Button color. | String! |
| title | Button label. | String! |
ConversationSetting
| Field | Description | Data Type |
|---|---|---|
| allowFileAttachments | Visitors can attach files. | Boolean! |
| soundNotifications | A sound plays on a new message. | Boolean! |
| assistantName | Name shown for the chatbot. | String! |
| assistantAvatar | Image shown for the chatbot. | String! |
| preChatWelcome | Greeting shown before the visitor writes. | String! |
| defaultQuestions | Suggested questions the visitor can click. | [String!]! |
ProviderStatusType
| Field | Description | Data Type |
|---|---|---|
| code | OK, UNCHECKED, EMPTY_KEY, INVALID_KEY, INSUFFICIENT_QUOTA, RATE_LIMITED, MODEL_UNAVAILABLE or TRANSIENT_ERROR. | ProviderStatus! |
| reason | The problem, in words. Empty when the provider works. | String! |
| checkedAt | When the provider was last checked. | Time |
ReconcileStatusType
A sync that was stopped because it would have removed most of a provider's documents.
| Field | Description | Data Type |
|---|---|---|
| provider | The sync provider that was stopped. | String! |
| blockedAt | When it was stopped. Empty when nothing is wrong. | Time |
| wouldRemove | Documents the sync would have removed. | Int! |
| owned | Documents the provider has in the knowledge base. | Int! |
| sample | Some of the documents that would have been removed. | [String!]! |
AccountWorkspace
| Field | Description | Data Type |
|---|---|---|
| id | Workspace ID. | String! |
| name | Workspace name. | String! |
| domain | Store domain. | String! |
| magentoBaseURL | Store base URL. | String! |
| status | active or disabled. | String! |
| isCurrent | This is the workspace the credential belongs to. | Boolean! |
| createdAt | When the workspace was created. | String! |
| lastActivityAt | When the workspace last had a chat. | String |
| liveStatus | active when the workspace had a chat recently, else idle. | String! |
| licensed | The store has a valid eChat license. | Boolean! |
DailyTokensStat
| Field | Description | Data Type |
|---|---|---|
| date | The day, as YYYY-MM-DD. | String! |
| tokens | Tokens used on that day. | Int! |
| providers | Tokens per AI provider: provider and tokens. | [ProviderTokens!]! |
BooleanPayload
Returned by mutations that have no object to return.
| Field | Description | Data Type |
|---|---|---|
| success | The operation was done. | Boolean! |
| error | Why it was not done. Empty on success. | Error |
| message | An optional note about the result. | String |
Error
| Field | Description | Data Type |
|---|---|---|
| code | Error code, such as INVALID_TYPE. | String! |
| message | What went wrong, in words. | String! |
DashboardPeriod
| Value | Description |
|---|---|
| WEEK | The last 7 days, including today. |
| TWO_WEEKS | The last 14 days, including today. |
| MONTH | The last 30 days, including today. |
Usage Examples
The responses below are shortened and show sample values.
Read the latest conversations
Get the five conversations that changed last, with their visitor and country:
query {
conversations(perPage: 5, sorting: { field: UPDATED_AT, direction: DESC }) {
totalCount
edges {
node {
id
status
createdAt
messageCount
visitor { name email }
session { countryName }
}
}
}
}
Response:
{
"data": {
"conversations": {
"totalCount": 14,
"edges": [
{
"node": {
"id": "3d1c4826-e219-4230-9833-41bef2be80ea",
"status": "CLOSED",
"createdAt": "2026-09-23T12:01:44Z",
"messageCount": 6,
"visitor": { "name": "Anna", "email": "[email protected]" },
"session": { "countryName": "Germany" }
}
}
]
}
}
}
Sync conversations incrementally
Get only the conversations that changed since the last run, with their messages:
query {
conversations(perPage: 100, filters: { updatedAtFrom: "2026-09-23T00:00:00Z" }) {
totalPages
edges {
node {
id
updatedAt
messages { senderType body createdAt }
}
}
}
}
Response:
{
"data": {
"conversations": {
"totalPages": 1,
"edges": [
{
"node": {
"id": "3d1c4826-e219-4230-9833-41bef2be80ea",
"updatedAt": "2026-09-23T12:04:10Z",
"messages": [
{ "senderType": "VISITOR", "body": "Do you ship to Austria?", "createdAt": "2026-09-23T12:01:44Z" },
{ "senderType": "AI", "body": "Yes, we ship to Austria. Delivery takes 3-5 business days.", "createdAt": "2026-09-23T12:01:49Z" }
]
}
}
]
}
}
}
Request the next pages with page until it reaches totalPages.
Add an FAQ entry
mutation {
saveFaq(input: {
question: "Do you ship to Austria?"
answer: "Yes. Delivery to Austria takes 3-5 business days."
status: "enabled"
}) {
faq { id question status }
error { code message }
}
}
Response:
{
"data": {
"saveFaq": {
"faq": {
"id": "8b0f6c1e-5d7a-4c2b-9f3e-1a2b3c4d5e6f",
"question": "Do you ship to Austria?",
"status": "enabled"
},
"error": null
}
}
}
Find a product document by SKU
query {
documents(perPage: 5, filters: { searchQuery: "24-MB01" }) {
edges {
node { id identifier name }
}
}
}
Response:
{
"data": {
"documents": {
"edges": [
{
"node": {
"id": "c2a7e0d4-91f3-4b6e-8a15-7d9e2f4b6c80",
"identifier": "product.24-MB01",
"name": "Joust Duffle Bag"
}
}
]
}
}
}
A refused operation
A mutation sent with a read-only credential, an operation that is not part of this API, or a refused saveSettings field is refused with the code NOT_AVAILABLE:
mutation {
saveSettings(input: { openaiKey: "sk-..." }) { success }
}
Response:
{
"errors": [
{
"message": "saveSettings cannot set the AI provider key",
"extensions": { "code": "NOT_AVAILABLE" }
}
],
"data": null
}