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 software purposes. Instead, utilize WhatsApp accounts with historical activity from real users to prevent account to be suspended. If you use fresh account they can be blocked after 2-3 new chat, they need to be warmup during days with one or two chats.
2. Keep the primary device (the phone where WhatsApp is installed) powered on and connected to the internet. This ensures that data remains synchronized with Unipile, and prevents missing messages when using GET methods or receiving real-time events.

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.