Connect

Call GET /v1/connect/telegram with profileId to generate an access code, valid for 15 minutes.

The user adds the bot to the channel or group and sends it the code. You poll until the connection completes.

The connecting accounts guide covers where this fits next to the OAuth platforms.

Access code flow

import Zernio from '@zernio/node';

const zernio = new Zernio();

const { data: access } = await zernio.connect.telegram.getTelegramConnectStatus({
  query: { profileId: '66a1f0c2a4b9d3e8f1a2b3c4' }
});

console.log(access.code, access.botUsername);

Response (200):

{
  "code": "ZRN-ABC123",
  "expiresAt": "2027-01-01T12:15:00.000Z",
  "expiresIn": 900,
  "botUsername": "ZernioScheduleBot",
  "instructions": [
    "1. Add @ZernioScheduleBot as an administrator in your channel/group",
    "2. Open a private chat with @ZernioScheduleBot",
    "3. Send: ZRN-ABC123 @yourchannel (replace @yourchannel with your channel username)",
    "4. Wait for confirmation - the connection will appear in your dashboard",
    "Tip: If your channel has no public username, forward a message from it along with the code"
  ]
}

The user then does 3 things in Telegram:

1. Adds @ZernioScheduleBot to the channel as an administrator with the Post Messages permission, or to the group as an administrator.
2. Opens a private chat with @ZernioScheduleBot.
3. Sends the code with the channel username: ZRN-ABC123 @yourchannel. For a private channel without a username, they forward any message from the channel to the bot together with the code.

Poll PATCH /v1/connect/telegram with the code until status is connected:

const { data: status } = await zernio.connect.telegram.completeTelegramConnect({
  query: { code: access.code }
});

console.log(status.status);

Response (200) while the user has not sent the code yet:

{
  "status": "pending",
  "expiresAt": "2027-01-01T12:15:00.000Z",
  "expiresIn": 542
}

Response (200) once the bot has received it:

{
  "status": "connected",
  "chatId": "-1001234567890",
  "chatTitle": "My Channel",
  "chatType": "channel",
  "account": {
    "_id": "66b2e19d8c3f5a7e9d0b1c2d",
    "platform": "telegram",
    "username": "mychannel",
    "displayName": "My Channel"
  }
}

account._id is the accountId for every call below.

A code that is not used within 15 minutes returns status: "expired". Generate a new one.

Direct connection

If the bot is already an administrator and you know the chat id, skip the code and connect directly with POST /v1/connect/telegram:

const { data: connected } = await zernio.connect.telegram.initiateTelegramConnect({
  body: {
    profileId: '66a1f0c2a4b9d3e8f1a2b3c4',
    chatId: '-1001234567890'
  }
});

console.log(connected.account._id);

Response (200):

{
  "message": "Telegram channel connected successfully",
  "account": {
    "_id": "66b2e19d8c3f5a7e9d0b1c2d",
    "platform": "telegram",
    "username": "mychannel",
    "displayName": "My Channel",
    "isActive": true,
    "chatType": "channel"
  }
}

chatId is the username with an @ prefix for a public channel (@mychannel). For a private channel or a group, it is the numeric id.

To find a numeric id:

• Channel: forward a message from the channel to @userinfobot, which replies with the id. Private channel ids start with -100.
• Group: add that bot to the group for a moment, and remove it once it has shown the group's negative id.