Skip to Content
API ReferenceAI Assistants

AI Assistants

Overview

AI Assistants define how Bread Crumbs Bot generates responses for incoming messages. Each assistant is created with an AI type and type-specific integration properties.

Any role on the workspace can read AIs and voices. Creating, changing and deleting AIs needs the Owner or Admin role; see the Access line of each API. An API key only works in its own workspace. A request whose input.workspaceId names another workspace is rejected before any field runs, and a field whose own workspaceId names another workspace (written inline in the query, passed in another variable or sent in a later operation of a batch) fails with This API key can only access its own workspace.

Supported AI types

Shared model

All AI assistants are created through the same GraphQL mutations (createAi, patchAi, deleteAi) and queried using ais/ai. The behavior depends on type and integrationProperties.

Bread Crumbs AI assistant (Crumby) is a pre-built AI assistant customized to serve most common use cases. This one is created automatically for you when you get an access on Crumby Playground.

Runtime features

  • You can train Crumby with your own data on Crumby files and Crumby text pages.
  • Crumby can gather client information for you if that is enabled in Crumby settings.
  • Crumby can transfer the conversation to an agent if you have handover enabled in Crumby settings.
  • Crumby can apply tags to the client and/or conversation if you have any tag rules configured in Crumby settings.

OpenAI

OpenAI assistant uses your OpenAI API key and model to generate text replies.

AI type

Use openai in AI creation operation.

Integration properties

AttributesTypeDescription
apiKeystring

Required. Your OpenAI API key.

modelstring

Required. OpenAI model name (for example: gpt-4o, gpt-4.1).

Runtime behavior

  • Bot sends the incoming message content using the OpenAI AI adapter.
  • Bot returns a text response.

Special keywords

In case the agent returns a response containing one of the following keywords, Bot will handle them specially:

  • #HANDOVER#: Handover the conversation to an agent.
  • #END#: End the conversation.

Create OpenAI AI (GraphQL)

POST https://gateway.bcrumbs.net/bot/gq
mutation createAi($input: AICreateInput!) { createAi(input: $input) { id workspaceId name type integrationProperties createdAt } } input AICreateInput { workspaceId: Int! integrationProperties: JSON! name: String! type: AIType! }

Next is an example of the input for the createAi mutation in JSON format:

{ "input": { "workspaceId": 12, "name": "My OpenAI AI", "type": "openai", "integrationProperties": { "apiKey": "your-openai-api-key", "model": "gpt-4o" } } }

Pinecone

Pinecone assistant uses your configured Pinecone integration properties to generate text replies through the bot runtime.

AI type

Use pinecone in AI creation/patch operations.

Integration properties

AttributesTypeDescription
apiKeystring

Required. API key used by the Pinecone AI handler.

modelstring

Required. Model identifier used by the Pinecone AI handler.

Runtime behavior

  • Bot sends the incoming message content using the Pinecone AI adapter.
  • Bot returns a text response.

Special keywords

In case the agent returns a response containing one of the following keywords, Bot will handle them specially:

  • #HANDOVER#: Handover the conversation to an agent.
  • #END#: End the conversation.

Create Pinecone AI (GraphQL)

mutation createAi($input: AICreateInput!) { createAi(input: $input) { id workspaceId name type integrationProperties createdAt } } input AICreateInput { workspaceId: Int! integrationProperties: JSON! name: String! type: AIType! }

Next is an example of the input for the createAi mutation in JSON format:

{ "input": { "workspaceId": 12, "name": "My Pinecone AI", "type": "pinecone", "integrationProperties": { "apiKey": "your-pinecone-api-key", "model": "pinecone-model-id" } } }

Custom AI

Custom AI lets you connect your own AI provider through a custom HTTP endpoint. Bread Crumbs sends conversation history to your endpoint (including text, audio, and document messages with typed URLs) and delivers your reply back to the customer, including optional audio or document responses.

