How does it work ?

To link a Telegram account with Unipile, users must use the Devices feature provided by Telegram.

If the Unipile device is removed from the list of linked devices in Telegram, the account will transition to the disconnected state (🟡 Requires Authentication). This means the user must re-authenticate to restore full functionality.

Recommendations

1. Avoid using brand-new accounts exclusively for automation. Use accounts with regular activity and gradually increase messaging activity to reduce the risk of restrictions.
2. Keep the Telegram session authorized and monitor its account status so that it can be re-authenticated promptly if it is disconnected.

Link with Hosted Auth

To link Telegram accounts using Hosted Authentication, follow the Authenticate with Hosted Auth guide and specify TELEGRAM as the providers when calling Create Auth Link.

Server code

// ...

const response = await hostedAuthApi.createAuthLink({
  body: {
    providers: "TELEGRAM",
    expires_on: dayjs().add(10, "minutes").toISOString(),
    redirect_uri: "https://myapp.com/link-account/callback",
  },
});

// ...

# ...

response = hosted_auth_api.create_auth_link(
    {
        "providers": "TELEGRAM",
        "expires_on": "2025-05-05T00:00:00.000Z",
        "redirect_uri": "https://myapp.com/link-account/callback",
    }
)

# ...

curl --request POST \
     --url https://api.unipile.com/v2/auth/link \
     --header 'X-API-KEY: api-key' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "providers": "TELEGRAM",
  "redirect_uri": "https://myapp.com/link-account/callback",
  "expires_on": "2025-05-05T00:00:00.000Z"
}
'

Link with Custom Auth

To build a custom authentication wizard for Telegram Accounts, follow the QR Code Flow guide.