Chat integrations

client.chatConnections puts an agent behind a Slack or Telegram bot. Blazing Agents receives the bot's messages, keeps a session for each direct message, thread, or forum topic, and posts the agent's replies and tool approval buttons. To set up the bot on each platform, read Chat integrations.

const connection = await client.chatConnections.create({
  name: "Support on Telegram",
  agentId,
  platform: "telegram",
  enabled: false,
  credentials: { botToken: process.env.TELEGRAM_BOT_TOKEN! },
});

await client.chatConnections.enable({ chatConnectionId: connection.id });
const { health } = await client.chatConnections.checkHealth({ chatConnectionId: connection.id });
console.log(health.checks);

Every method takes one input object and accepts an optional abortSignal. Bot credentials are never returned; responses show at most four characters in credentialFragment.

Available operations

client.chatDeliveries has one method, list(), which lists replies and approval buttons that failed or may not have arrived, across every connection.

Methods

create()

Connects an agent to a Slack or Telegram bot.

Signature: create(input: CreateChatConnectionBody & ResourceRequestOptions): Promise<ChatConnection>

const connection = await client.chatConnections.create({
  name: "Support on Slack",
  agentId,
  platform: "slack",
  credentials: {
    botToken: process.env.SLACK_BOT_TOKEN!,
    signingSecret: process.env.SLACK_SIGNING_SECRET!,
  },
  configuration: { channelIds: ["C0123456789"] },
});
console.log(connection.webhookUrl);

channelIds and chatIds list up to 20 conversations that health checks test against. They do not limit where the bot answers. Set businessMode: true for a Telegram Business bot.

For Telegram, Blazing Agents registers the bot's webhook when the connection is enabled. For Slack, paste the returned webhookUrl into your Slack app's settings. Pass enabled: false to finish setup before messages arrive. To use another agent or bot, create a new connection.

If create() times out, list your connections before you retry, so you do not create two. Returns ChatConnection.

list()

Lists your connections.

Signature: list(input?: ResourceRequestOptions): Promise<ChatConnectionsResponse>

const { chatConnections } = await client.chatConnections.list();

Returns { chatConnections: ChatConnection[] }.

get()

Reads one connection.

Signature: get(input: { chatConnectionId: string } & ResourceRequestOptions): Promise<ChatConnection>

const connection = await client.chatConnections.get({ chatConnectionId });

Returns ChatConnection.

update()

Changes the name, the test destinations, or Telegram Business mode.

Signature: update(input: UpdateChatConnectionBody & { chatConnectionId: string } & ResourceRequestOptions): Promise<ChatConnection>

const connection = await client.chatConnections.update({
  chatConnectionId,
  configuration: { chatIds: ["-1001234567890"] },
});

Pass name, configuration, or both. configuration takes any of channelIds, chatIds, and businessMode, and changes only the keys you send. Returns ChatConnection.

rotateCredentials()

Replaces the credentials for the same bot. Its sessions stay attached.

Signature: rotateCredentials(input: RotateChatConnectionBody & { chatConnectionId: string } & ResourceRequestOptions): Promise<ChatConnection>

const connection = await client.chatConnections.rotateCredentials({
  chatConnectionId,
  platform: "slack",
  botToken: process.env.SLACK_BOT_TOKEN!,
  signingSecret: process.env.SLACK_SIGNING_SECRET!,
});

Send the full set for the platform: botToken and signingSecret for Slack, botToken for Telegram. Returns ChatConnection.

checkHealth()

Checks the token, bot identity, and webhook now, and returns the connection with fresh results.

Signature: checkHealth(input: { chatConnectionId: string } & ResourceRequestOptions): Promise<ChatConnection>

const { health } = await client.chatConnections.checkHealth({ chatConnectionId });
const webhook = health.checks.find(({ code }) => code === "webhook_url");
if (webhook?.status !== "pass") console.warn("Webhook not confirmed", webhook);

Each check is pass, fail, or unknown; confirm unknown ones by hand. A valid token alone does not prove messages arrive, so require the webhook_url check to pass and send the bot a test message. Returns ChatConnection.

enable()

Starts handling the bot's messages.

Signature: enable(input: { chatConnectionId: string } & ResourceRequestOptions): Promise<ChatConnection>

await client.chatConnections.enable({ chatConnectionId });

Messages sent while the connection was disabled are not replayed. Returns ChatConnection with enabled: true.

disable()

Stops handling new messages and approval clicks. Work already running may finish, and the connection keeps its settings.

Signature: disable(input: { chatConnectionId: string } & ResourceRequestOptions): Promise<ChatConnection>

await client.chatConnections.disable({ chatConnectionId });

Returns ChatConnection with enabled: false.

delete()

Disconnects the bot from Blazing Agents. Its sessions stay readable.

Signature: delete(input: { chatConnectionId: string } & ResourceRequestOptions): Promise<void>

await client.chatConnections.delete({ chatConnectionId });

A Telegram bot's webhook is cleared for you. Uninstall a Slack app yourself.

chatDeliveries.list()

Lists the replies and approval buttons that failed or may not have arrived, across every connection, newest first. Use it for a status view that shows which messages need attention.

Signature: list(input?: ChatDeliveriesListOptions): Promise<ChatDeliveriesResponse>

const since = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString();
const page = await client.chatDeliveries.list({ since });
for (const delivery of page.data) {
  console.log(delivery.platform, delivery.connectionId, delivery.status, delivery.diagnostic);
}

failed means the platform did not accept the message, and ambiguous means it may have been sent. The feed never lists pending or confirmed deliveries; list one connection's deliveries for those, and passing any other status fails with validation_failed. Keep the same filters when you pass nextCursor back as cursor.

Returns ChatDeliveriesResponse. Errors: validation_failed, invalid_cursor.

Response types

ChatConnection

Each entry in health.checks is { code: string; status: "pass" | "fail" | "unknown"; subject?: string }.

ChatDeliveriesResponse

{ data: TenantChatDelivery[]; nextCursor: string | null }. nextCursor is null on the last page. Each TenantChatDelivery has:

It also has credentialVersion, representation, and receipts. The package exports ChatDelivery, TenantChatDelivery, ChatDeliveryStatus, and ChatDeliveryListStatus.

Next

• Chat integrations
• Client generation methods