See the full request/response contract, media handling, and examples in the Custom AI integration guide.

You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

List AIs API

List the workspace’s AI assistants, newest first. Deleted AIs are never returned, and the list isn’t paginated. integrationProperties returns only endpoint, model and version: a saved apiKey is never returned.

Access: Any role on the workspace (Owner, Admin, Manager, Agent+ or Agent). Works with workspace API keys and with agent API keys of any role, in the key’s own workspace.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Returns AIs whose name contains this text, case-insensitive.

typeAIType

Returns only AIs of this type: bc_ai, openai, pinecone, custom or bc_flow. Omit it to include every type.

subTypeAISubType

Returns only AIs with this sub-type: qa, rating or profile. Omit it to include every sub-type.

AI fields

FieldTypeDescription
idstring

The AI ID.

workspaceIdnumber

The workspace ID.

namestring

The AI name.

typeAIType

The AI type: bc_ai (Bread Crumbs AI, Crumby), openai, pinecone, custom or bc_flow (a scripted conversation flow). It can't be changed after creation.

subTypeAISubType

The bc_ai behavior: qa, rating or profile. null when not set. See subType values.

integrationPropertiesIntegrationProperties

The saved endpoint, model and version. apiKey is write-only and never returned.

configurationConfigurations

The assistant settings: prompts, handover and end, tag rules, messages and voice. null until set. See configuration fields.

createdAtDateTime

When the AI was created.

deletedAtDateTime

When the AI was deleted. Always null in List AIs and Get AI, which skip deleted AIs.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
query ais($input: AIsInput!) { ais(input: $input) { nodes { id name type subType integrationProperties { endpoint model version } configuration { handoverEnabled endEnabled voiceLanguage } createdAt deletedAt } } } input AIsInput { workspaceId: Int! # Workspace ID. name: String # Case-insensitive name contains. type: AIType # Filter by type. subType: AISubType # Filter by sub-type. } enum AIType { bc_ai openai pinecone custom bc_flow } enum AISubType { qa rating profile }

The query above returns JSON structured like this:

{ "data": { "ais": { "nodes": [ { "id": "ai_456", "name": "Order Status Bot", "type": "custom", "subType": null, "integrationProperties": { "endpoint": "https://ai.example.com/bcrumbs/reply", "model": null, "version": null }, "configuration": null, "createdAt": "2026-10-17T09:30:00.000Z", "deletedAt": null }, { "id": "ai_123", "name": "Crumby AI", "type": "bc_ai", "subType": "qa", "integrationProperties": { "endpoint": null, "model": null, "version": null }, "configuration": { "handoverEnabled": true, "endEnabled": true, "voiceLanguage": "en" }, "createdAt": "2026-09-02T08:15:00.000Z", "deletedAt": null } ] } } }

A Channel or conversation can still point to an AI that is missing here because it was deleted. See Delete AI API.

ErrorCause
User not AuthenticatedThe Authorization header or input.workspaceId is missing.
Missing role assignment for the target userThe calling user has no role in the workspace.
This API key can only access its own workspaceThe call uses an API key and the field’s workspaceId belongs to another workspace, for example a value written inline in the query, passed in another variable or sent in a later operation of a batch.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"ais","variables":{"input":{"workspaceId":12}},"query":"query ais($input: AIsInput!) {\n ais(input: $input) {\n nodes {\n id\n name\n type\n subType\n integrationProperties {\n endpoint\n model\n version\n }\n configuration {\n handoverEnabled\n endEnabled\n voiceLanguage\n }\n createdAt\n deletedAt\n }\n }\n}"}'

Get AI API

Get one AI assistant by ID, with its full configuration. Deleted AIs and AIs of other workspaces aren’t returned. A saved apiKey is never returned.

