Chatbots - Humanly Developer Docs

Overview

Chatbots are AI Career Chat assistants scoped to a team. Each chatbot has a configuration (tool toggles, welcome message, branding, language) and may have attached jobs and knowledge bases. This resource supports full create, read, update, archive, and unarchive operations. The status field is returned as ACTIVE or ARCHIVED. By default, GET /qsi/gather/chatbots returns only active chatbots; pass archived=true to list archived ones instead.

Create Chatbot

Create a new chatbot. Endpoint: POST /qsi/gather/chatbots

cURL
JavaScript
Python

curl -X POST https://api.prod.qualifi.hr/qsi/gather/chatbots \
  -H "x-api-key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Careers Bot",
    "displayName": "Careers Assistant",
    "language": "en",
    "useJobMatching": true,
    "welcomeMessage": "Hi! How can I help with your job search?"
  }'

const response = await fetch('https://api.prod.qualifi.hr/qsi/gather/chatbots', {
  method: 'POST',
  headers: {
    'x-api-key': apiKey,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Careers Bot',
    displayName: 'Careers Assistant',
    language: 'en',
    useJobMatching: true
  })
})
const { data } = await response.json()

response = requests.post(
    'https://api.prod.qualifi.hr/qsi/gather/chatbots',
    headers={'x-api-key': api_key, 'Content-Type': 'application/json'},
    json={
        'title': 'Careers Bot',
        'displayName': 'Careers Assistant',
        'language': 'en',
        'useJobMatching': True
    }
)
data = response.json()['data']

{
  "title": "Careers Bot",
  "displayName": "Careers Assistant",
  "language": "en",
  "useJobMatching": true,
  "welcomeMessage": "Hi! How can I help with your job search?"
}

