Skip to main content
Integrations allow Support Bot to automatically pull incident data from external systems like ServiceNow, Jira, or other ITSM platforms. This keeps your knowledge base up-to-date without manual data entry.

​
Supported Integration Types

Support Bot supports various authentication methods for connecting to external systems:

Basic Auth

Username and password authentication for ServiceNow and similar platforms.

API Token

Token-based authentication for platforms like Jira or custom APIs.

OAuth 2.0

Modern OAuth2 flow for secure, delegated access.

​
Adding an Integration

1

Navigate to Integrations

From the sidebar, go to Settings > Integrations.
2

Click Add

Click the Add button to open the integration creation dialog.
3

Enter Service Name

Provide a descriptive name (e.g., “Production ServiceNow”, “Jira Cloud”).
4

Select Authentication Type

Choose the authentication method your external system uses:
Required fields:
  • URL - Base URL of your ServiceNow instance (e.g., https://company.service-now.com)
  • Username - Your ServiceNow username
  • Password - Your ServiceNow password
Credentials are stored encrypted. Never share them.
5

Save

Click Save to create the integration.

​
Managing Integrations

​
View All Integrations

The integrations page displays all configured connections with:
  • Service name and authentication type
  • Status (enabled/disabled)
  • Last sync timestamp
  • Sync status (success/error/never)
  • Error details (if last sync failed)

​
Edit Integration

1

Expand Integration Card

Click anywhere on the integration card to expand it.
2

Click Edit

Click the Edit button to enable editing mode.
3

Update Settings

Modify any configuration fields:
  • Service name
  • Credentials (username/password/token)
  • URL endpoints
  • Enable/disable toggle
4

Save Changes

Click Save to apply your updates.
Credentials are masked in the UI. To update a password or token, you must enter the new value explicitly.

​
Enable/Disable Integration

Toggle the Enabled switch on any integration card to activate or deactivate it:
  • Enabled - Integration will sync on schedule
  • Disabled - No automatic syncing; manual sync still possible

​
Delete Integration

Deleting an integration is permanent. The connection configuration will be removed, but already-synced data remains in your knowledge base.
1

Expand Integration

Click the integration card to expand it.
2

Click Delete

Click the Delete button.
3

Confirm

Confirm the deletion in the dialog that appears.

​
Syncing Data

​
Manual Sync

Trigger an immediate sync to pull the latest data from your external system:
1

Expand Integration

Click the integration card to expand it.
2

Click Sync

Click the Sync Now button.
3

Monitor Progress

A progress indicator shows:
  • Current batch being processed
  • Total batches
  • Number of incidents processed
The sync runs in real-time with live progress updates.
4

Review Results

When complete, the integration card updates with:
  • New “Last sync” timestamp
  • Sync status (success/error)
  • Statistics (incidents added, total incidents)

​
Automatic Sync

Automatic scheduled syncing will be available in a future release. Currently, all syncs are manual.

​
Sync Process

When a sync runs:
  1. Fetch - Support Bot queries the external system for new or updated incidents
  2. Normalize - Incident data is transformed to Support Bot’s schema
  3. Batch - Data is processed in batches (5 incidents per batch)
  4. Ingest - Incidents are embedded and added to the vector database
  5. Version - A new dataset version is created for audit purposes
Only incidents modified since the last sync are fetched (incremental sync).

​
ServiceNow Integration

​
Configuration

For ServiceNow specifically:
1

Get ServiceNow URL

Your instance URL format: https://[instance-name].service-now.com
2

Create Service Account

In ServiceNow, create a dedicated service account for Support Bot with:
  • Read access to incident table (incident)
  • Read access to sys_user table (for user info)
  • No delete or modify permissions (read-only)
3

Configure Integration

In Support Bot:
  • Service Name: “ServiceNow Production”
  • Auth Type: Basic Auth
  • URL: https://[instance-name].service-now.com
  • Username: Service account username
  • Password: Service account password
4

Test

Save and run a manual sync to verify the connection works.

​
Synced Fields

Support Bot syncs the following ServiceNow incident fields:
  • Number - Incident identifier (e.g., INC0010001)
  • Short Description - Brief summary
  • Description - Full incident details
  • State - Current status
  • Priority - Incident priority
  • Category - Incident category
  • Subcategory - More specific categorization
  • Assigned To - Person currently handling the incident
  • Resolved By - Person who resolved it
  • Resolution Notes - How it was resolved
  • Timestamps - Created, updated, resolved dates

​
Filtering

Currently, all incidents are synced. Custom filtering (by priority, category, date range) will be available in a future release.

​
Sync Status and Errors

​
Status Indicators

​
Never synced
gray
Integration has been created but never run
​
Success
green
Last sync completed without errors
​
Error
red
Last sync failed. Check error message for details.

​
Common Errors

Cause: Invalid credentials or expired passwordSolution:
  • Verify username and password are correct
  • Check if the service account is locked
  • Update credentials and try again
Cause: ServiceNow instance unreachable or network issuesSolution:
  • Verify the URL is correct
  • Check firewall rules allow outbound HTTPS
  • Ensure the ServiceNow instance is online
Cause: Service account lacks required read permissionsSolution:
  • Grant the account incident table read access
  • Grant sys_user table read access
  • Test with an admin account to isolate permission issues
Cause: Too many API requests in a short timeSolution:
  • Wait a few minutes before retrying
  • Contact your ServiceNow admin about rate limits
  • Reduce sync frequency if applicable

​
Viewing Error Details

When a sync fails:
  1. The integration card shows a red Error status
  2. Expand the card to see the full error message
  3. The “Last sync” timestamp shows when the error occurred

​
Data Versioning

Each sync creates a new dataset version for audit and rollback purposes:
  • Version ID - Unique identifier for this sync
  • Timestamp - When the sync occurred
  • Source - Integration name (e.g., “ServiceNow”)
  • Stats - Number of incidents added/updated
  • Notes - Auto-generated description
Versions can be viewed in Settings > Knowledge Base > Version History.

​
Required Permissions

ActionPermission Required
View integrationsintegration.view
Add integrationintegration.create
Edit integrationintegration.edit
Delete integrationintegration.delete
Trigger syncintegration.sync

​
Best Practices

Use Service Accounts

Create dedicated service accounts in external systems rather than using personal credentials.

Test in Staging

Set up a staging integration first to verify configuration before connecting to production.

Monitor Sync Status

Regularly check integration health to catch sync failures early.

Read-Only Access

Grant integrations only read permissions in external systems for security.

​
Troubleshooting

​
Sync Completes But No Data

  1. Check if there are new incidents since the last sync (incremental sync only fetches changes)
  2. Verify the service account has access to the incident table
  3. Check ServiceNow instance logs for API request errors

​
Slow Sync Performance

  1. ServiceNow may be rate-limiting requests
  2. Large incident volumes take longer (5 incidents per batch)
  3. Network latency between Support Bot and ServiceNow instance

​
Credentials Keep Failing

  1. Verify the service account is active in ServiceNow
  2. Check if the account requires MFA (not supported - use app password)
  3. Ensure password hasn’t expired
  4. Test login directly in ServiceNow UI with same credentials

​
API Reference

For programmatic integration management, see the Integrations API documentation.

Build docs developers (and LLMs) love

Get started for freeTalk to us