Access: Any role on the workspace (Owner, Admin, Manager, Agent+ or Agent). Works with workspace API keys and with agent API keys of any role, in the key’s own workspace.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The AI ID.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
query ai($input: AIInput!) { ai(input: $input) { id name type subType configuration { instructionsVersion handoverEnabled endEnabled contextPrompt rolePrompt personaPrompt constraints emptyResponseFallbackMessage closingMessage clientTagRules { tag rule } convTagRules { tag rule } voiceId voiceName voiceLanguage } createdAt } } input AIInput { workspaceId: Int! # Workspace ID. id: ID! # AI ID. }

The query above returns JSON structured like this:

{ "data": { "ai": { "id": "ai_123", "name": "Crumby AI", "type": "bc_ai", "subType": "qa", "configuration": { "instructionsVersion": "1.1", "handoverEnabled": true, "endEnabled": true, "contextPrompt": "Acme Dental runs two clinics in Dubai, open Sunday to Thursday from 9:00 to 18:00.", "rolePrompt": null, "personaPrompt": "Warm, brief and professional. Reply in the client's language.", "constraints": "Never quote treatment prices. Offer a free consultation instead.", "emptyResponseFallbackMessage": "Sorry, I couldn't prepare an answer. Could you rephrase your question?", "closingMessage": "Thanks for contacting Acme Dental. Have a great day!", "clientTagRules": [ { "tag": "vip", "rule": "The client mentions an ongoing treatment plan." } ], "convTagRules": [ { "tag": "booking", "rule": "The client wants to book or move an appointment." } ], "voiceId": "voice_123", "voiceName": "Maya", "voiceLanguage": "en" }, "createdAt": "2026-09-02T08:15:00.000Z" } } }

An unknown id, a deleted AI or an AI of another workspace fails with a not-found error.

ErrorCause
User not AuthenticatedThe Authorization header or input.workspaceId is missing.
Missing role assignment for the target userThe calling user has no role in the workspace.
This API key can only access its own workspaceThe call uses an API key and the field’s workspaceId belongs to another workspace, for example a value written inline in the query, passed in another variable or sent in a later operation of a batch.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"ai","variables":{"input":{"workspaceId":12,"id":"ai_123"}},"query":"query ai($input: AIInput!) {\n ai(input: $input) {\n id\n name\n type\n subType\n configuration {\n instructionsVersion\n handoverEnabled\n endEnabled\n contextPrompt\n rolePrompt\n personaPrompt\n constraints\n emptyResponseFallbackMessage\n closingMessage\n clientTagRules {\n tag\n rule\n }\n convTagRules {\n tag\n rule\n }\n voiceId\n voiceName\n voiceLanguage\n }\n createdAt\n }\n}"}'

Create AI API

Create an AI assistant. type picks the engine that replies and can’t be changed later. Each type needs its own integrationProperties, listed below and in the per-type sections above: Bread Crumbs AI, openai, pinecone and Custom AI. The example creates a Crumby Q&A assistant (bc_ai). Creating an AI doesn’t connect it to a Channel: to have it answer new conversations, set the Channel properties to startWith: AI and assigneeId to the AI ID with Patch Channel API. No webhook fires.

Access: Owner or Admin (MANAGE_WORKSPACE). Works with workspace API keys. Agent API keys can’t call it, whatever their role (Manager, Agent+ or Agent). Exception: any role, and any agent API key, can create the default Crumby record: a bc_ai named Crumby AI with no subType and no configuration. The portal inbox creates it the first time a conversation is assigned to Crumby.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

namestring

Required. The AI name. A bc_ai created without subType needs a name that no other active bc_ai in the workspace uses.

typeAIType

Required. bc_ai, openai, pinecone, custom or bc_flow. Can't be changed later.

integrationPropertiesJSON

Required. Type-specific settings, see integrationProperties by type. Accepted keys: apiKey, endpoint, model and version; other keys are rejected. apiKey is stored but never returned.

subTypeAISubType

bc_ai only: qa, rating or profile, see subType values. A workspace can have one active bc_ai per sub-type. Other types ignore it.

configurationConfigurationsInput

