What causes "Livechat secret token is not configured" in RocketChat/Rocket.Chat?

Set the Livechat secret token in the workspace settings (Administration -> Omnichannel/Livechat) and retry the test endpoint.

RocketChat/Rocket.Chat · error · Error

Livechat secret token is not configured

Error message

Livechat secret token is not configured

What it means

Both trigger external-service endpoints read the Livechat_secret_token setting and refuse to run when it is empty, because the token is sent as the X-RocketChat-Livechat-Token header so the external service can authenticate the call. The test route (livechat/triggers/external-service/test, rate-limited to 15/min) throws before any HTTP request is made; the call route (livechat/triggers/:_id/external-service/call) has the same check after resolving the trigger.

Source

Thrown at apps/meteor/ee/server/api/v1/omnichannel/triggers.ts:26

import { settings } from '../../../../../server/settings';

API.v1.addRoute(
	'livechat/triggers/external-service/test',
	{
		authRequired: true,
		permissionsRequired: ['view-livechat-manager'],
		validateParams: isLivechatTriggerWebhookTestParams,
		rateLimiterOptions: { numRequestsAllowed: 15, intervalTimeInMS: 60000 },
		license: ['livechat-enterprise'],
	},
	{
		async post() {
			const { webhookUrl, timeout, fallbackMessage, extraData: clientParams } = this.bodyParams;

			const token = settings.get<string>('Livechat_secret_token');

			if (!token) {
				throw new Error('Livechat secret token is not configured');
			}

			const body = {
				metadata: clientParams,
				visitorToken: '1234567890',
			};

			const headers = {
				'Accept': 'application/json',
				'Content-Type': 'application/json',
				'X-RocketChat-Livechat-Token': token,
			};

			const response = await callTriggerExternalService({
				url: webhookUrl,
				timeout,
				fallbackMessage,
				body,

View on GitHub (pinned to b2c16d5842)

Solutions

Set the Livechat secret token in the workspace settings (Administration -> Omnichannel/Livechat) and retry the test endpoint.
If the setting is not exposed in the UI, set it via POST /api/v1/settings/Livechat_secret_token with an admin account.
After configuring, verify the external service receives the X-RocketChat-Livechat-Token header.

Example fix

// before
await api.post('/v1/livechat/triggers/external-service/test', { webhookUrl });
// -> 'Livechat secret token is not configured'

// after
await api.post('/v1/settings/Livechat_secret_token', { value: process.env.LIVECHAT_SECRET_TOKEN });
await api.post('/v1/livechat/triggers/external-service/test', { webhookUrl });

Defensive patterns

Strategy: try-catch

Try / catch

try {
  await api.post('/v1/livechat/triggers/external-service/test', { webhookUrl });
} catch (e) {
  if (e?.response?.data?.error === 'Livechat secret token is not configured') {
    // set the Livechat_secret_token setting, then retry the test
  } else throw e;
}

Prevention

Configure the Livechat secret token before developing against external-service triggers.
Include the token setting in environment provisioning scripts and clone checklists.
If the token is rotated, update the external service's verification list in the same change.

When it happens

Trigger: POST /api/v1/livechat/triggers/external-service/test (or the call route) on a workspace where the Livechat secret token setting was never set or was cleared.

Common situations: Fresh installs before Omnichannel was fully configured; tokens cleared or rotated during security audits; cloned test environments missing private settings.

Related errors

AI-assisted analysis of RocketChat/Rocket.Chat@b2c16d5842 (2026-08-18). Data as JSON: /api/errors/68cecda7e668ff55. Report an issue: GitHub.