{
  "data": {
    "chatbot": {
      "id": "uuid",
      "title": "Careers Bot",
      "displayName": "Careers Assistant",
      "status": "ACTIVE",
      "language": "en",
      "welcomeMessage": "Hi! How can I help with your job search?",
      "useJobMatching": true,
      "jobIds": [],
      "knowledgeBaseIds": [],
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

List Chatbots

List chatbots with pagination. archived=true to get archived only (true returns archived chatbots; default false returns active only). Endpoint: GET /qsi/gather/chatbots

page

number

Page number (default: 1)

pageSize

number

Items per page (default: 50)

archived

boolean

Return archived chatbots instead of active (default: false)

string

Search by title or display name

{
  "data": {
    "chatbots": [
      {
        "id": "uuid",
        "title": "Careers Bot",
        "displayName": "Careers Assistant",
        "status": "ACTIVE",
        "language": "en",
        "organizationId": "org-uuid",
        "teamId": "team-uuid",
        "createdById": "user-uuid",
        "createdAt": "2026-01-01T00:00:00Z",
        "updatedAt": "2026-01-01T00:00:00Z"
      }
    ],
    "pagination": { "total": 12, "page": 1, "totalPages": 1, "pageSize": 50 }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

The list response omits per-chatbot configuration, attached jobIds, and knowledgeBaseIds. Fetch a single chatbot with GET /qsi/gather/chatbots/{chatbotId} to retrieve the full configuration and attachments.

Get Chatbot

Retrieve a chatbot with its configuration and attached jobs/knowledge bases. Endpoint: GET /qsi/gather/chatbots/{chatbotId}

chatbotId

string

required

UUID of the chatbot

{
  "data": {
    "chatbot": {
      "id": "uuid",
      "title": "Careers Bot",
      "displayName": "Careers Assistant",
      "status": "ACTIVE",
      "language": "en",
      "welcomeMessage": "Hi! How can I help with your job search?",
      "friendlyTone": true,
      "useJobMatching": true,
      "useKnowledgeBase": true,
      "guardrails": ["Stay on topic"],
      "branding": { "accentColor": "#0000CC" },
      "allowedDomains": ["careers.example.com"],
      "jobPageUrlPattern": "/jobs/*",
      "jobIds": ["job-uuid-1", "job-uuid-2"],
      "knowledgeBaseIds": ["kb-uuid-1"],
      "organizationId": "org-uuid",
      "teamId": "team-uuid",
      "createdById": "user-uuid",
      "createdAt": "2026-01-01T00:00:00Z",
      "updatedAt": "2026-01-01T00:00:00Z"
    }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

Update Chatbot

Update a chatbot’s configuration. Any field accepted on create may be updated. Supplying jobIds or knowledgeBaseIds replaces the entire attached set. Endpoint: PATCH /qsi/gather/chatbots/{chatbotId}

chatbotId

string

required

UUID of the chatbot to update

{
  "welcomeMessage": "Welcome! Ask me about open roles.",
  "useJobMatching": false
}

{
  "data": {
    "chatbot": {
      "id": "uuid",
      "title": "Careers Bot",
      "status": "ACTIVE",
      "welcomeMessage": "Welcome! Ask me about open roles.",
      "useJobMatching": false,
      "updatedAt": "2026-01-02T00:00:00Z"
    }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-02T00:00:00Z" }
}

Update Attached Jobs

Replace the full set of jobs attached to a chatbot. Endpoint: PATCH /qsi/gather/chatbots/{chatbotId}/jobs

chatbotId

string

required

UUID of the chatbot

{ "jobIds": ["job-uuid-1", "job-uuid-2"] }

{
  "data": {
    "chatbot": {
      "id": "uuid",
      "status": "ACTIVE",
      "jobIds": ["job-uuid-1", "job-uuid-2"]
    }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-02T00:00:00Z" }
}

Update Attached Knowledge Bases

Replace the full set of knowledge bases attached to a chatbot. Endpoint: PATCH /qsi/gather/chatbots/{chatbotId}/knowledge-bases

chatbotId

string

required

UUID of the chatbot

{ "knowledgeBaseIds": ["kb-uuid-1"] }

{
  "data": {
    "chatbot": {
      "id": "uuid",
      "status": "ACTIVE",
      "knowledgeBaseIds": ["kb-uuid-1"]
    }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-02T00:00:00Z" }
}

Archive Chatbot

Archive a chatbot. Archived chatbots are excluded from the default list. Endpoint: DELETE /qsi/gather/chatbots/{chatbotId}

chatbotId

string

required

UUID of the chatbot to archive

{
  "data": {
    "chatbot": {
      "id": "uuid",
      "status": "ARCHIVED",
      "archivedAt": "2026-01-03T00:00:00Z"
    }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-03T00:00:00Z" }
}

Unarchive Chatbot

Restore an archived chatbot to active status. Endpoint: POST /qsi/gather/chatbots/{chatbotId}/unarchive

chatbotId

string

required

UUID of the chatbot to unarchive

{
  "data": {
    "chatbot": { "id": "uuid", "status": "ACTIVE" }
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-03T00:00:00Z" }
}

Error Responses

Errors use the standard envelope: a nested error object (code, message, and an optional details) alongside a meta block.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing or invalid fields in request body"
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid API key"
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Chatbot not found"
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Failed to process request"
  },
  "meta": { "requestId": "uuid", "timestamp": "2026-01-01T00:00:00Z" }
}

Conversations

Read chatbot conversations and messages

Analytics

Chatbot engagement and funnel metrics

​Overview

​Create Chatbot

​List Chatbots

​Get Chatbot

​Update Chatbot

​Update Attached Jobs

​Update Attached Knowledge Bases

​Archive Chatbot

​Unarchive Chatbot

​Error Responses

​Related Resources

Conversations

Analytics

Overview

Create Chatbot

List Chatbots

Get Chatbot

Update Chatbot

Update Attached Jobs

Update Attached Knowledge Bases

Archive Chatbot

Unarchive Chatbot

Error Responses

Related Resources