Assistant settings, see configuration fields. Used by bc_ai and by AI voice calls. When omitted, configuration stays null.

subType values

ValuePurposeDescription
qaQ&A assistant

Answers client questions using only the knowledge you train it on (Crumby files and Crumby text), and says so when it can't find an answer. It can hand the conversation over to an agent, end it and apply tag rules. It uses the prompts, tag rules, handoverEnabled, endEnabled, emptyResponseFallbackMessage and closingMessage.

profileContact details assistant

Greets the client and helps them review or update their name, surname, email, city and address. For each askFor... flag that is on, it points out the missing field and offers to fill it, asks one field at a time, and confirms each value before saving it to the client. When the client asks about anything else, it hands the conversation over without sending a message.

ratingFeedback assistant

Runs the post-conversation feedback flow: asks for a rating from 1 to 5, a reason and a comment, saves them as the conversation feedback, thanks the client and ends the conversation. If the client refuses, it ends the conversation. It starts when a conversation on a Channel with ratingEnabled: true and ratingAiId set to this AI's ID in its properties is ended. It ignores configuration.

integrationProperties by type

createAi doesn’t check these keys. An AI saved without the keys its type needs never replies.

TypeKeysDescription
bc_ainone

Send {}. Without a subType, the AI behaves as qa. See Bread Crumbs AI.

openaiapiKey, model

Both are needed for replies. See openai.

pineconeapiKey, model

Both are needed for replies. See pinecone.

customendpoint, apiKey

Both are needed for replies. apiKey is sent to your endpoint in the x-api-key header. See Custom AI and the Custom AI integration guide.

bc_flowmodel, version

model is the name of a scripted conversation flow stored for the workspace, and version its version. model is needed for replies.

configuration fields

AttributeTypeDescription
instructionsVersionstring

qa: the instruction set, 1.0 or 1.1. Unset or unknown values use 1.0.

askForNameboolean

profile: offer to collect the client's first name when it is missing. Off when unset.

askForSurnameboolean

profile: offer to collect the client's surname when it is missing. Off when unset.

askForEmailboolean

profile: offer to collect the client's email when it is missing. Off when unset.

askForCityboolean

profile: offer to collect the client's city when it is missing. Off when unset.

askForAddressboolean

profile: offer to collect the client's address when it is missing. Off when unset.

handoverEnabledboolean

qa: let the AI hand the conversation over to an agent when the client asks for a person, is frustrated, wants to buy, get a quote or book (after the client confirms), or when it can't find an answer. When false, the AI keeps answering. An AI with no configuration at all allows handover. Set it explicitly.

endEnabledboolean

qa: let the AI send a closing message and end the conversation when the client is done. When false, the AI doesn't end the conversation. An AI with no configuration at all allows ending. Set it explicitly.

contextPromptstring

qa: business context added to the AI's instructions, for example what you sell and your opening hours. Up to 512 characters.

rolePromptstring

qa: replaces the default role (a friendly customer support assistant that answers only from your knowledge). Up to 512 characters.

personaPromptstring

qa: replaces the default tone and style (friendly, warm, professional, one question at a time). Up to 768 characters.

constraintsstring

qa: extra rules the AI must follow. Up to 1024 characters.

emptyResponseFallbackMessagestring

qa: sent when the AI can't prepare a reply. Default: I'm sorry, I wasn't able to prepare a reply just now. How can I help you?

closingMessagestring

qa: sent when the AI ends the conversation without writing a goodbye itself. When unset, the fallback message is sent instead.

clientTagRulesTagRuleInput[]

qa: rules for tagging the client. Each rule has tag (the tag to apply) and rule (when to apply it, in plain language). The AI checks the rules before a handover or an end, and only applies tags listed here.

convTagRulesTagRuleInput[]

qa: rules for tagging the conversation, same shape and timing as clientTagRules.

voiceIdstring

