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
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
| Attributes | Type | Description |
|---|---|---|
apiKey | string | Required. Your OpenAI API key. |
model | string | 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/gqmutation 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
| Attributes | Type | Description |
|---|---|---|
apiKey | string | Required. API key used by the Pinecone AI handler. |
model | string | 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.
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | Returns AIs whose name contains this text, case-insensitive. |
type | AIType | Returns only AIs of this type: |
subType | AISubType | Returns only AIs with this sub-type: |
AI fields
| Field | Type | Description |
|---|---|---|
id | string | The AI ID. |
workspaceId | number | The workspace ID. |
name | string | The AI name. |
type | AIType | The AI type: |
subType | AISubType | The |
integrationProperties | IntegrationProperties | The saved |
configuration | Configurations | The assistant settings: prompts, handover and end, tag rules, messages and voice. |
createdAt | DateTime | When the AI was created. |
deletedAt | DateTime | When the AI was deleted. Always |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery 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.
| Error | Cause |
|---|---|
User not Authenticated | The Authorization header or input.workspaceId is missing. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
This API key can only access its own workspace | The 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. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The AI ID. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery 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.
| Error | Cause |
|---|---|
User not Authenticated | The Authorization header or input.workspaceId is missing. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
This API key can only access its own workspace | The 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. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
name | string | Required. The AI name. A |
type | AIType | Required. |
integrationProperties | JSON | Required. Type-specific settings, see integrationProperties by type. Accepted keys: |
subType | AISubType |
|
configuration | ConfigurationsInput | Assistant settings, see configuration fields. Used by |
subType values
| Value | Purpose | Description |
|---|---|---|
qa | Q&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, |
profile | Contact details assistant | Greets the client and helps them review or update their name, surname, email, city and address. For each |
rating | Feedback 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 |
integrationProperties by type
createAi doesn’t check these keys. An AI saved without the keys its type needs never replies.
| Type | Keys | Description |
|---|---|---|
bc_ai | none | Send |
openai | apiKey, model | Both are needed for replies. See |
pinecone | apiKey, model | Both are needed for replies. See |
custom | endpoint, apiKey | Both are needed for replies. |
bc_flow | model, version |
|
configuration fields
| Attribute | Type | Description |
|---|---|---|
instructionsVersion | string |
|
askForName | boolean |
|
askForSurname | boolean |
|
askForEmail | boolean |
|
askForCity | boolean |
|
askForAddress | boolean |
|
handoverEnabled | boolean |
|
endEnabled | boolean |
|
contextPrompt | string |
|
rolePrompt | string |
|
personaPrompt | string |
|
constraints | string |
|
emptyResponseFallbackMessage | string |
|
closingMessage | string |
|
clientTagRules | TagRuleInput[] |
|
convTagRules | TagRuleInput[] |
|
voiceId | string | Voice calls: the |
voiceName | string | The chosen voice's |
voiceLanguage | string | Voice calls: the call language, |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation 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,personaPromptandconstraintsare saved asnull, so the default role and persona apply. - A prompt over its limit fails the request and nothing is saved.
- Only
bc_aihas a uniqueness rule: one active AI persubType, or, withoutsubType, one per name. Deleted AIs don’t count. integrationPropertieskeys other thanapiKey,endpoint,modelandversionfail the request with a validation error.
| Error | Cause |
|---|---|
Context prompt must be 512 characters or fewer | configuration.contextPrompt is longer than 512 characters. |
Role prompt must be 512 characters or fewer | configuration.rolePrompt is longer than 512 characters. |
Persona prompt must be 768 characters or fewer | configuration.personaPrompt is longer than 768 characters. |
Constraints must be 1024 characters or fewer | configuration.constraints is longer than 1024 characters. |
A bc_ai with subType 'qa' already exists in this workspace | An 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 workspace | subType is omitted and an active bc_ai with the same name exists. The message names the name you sent. |
User not Authenticated | The Authorization header or input.workspaceId is missing. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
You do not have permission to access this resource with your current role assignment | The 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 workspace | The 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. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The AI ID. |
name | string | The new name. An empty string is ignored. |
subType | AISubType | The new sub-type: |
integrationProperties | JSON | Keys to change, merged into the saved properties. See merge rules. |
configuration | ConfigurationsInput | Fields to change, merged into the saved configuration. See merge rules and configuration fields. |
Merge rules
| Field | You send | Result |
|---|---|---|
integrationProperties | omitted or `null` | Unchanged. |
integrationProperties | an object | Merged key by key: each key you send replaces the saved value, keys you leave out keep theirs, and a key sent as |
configuration | omitted or `{}` | Unchanged. |
configuration | an object | Merged field by field: each field you send replaces the saved value, fields you leave out keep theirs, and a field sent as |
configuration.clientTagRules, configuration.convTagRules | a list | Replaces the whole list. Send |
configuration | `null` | Removes the whole configuration. The AI then runs with its defaults. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation 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.
| Error | Cause |
|---|---|
AI not found in this workspace | integrationProperties is sent and the AI doesn’t exist, belongs to another workspace or is deleted. |
Context prompt must be 512 characters or fewer | configuration.contextPrompt is longer than 512 characters. |
Role prompt must be 512 characters or fewer | configuration.rolePrompt is longer than 512 characters. |
Persona prompt must be 768 characters or fewer | configuration.personaPrompt is longer than 768 characters. |
Constraints must be 1024 characters or fewer | configuration.constraints is longer than 1024 characters. |
User not Authenticated | The Authorization header or input.workspaceId is missing. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
You do not have permission to access this resource with your current role assignment | The calling user is a Manager, Agent+ or Agent, or the call uses an agent API key. |
This API key can only access its own workspace | The 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. |
Programming language examples
cURL
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).
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
id | string | Required. The AI ID. |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqmutation 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(assigneeIdwithstartWith: AIorAI_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.
| Error | Cause |
|---|---|
User not Authenticated | The Authorization header or input.workspaceId is missing. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
You do not have permission to access this resource with your current role assignment | The calling user is a Manager, Agent+ or Agent, or the call uses an agent API key. |
This API key can only access its own workspace | The 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. |
Programming language examples
cURL
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.
| Attribute | Type | Description |
|---|---|---|
workspaceId | number | Required. The workspace ID. |
language | string | Required. The voice language: |
AiVoice fields
| Field | Type | Description |
|---|---|---|
id | string | The voice ID. Save it as |
name | string | The voice name. Save it as |
language | string | The language you asked for. Save it as |
previewUrl | string | An HTTPS link to a short audio sample of the voice, or |
Request & Response
POST https://gateway.bcrumbs.net/bot/gqquery 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.
| Error | Cause |
|---|---|
Unsupported voice language | language isn’t en, ar or tr. |
Voice is not configured | Voice isn’t set up on the platform. |
Could not load voices | The voice list couldn’t be loaded. Try again later. |
User not Authenticated | The Authorization header or input.workspaceId is missing. |
Missing role assignment for the target user | The calling user has no role in the workspace. |
This API key can only access its own workspace | The 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. |
Programming language examples
cURL
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}"}'