Chat integrations

client.chat_connections puts an existing agent behind your Slack app or Telegram bot. Blazing Agents receives the messages, keeps a session per conversation, posts the replies, and shows tool approval buttons in the chat. You send the bot credentials once; they are never returned. The agent must be configured with a provider and model, and your tenant needs an active subscription.

Examples assume client = BlazingAgents(). Every method also accepts extra_headers and timeout. On AsyncBlazingAgents, await the same method names. For the Slack and Telegram setup steps, see Slack and Telegram.

import os

connection = client.chat_connections.create(
    name="Support on Telegram",
    agent_id="ag_0123456789abcdef",
    platform="telegram",
    credentials={"bot_token": os.environ["TELEGRAM_BOT_TOKEN"]},
    enabled=False,
)
connection = client.chat_connections.enable(connection.id)
connection = client.chat_connections.check_health(connection.id)
print([(check.code, check.status) for check in connection.health.checks])

Available operations

client.chat_deliveries lists replies and approval buttons that failed or may not have arrived, across every connection: list() gets one page and iter() walks them all.

Methods

list()

Lists your chat connections.

connections = client.chat_connections.list().chat_connections

Signature: list() -> ChatConnections

Returns ChatConnections, whose chat_connections field is list[ChatConnection].

get()

Gets one connection.

connection = client.chat_connections.get("cc_0123456789abcdef")

Signature: get(chat_connection_id: str) -> ChatConnection

Returns ChatConnection.

create()

Connects a Slack app or Telegram bot to an agent.

connection = client.chat_connections.create(
    name="Support on Slack",
    agent_id="ag_0123456789abcdef",
    platform="slack",
    credentials={
        "bot_token": os.environ["SLACK_BOT_TOKEN"],
        "signing_secret": os.environ["SLACK_SIGNING_SECRET"],
    },
    configuration={"channel_ids": ["C0123456789"]},
)
print(connection.webhook_url)

Signature: create(*, name: str, agent_id: str, platform: Literal["slack", "telegram"], credentials, configuration=..., enabled=...) -> ChatConnection

credentials must have exactly the keys for the platform, and configuration only the platform's keys, or the SDK raises ValueError. channel_ids and chat_ids, up to 20 each, pick where health checks look; they do not restrict who can use the bot. Set business_mode only for a Telegram Business bot.

enabled defaults to True. Pass False to finish setup before messages arrive. For Slack, paste the returned webhook_url into your Slack app. For Telegram, Blazing Agents registers the webhook for you when the connection is enabled. To use a different agent or bot, create a new connection. If creation times out, list your connections before retrying, since the first attempt may have succeeded.

update()

Changes a connection's name or configuration.

connection = client.chat_connections.update(
    connection.id,
    configuration={"channel_ids": ["C0123456789", "C9876543210"]},
)

Signature: update(chat_connection_id: str, *, name=..., configuration=...) -> ChatConnection

Pass at least one parameter; passing neither, or unknown configuration keys, raises ValueError before any request.

rotate_credentials()

Replaces the bot credentials for the same bot or Slack installation. Existing conversations keep their sessions.

connection = client.chat_connections.rotate_credentials(
    connection.id,
    platform="telegram",
    credentials={"bot_token": os.environ["TELEGRAM_BOT_TOKEN"]},
)

Signature: rotate_credentials(chat_connection_id: str, *, platform: Literal["slack", "telegram"], credentials) -> ChatConnection

Send the complete credential set for the platform, as in create().

check_health()

Re-runs the connection's health checks and returns the refreshed result.

connection = client.chat_connections.check_health(connection.id)
for check in connection.health.checks:
    print(check.code, check.status, check.subject)

Signature: check_health(chat_connection_id: str) -> ChatConnection

Each check is "pass", "fail", or "unknown". "unknown" means the check could not tell; verify that setting yourself. A valid token alone does not prove messages arrive: require the webhook_url check to pass.

enable()

Starts accepting messages and approval clicks.

connection = client.chat_connections.enable(connection.id)

Signature: enable(chat_connection_id: str) -> ChatConnection

Messages sent while the connection was disabled are not replayed. For Telegram, enabling registers the webhook: it raises chat_webhook_conflict when the bot already points to another webhook and chat_webhook_registration_failed for other registration failures.

disable()

Stops accepting new messages and approval clicks. Work already started can finish.

connection = client.chat_connections.disable(connection.id)

Signature: disable(chat_connection_id: str) -> ChatConnection

delete()

Disconnects the bot. Sessions from its conversations are kept.

client.chat_connections.delete(connection.id)

Signature: delete(chat_connection_id: str) -> None

Blazing Agents clears the bot's Telegram webhook if it still points to this connection. Uninstalling a Slack app is up to you.

chat_deliveries.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.

from datetime import datetime, timedelta, timezone

since = (datetime.now(timezone.utc) - timedelta(hours=24)).isoformat()
page = client.chat_deliveries.list(since=since)
for delivery in page.data:
    print(delivery.platform, delivery.connection_id, delivery.status, delivery.diagnostic)

Signature: list(*, status=..., since=..., cursor=..., limit=...) -> ChatDeliveriesPage

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 next_cursor back as cursor.

Returns ChatDeliveriesPage with data: list[TenantChatDelivery] and next_cursor: str | None. Raises validation_failed or invalid_cursor.

chat_deliveries.iter()

Iterates every matching delivery, fetching pages as you go.

for delivery in client.chat_deliveries.iter(since=since):
    print(delivery.platform, delivery.connection_id, delivery.status, delivery.diagnostic)

Signature: iter(*, status=..., since=..., cursor=..., limit=...) -> Iterator[TenantChatDelivery]

Takes the same parameters as chat_deliveries.list(). No request is sent until you start iterating. On the async client, use async for directly on iter(...); do not await it.

Response models

ChatConnection

TenantChatDelivery

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

Next

• Slack and Telegram setup
• Tool approvals
• Sessions