Voice calls: the id of a voice from List AI Voices API. It speaks the AI's replies on calls the AI answers. Unset: the platform default voice. Voice calls answered by an AI always use the qa behavior with this configuration.

voiceNamestring

The chosen voice's name, stored so Crumby settings can show it. Not used on calls.

voiceLanguagestring

Voice calls: the call language, en, ar or tr. Use the language you listed voices for. It also sets the language of the short spoken line used when the AI transfers or ends a call without saying anything. Unset: the platform default language.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation createAi($input: AICreateInput!) { createAi(input: $input) { id name type subType configuration { instructionsVersion handoverEnabled endEnabled convTagRules { tag rule } voiceId voiceLanguage } createdAt } } input AICreateInput { workspaceId: Int! # Workspace ID. integrationProperties: JSON! # apiKey, endpoint, model, version. name: String! # AI name. type: AIType! # Engine; fixed after creation. subType: AISubType # bc_ai behavior. configuration: ConfigurationsInput # Assistant settings. } input ConfigurationsInput { instructionsVersion: String # qa instruction set: 1.0 or 1.1. askForName: Boolean # profile: collect first name. askForSurname: Boolean # profile: collect surname. askForEmail: Boolean # profile: collect email. askForCity: Boolean # profile: collect city. askForAddress: Boolean # profile: collect address. handoverEnabled: Boolean # qa: allow handover to an agent. endEnabled: Boolean # qa: allow ending the conversation. contextPrompt: String # qa: business context, max 512 chars. rolePrompt: String # qa: role, max 512 chars. personaPrompt: String # qa: tone and style, max 768 chars. constraints: String # qa: extra rules, max 1024 chars. emptyResponseFallbackMessage: String # qa: sent when no reply could be prepared. closingMessage: String # qa: sent when the AI ends without a goodbye. clientTagRules: [TagRuleInput!] # qa: client tagging rules. convTagRules: [TagRuleInput!] # qa: conversation tagging rules. voiceId: String # Voice ID from aiVoices. voiceName: String # Voice name, for display. voiceLanguage: String # Voice call language: en, ar or tr. } input TagRuleInput { tag: String! # Tag to apply. rule: String! # When to apply it, in plain language. } enum AIType { bc_ai openai pinecone custom bc_flow } enum AISubType { qa rating profile }

The mutation above returns JSON structured like this:

{ "data": { "createAi": { "id": "ai_123", "name": "Crumby AI", "type": "bc_ai", "subType": "qa", "configuration": { "instructionsVersion": "1.1", "handoverEnabled": true, "endEnabled": true, "convTagRules": [ { "tag": "booking", "rule": "The client wants to book or move an appointment." } ], "voiceId": "voice_123", "voiceLanguage": "en" }, "createdAt": "2026-10-17T09:30:00.000Z" } } }

Validation and defaults:

  • Blank contextPrompt, rolePrompt, personaPrompt and constraints are saved as null, so the default role and persona apply.
  • A prompt over its limit fails the request and nothing is saved.
  • Only bc_ai has a uniqueness rule: one active AI per subType, or, without subType, one per name. Deleted AIs don’t count.
  • integrationProperties keys other than apiKey, endpoint, model and version fail the request with a validation error.
ErrorCause
Context prompt must be 512 characters or fewerconfiguration.contextPrompt is longer than 512 characters.
Role prompt must be 512 characters or fewerconfiguration.rolePrompt is longer than 512 characters.
Persona prompt must be 768 characters or fewerconfiguration.personaPrompt is longer than 768 characters.
Constraints must be 1024 characters or fewerconfiguration.constraints is longer than 1024 characters.
A bc_ai with subType 'qa' already exists in this workspaceAn active bc_ai with the same subType exists. The message names the sub-type you sent.
A bc_ai with name 'Crumby AI' already exists in this workspacesubType is omitted and an active bc_ai with the same name exists. The message names the name you sent.
User not AuthenticatedThe Authorization header or input.workspaceId is missing.
Missing role assignment for the target userThe calling user has no role in the workspace.
You do not have permission to access this resource with your current role assignmentThe calling user is a Manager, Agent+ or Agent, or the call uses an agent API key, and the input isn’t the default Crumby record.
This API key can only access its own workspaceThe call uses an API key and the field’s workspaceId belongs to another workspace, for example a value written inline in the query, passed in another variable or sent in a later operation of a batch.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"createAi","variables":{"input":{"workspaceId":12,"name":"Crumby AI","type":"bc_ai","subType":"qa","integrationProperties":{},"configuration":{"instructionsVersion":"1.1","handoverEnabled":true,"endEnabled":true,"contextPrompt":"Acme Dental runs two clinics in Dubai, open Sunday to Thursday from 9:00 to 18:00.","personaPrompt":"Warm, brief and professional. Reply in the client'\''s language.","constraints":"Never quote treatment prices. Offer a free consultation instead.","closingMessage":"Thanks for contacting Acme Dental. Have a great day!","convTagRules":[{"tag":"booking","rule":"The client wants to book or move an appointment."}],"voiceId":"voice_123","voiceName":"Maya","voiceLanguage":"en"}}},"query":"mutation createAi($input: AICreateInput!) {\n createAi(input: $input) {\n id\n name\n type\n subType\n configuration {\n instructionsVersion\n handoverEnabled\n endEnabled\n convTagRules {\n tag\n rule\n }\n voiceId\n voiceLanguage\n }\n createdAt\n }\n}"}'

