Agent APIs

Overview

Manage workspace agents and their profile information. An agent is a user that can be assigned to a conversation. A system user can have only one agent.

An agent is created for a user automatically when the user is invited to the workspace and he accepts the invitation and accessed the portal. However that agent is created with default name, if you want to change the name you can do it in the portal. You can manage agents directly from the Agents page (opens in a new tab).

Agent properties

Property	Type	Description
`workspaceId`	`number`	The workspace ID.
`id`	`string`	The agent ID.
`userId`	`string`	The user ID linked to the agent.
`name`	`string`	The agent first name.
`surname`	`string`	The agent surname.
`email`	`string`	The agent email.
`avatar`	`string`	The agent avatar URL. You can use Gravatar for the avatar. Or patch the agent with a custom avatar URL.
`createdAt`	`DateTime`	The timestamp when the agent was created.

List Agents API

List the agents in the workspace. Next are the available filters to list the agents.

This endpoint supports pagination. See Pagination for more information.

Attribute	Type	Description
`workspaceId`	`number`	Required. The workspace ID.
`conversationId`	`string`	Filter agents by conversation ID.
`name`	`string`	Filter agents by name.
`surname`	`string`	Filter agents by surname.
`email`	`string`	Filter agents by email.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

query agents($input: AgentsInput!) {
  agents(input: $input) {
    nodes {
      id
      userId
      name
      surname
      email
    }
    pageInfo {
      hasNextPage
      endCursor
      count
    }
  }
}
 
input AgentsInput {
  workspaceId: Int! # Workspace ID.
  conversationId: String # Filter agents by conversation ID.
  name: String # Filter agents by name.
  surname: String # Filter agents by surname.
  email: String # Filter agents by email.
}

The query above returns JSON structured like this:

{
  "data": {
    "agents": {
      "nodes": [
        {
          "id": "id_123",
          "userId": "sample",
          "name": "sample",
          "surname": "sample",
          "email": "[email protected]"
        }
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "cursor_123",
        "count": 1
      }
    }
  }
}

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/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  -d '{"operationName":"agents","variables":{"input":{"workspaceId":12,"conversationId":"sample","name":"sample","surname":"sample","email":"[email protected]"}},"query":"query agents($input: AgentsInput!) {\\n  agents(input: $input) {\\n    nodes {\\n      id\\n      userId\\n      name\\n      surname\\n      email\\n    }\\n    pageInfo {\\n      hasNextPage\\n      endCursor\\n      count\\n    }\\n  }\\n}"}'

Create Agent API

Create an agent for a user.

Attribute	Type	Description
`workspaceId`	`number`	Required. The workspace ID.
`userId`	`string`	Required. User ID of the agent.
`name`	`string`	Required. The name of the agent.
`surname`	`string`	The surname of the agent.
`email`	`string`	Required. Agent email.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

mutation createAgent($input: AgentCreateInput!) {
  createAgent(input: $input) {
    id
    userId
    name
    surname
    email
  }
}
 
input AgentCreateInput {
  workspaceId: Int! # Workspace ID.
  userId: String! # User ID of the agent.
  name: String! # Agent first name.
  surname: String # Agent surname.
  email: String! # Agent email.
}

The mutation above returns JSON structured like this:

{
  "data": {
    "createAgent": {
      "id": "id_123",
      "userId": "sample",
      "name": "sample",
      "surname": "sample",
      "email": "[email protected]"
    }
  }
}

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/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  -d '{"operationName":"createAgent","variables":{"input":{"workspaceId":12,"userId":"sample","name":"sample","surname":"sample","email":"[email protected]"}},"query":"mutation createAgent($input: AgentCreateInput!) {\\n  createAgent(input: $input) {\\n    id\\n    userId\\n    name\\n    surname\\n    email\\n  }\\n}"}'

Create agent with API key

Creates an agent and an API key linked to that agent in a single atomic operation. The returned API key uses Agent+ scope (same as linking a key via genApiKey with agentId). The raw secret is only returned in this response.

Field	Type	Description
`workspaceId`	`Int!`	Target workspace.
`userId`	`String`	Optional. Invited workspace user id. If omitted, a synthetic `api:…` id is stored for API-key-only agents. If the email is provided and the user is invited to the workspace, the agent will be linked to the invited user automatically after accessing the workspace.
`name`	`String!`	Agent first name.
`surname`	`String`	Agent surname.
`email`	`String`	Optional. If omitted, stored as an empty string (API-key-only / non-login agents).
`apiKeyLabel`	`String`	Optional. Defaults to "API key · {name}" (includes surname if provided) when omitted.

mutation createAgentWithApiKey($input: AgentCreateWithApiKeyInput!) {
  createAgentWithApiKey(input: $input) {
    agent {
      id
      workspaceId
      userId
      name
      surname
      email
      createdAt
    }
    apiKey {
      workspaceId
      id
      key
      label
      agentId
      createdAt
    }
  }
}
 
input AgentCreateWithApiKeyInput {
  workspaceId: Int!
  userId: String
  name: String!
  surname: String
  email: String
  apiKeyLabel: String
}

Patch Agent API

Patch an agent, you can only patch the name and surname of the agent.

Attribute	Type	Description
`workspaceId`	`number`	Required. The workspace ID.
`id`	`string`	Required. The ID.
`name`	`string`	Required. The name.
`surname`	`string`	Agent surname.

Request & Response

POST https://gateway.bcrumbs.net/core/gq

mutation patchAgent($input: AgentPatchInput!) {
  patchAgent(input: $input) {
    id
    userId
    name
    surname
    email
  }
}
 
input AgentPatchInput {
  workspaceId: Int! # Workspace ID.
  id: ID! # Agent ID.
  name: String! # Agent first name.
  surname: String # Agent surname.
}

The mutation above returns JSON structured like this:

{
  "data": {
    "patchAgent": {
      "id": "id_123",
      "userId": "sample",
      "name": "sample",
      "surname": "sample",
      "email": "[email protected]"
    }
  }
}

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/core/gq' \
  -H 'authorization: API-KEY' \
  -H 'content-type: application/json' \
  -d '{"operationName":"patchAgent","variables":{"input":{"workspaceId":12,"id":"id_123","name":"sample","surname":"sample"}},"query":"mutation patchAgent($input: AgentPatchInput!) {\\n  patchAgent(input: $input) {\\n    id\\n    userId\\n    name\\n    surname\\n    email\\n  }\\n}"}'

Contacts AI Assistants