---
title: "Connect an external AI assistant"
locale: en
url: https://tlg.builera.app/en/docs/integrations/ai-connections
verified: 2026-10-24
app_version: "2.0"
---

# Connect an external AI assistant

Grant limited access to an external assistant through MCP or REST v2 and track the connection's commands.


You connect an external AI assistant to Telegram-Auto and limit what it can do. Telegram-Auto has no built-in AI. Every assistant command passes through the same safety gate as actions on the web.

## Who can do this

An Owner or Manager can create and manage connections. A connection's effective permissions are the intersection of its role, job categories and granted accounts. A connection cannot have more access than its creator.

## Before you start

- An assistant that supports MCP, or a program that calls REST.
- A list of accounts and tasks the assistant may handle.
- A secret store if you use an API key.

Keep reporting-only connections separate from connections with permission to send messages.

## Where to start

Open **Settings → AI connections**.

![External assistant connection management screen](https://tlg.builera.app/docs-media/en/settings-ai.webp "AI connections")

## Steps

1. Choose **Create connection**.
2. Enter a **Name** to identify the assistant.
3. Choose a **Connection method** that suits your program.
4. Choose a **Role** no higher than your own permissions.
5. Choose a suitable **MCP tool set**.
6. Choose **Allowed job categories** using the minimum access needed.
7. Choose the **Telegram accounts** the assistant may access.
8. Set **Language for AI**. This changes the language of descriptions, errors and reasons. It does not change operation codes, event codes or data.
9. Check **Dangerous actions**. Keep the **Ask for confirmation** policy unless you have a reason to change it.
10. Choose **Create**.

![Form for choosing an AI connection's permissions and accounts](https://tlg.builera.app/docs-media/en/ai-connection-create.webp "Connection scope")

If you use an API key, copy the `tga_…` key as soon as it appears. It is only shown once. Do not paste it into conversations, screenshots or logs.

### Connect with OAuth

In your MCP client, add this address:

```text
https://tlg.builera.app/mcp
```

Sign in to Telegram-Auto, review the consent screen and choose the appropriate connection. Do not approve if the workspace or permission scope is wrong.

### Connect with an API key

REST v2 uses this base URL:

```text
https://tlg.builera.app/api/public/v2
```

MCP with an API key uses:

```text
https://tlg.builera.app/api/public/mcp
```

Both use this header:

```text
Authorization: Bearer $TELEGRAM_AUTO_API_KEY
```

### Understand tool sets

The profiles are `realtime`, `setup`, `prospecting`, `reports`, `admin` and `full`. Each profile exposes up to **35 tools**, including helper and discovery tools.

An operation is not necessarily forbidden just because it has no dedicated tool name. The assistant uses `tools_search`, reads the contract with `tools_describe`, then calls `tools_run`. Permission checks remain the same.

## Result

The connection has its own identity, account scope and command history. When handling customers, the assistant must claim the conversation with `conversations.claim`, must not take someone else's lock and must release the lock when finished.

## Check

Open **Recent actions** to review commands, statuses and errors. Have the assistant call `whoami` before working.

Use **Edit** to narrow permissions. **Stop now** rejects new commands, cancels the connection's queued or held jobs and releases conversations. Sent messages are not recalled.

> [!WARNING]
> Deleting a connection immediately removes the assistant's access and cancels queued jobs. Sent messages are not recalled.

Only choose **Delete** after checking that you have the right connection.

## If something goes wrong

Check the connection's status, role, scopes, accounts and expiration. For `confirmation_required`, the assistant must ask the person. It must not decide to confirm on its own.

## Do it with the API or MCP

- [View connections](https://tlg.builera.app/en/docs/reference/rest/connections.list).
- [Edit a connection](https://tlg.builera.app/en/docs/reference/rest/connections.update).
- [Stop a connection](https://tlg.builera.app/en/docs/reference/rest/connections.stop).
- MCP: use `tools_run` with the corresponding code after reading `tools_describe`.

See also [sending safely](https://tlg.builera.app/en/docs/agent-playbooks/send-safely) and [action confirmations](https://tlg.builera.app/en/docs/concepts/confirmations).