Patch AI API

Update an AI assistant’s name, sub-type, integration properties or configuration. Fields you leave out keep their values. type can’t be changed: create a new AI instead. The example turns off handover, changes the closing message and replaces the conversation tag rules, while endEnabled and the other saved settings stay as they were.

Access: Owner or Admin (MANAGE_WORKSPACE). Works with workspace API keys. Agent API keys can’t call it, whatever their role (Manager, Agent+ or Agent).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The AI ID.

namestring

The new name. An empty string is ignored.

subTypeAISubType

The new sub-type: qa, rating or profile. Send null to clear it.

integrationPropertiesJSON

Keys to change, merged into the saved properties. See merge rules.

configurationConfigurationsInput

Fields to change, merged into the saved configuration. See merge rules and configuration fields.

Merge rules

FieldYou sendResult
integrationPropertiesomitted or `null`

Unchanged.

integrationPropertiesan object

Merged key by key: each key you send replaces the saved value, keys you leave out keep theirs, and a key sent as null is cleared. Only apiKey, endpoint, model and version are accepted. To rotate an apiKey, send just that key.

configurationomitted or `{}`

Unchanged.

configurationan object

Merged field by field: each field you send replaces the saved value, fields you leave out keep theirs, and a field sent as null is cleared. Blank prompts are saved as null. If the AI had no configuration, one is created from the fields you send.

configuration.clientTagRules, configuration.convTagRulesa list

Replaces the whole list. Send [] to remove every rule.

configuration`null`

Removes the whole configuration. The AI then runs with its defaults.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation patchAi($input: AIPatchInput!) { patchAi(input: $input) { id name configuration { handoverEnabled endEnabled closingMessage convTagRules { tag rule } } } } input AIPatchInput { workspaceId: Int! # Workspace ID. id: ID! # AI ID. integrationProperties: JSON # Keys to merge. name: String # New name. subType: AISubType # New sub-type, or null to clear. configuration: ConfigurationsInput # Fields to merge, or null to remove. } input ConfigurationsInput { instructionsVersion: String # qa instruction set: 1.0 or 1.1. askForName: Boolean # profile: collect first name. askForSurname: Boolean # profile: collect surname. askForEmail: Boolean # profile: collect email. askForCity: Boolean # profile: collect city. askForAddress: Boolean # profile: collect address. handoverEnabled: Boolean # qa: allow handover to an agent. endEnabled: Boolean # qa: allow ending the conversation. contextPrompt: String # qa: business context, max 512 chars. rolePrompt: String # qa: role, max 512 chars. personaPrompt: String # qa: tone and style, max 768 chars. constraints: String # qa: extra rules, max 1024 chars. emptyResponseFallbackMessage: String # qa: sent when no reply could be prepared. closingMessage: String # qa: sent when the AI ends without a goodbye. clientTagRules: [TagRuleInput!] # qa: client tagging rules. convTagRules: [TagRuleInput!] # qa: conversation tagging rules. voiceId: String # Voice ID from aiVoices. voiceName: String # Voice name, for display. voiceLanguage: String # Voice call language: en, ar or tr. } input TagRuleInput { tag: String! # Tag to apply. rule: String! # When to apply it, in plain language. } enum AISubType { qa rating profile }

The mutation above returns JSON structured like this:

{ "data": { "patchAi": { "id": "ai_123", "name": "Crumby AI", "configuration": { "handoverEnabled": false, "endEnabled": true, "closingMessage": "Thanks for chatting with Acme Dental. See you soon!", "convTagRules": [ { "tag": "booking", "rule": "The client wants to book or move an appointment." }, { "tag": "complaint", "rule": "The client is unhappy with a treatment or the service." } ] } } } }

When the request has no integrationProperties, an unknown id fails with a not-found error.

ErrorCause
AI not found in this workspaceintegrationProperties is sent and the AI doesn’t exist, belongs to another workspace or is deleted.
Context prompt must be 512 characters or fewerconfiguration.contextPrompt is longer than 512 characters.
Role prompt must be 512 characters or fewerconfiguration.rolePrompt is longer than 512 characters.
Persona prompt must be 768 characters or fewerconfiguration.personaPrompt is longer than 768 characters.
Constraints must be 1024 characters or fewerconfiguration.constraints is longer than 1024 characters.
User not AuthenticatedThe Authorization header or input.workspaceId is missing.
Missing role assignment for the target userThe calling user has no role in the workspace.
You do not have permission to access this resource with your current role assignmentThe calling user is a Manager, Agent+ or Agent, or the call uses an agent API key.
This API key can only access its own workspaceThe call uses an API key and the field’s workspaceId belongs to another workspace, for example a value written inline in the query, passed in another variable or sent in a later operation of a batch.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"patchAi","variables":{"input":{"workspaceId":12,"id":"ai_123","configuration":{"handoverEnabled":false,"closingMessage":"Thanks for chatting with Acme Dental. See you soon!","convTagRules":[{"tag":"booking","rule":"The client wants to book or move an appointment."},{"tag":"complaint","rule":"The client is unhappy with a treatment or the service."}]}}},"query":"mutation patchAi($input: AIPatchInput!) {\n patchAi(input: $input) {\n id\n name\n configuration {\n handoverEnabled\n endEnabled\n closingMessage\n convTagRules {\n tag\n rule\n }\n }\n }\n}"}'

Delete AI API

Delete an AI assistant. The AI is soft-deleted: deletedAt is set, and it no longer appears in List AIs or Get AI. The workspace knowledge (Crumby files and text) is shared by the workspace and isn’t deleted. After deleting a bc_ai, you can create a new one with the same sub-type or name. No webhook fires.

Access: Owner or Admin (MANAGE_WORKSPACE). Works with workspace API keys. Agent API keys can’t call it, whatever their role (Manager, Agent+ or Agent).

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

idstring

Required. The AI ID.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
mutation deleteAi($input: AIDeleteInput!) { deleteAi(input: $input) { id name type deletedAt } } input AIDeleteInput { workspaceId: Int! # Workspace ID. id: ID! # AI ID. }

The mutation above returns JSON structured like this:

{ "data": { "deleteAi": { "id": "ai_456", "name": "Order Status Bot", "type": "custom", "deletedAt": "2026-10-20T14:05:00.000Z" } } }

Deleting doesn’t change anything that points to the AI:

  • Channels keep the AI ID in their properties (assigneeId with startWith: AI or AI_BY_COUNTRY_CODE, byCountryCodeConfig[].assigneeId, ratingAiId) and keep assigning new conversations to it.
  • Conversations assigned to the AI stay assigned. New client messages in them get no AI reply, and the conversation isn’t handed over to an agent.

Before deleting, point those Channels to another assignee with Patch Channel API, and move open conversations to an agent with Handover Conversation API.

An unknown id or an AI of another workspace fails with a not-found error.

ErrorCause
User not AuthenticatedThe Authorization header or input.workspaceId is missing.
Missing role assignment for the target userThe calling user has no role in the workspace.
You do not have permission to access this resource with your current role assignmentThe calling user is a Manager, Agent+ or Agent, or the call uses an agent API key.
This API key can only access its own workspaceThe call uses an API key and the field’s workspaceId belongs to another workspace, for example a value written inline in the query, passed in another variable or sent in a later operation of a batch.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"deleteAi","variables":{"input":{"workspaceId":12,"id":"ai_456"}},"query":"mutation deleteAi($input: AIDeleteInput!) {\n deleteAi(input: $input) {\n id\n name\n type\n deletedAt\n }\n}"}'

List AI Voices API

List the voices an AI assistant can speak with on voice calls, for one language. Save the chosen voice’s id, name and language as voiceId, voiceName and voiceLanguage in the AI configuration with Patch AI API. The AI then uses that voice and language on the calls it answers. The list is the same for every workspace and can be up to 10 minutes old.

Access: Any role on the workspace (Owner, Admin, Manager, Agent+ or Agent). Works with workspace API keys and with agent API keys of any role, in the key’s own workspace.

AttributeTypeDescription
workspaceIdnumber

Required. The workspace ID.

languagestring

Required. The voice language: en, ar or tr.

AiVoice fields

FieldTypeDescription
idstring

The voice ID. Save it as configuration.voiceId.

namestring

The voice name. Save it as configuration.voiceName.

languagestring

The language you asked for. Save it as configuration.voiceLanguage.

previewUrlstring

An HTTPS link to a short audio sample of the voice, or null.

Request & Response

POST https://gateway.bcrumbs.net/bot/gq
query aiVoices($input: AiVoicesInput!) { aiVoices(input: $input) { id name language previewUrl } } input AiVoicesInput { workspaceId: Int! # Workspace ID. language: String! # en, ar or tr. }

The query above returns JSON structured like this:

{ "data": { "aiVoices": [ { "id": "voice_123", "name": "Maya", "language": "en", "previewUrl": "https://files.example.com/voice-previews/voice_123.mp3" }, { "id": "voice_456", "name": "Omar", "language": "en", "previewUrl": null } ] } }

When an AI has no voiceId or voiceLanguage, its calls use the platform default voice and language.

ErrorCause
Unsupported voice languagelanguage isn’t en, ar or tr.
Voice is not configuredVoice isn’t set up on the platform.
Could not load voicesThe voice list couldn’t be loaded. Try again later.
User not AuthenticatedThe Authorization header or input.workspaceId is missing.
Missing role assignment for the target userThe calling user has no role in the workspace.
This API key can only access its own workspaceThe call uses an API key and the field’s workspaceId belongs to another workspace, for example a value written inline in the query, passed in another variable or sent in a later operation of a batch.
You can check our playground to explore and interact with GraphQL APIs easily and intuitively with real-time documentation.

Programming language examples

curl -X POST 'https://gateway.bcrumbs.net/bot/gq' \ -H 'authorization: API-KEY' \ -H 'content-type: application/json' \ -d '{"operationName":"aiVoices","variables":{"input":{"workspaceId":12,"language":"en"}},"query":"query aiVoices($input: AiVoicesInput!) {\n aiVoices(input: $input) {\n id\n name\n language\n previewUrl\n }\n}"}'