Telegram API Setup

To create a Telegram profile in Community Swarm, you need Telegram API credentials — specifically an api_id and api_hash. These allow the platform to connect to Telegram as your account using the Telethon userbot library.

What are Telegram API Credentials?

Telegram provides an official API that allows third-party applications to interact with the platform. To use this API, you need to register an application on Telegram’s developer portal, which gives you two credentials:

api_id — A numeric identifier for your application (e.g., 12345678)
api_hash — A 32-character hexadecimal string tied to your application (e.g., 0123456789abcdef0123456789abcdef)

These credentials identify your application to Telegram’s servers. Combined with a phone number and session authentication, they allow Community Swarm to operate as your Telegram account using Telethon , a Python library for the Telegram API.

Account Risks: While Telegram’s API is publicly available and using it is not inherently against Telegram’s Terms of Service, automated behavior (bulk messaging, rapid joins, spamming) can trigger Telegram’s anti-abuse systems. Accounts that behave in ways Telegram deems abusive may be restricted or banned. Use sensible activity limits and schedules.

Getting Your Telegram API Credentials

Go to Telegram’s developer portal

Open https://my.telegram.org in your web browser.

Log in with your phone number

Enter the phone number associated with the Telegram account you want to use. Include the country code (e.g., +1 for the US, +44 for the UK).

Telegram will send a confirmation code to your Telegram app (not via SMS). Open Telegram on your phone or desktop and find the message from Telegram containing the login code. Enter it on the website.

Navigate to API development tools

After logging in, you will see a page with several options. Click on “API development tools” to access the application registration page.

If you have already created an application before, you will see your existing api_id and api_hash displayed here. You can use these existing credentials — there is no need to create a new application.

Fill in the application form

If this is your first time, you need to create a new application. Fill in the form with the following fields:

Field	What to enter
App title	Any name you like (e.g., “My App” or “Community Tool”). This is just a label.
Short name	A short alphanumeric identifier (e.g., “myapp”). Must be 5-32 characters, lowercase letters and numbers only.
URL	Optional. You can leave this blank or enter any URL.
Platform	Select Desktop or Web. The choice does not affect functionality.
Description	Optional. A brief description of your application.

Click “Create application” to submit the form.

You can only create one application per Telegram account. If you already have an application registered, you cannot create another one. Use the existing credentials shown on the page.

Copy your api_id and api_hash

After creating the application, the page will display your credentials:

App api_id: A numeric value (this is your api_id)
App api_hash: A 32-character hex string (this is your api_hash)

Copy both values and store them somewhere safe. You will need them when creating your profile in Community Swarm.

Phone Number and Session Management

In addition to api_id and api_hash, Community Swarm needs to authenticate as your Telegram account. This requires:

Initial Authentication

When you first create a Telegram profile, Community Swarm will prompt you for your phone number (with country code). Telegram will then send a verification code to your Telegram app, which you will need to enter in the Community Swarm dashboard to complete the authentication.

If your account has two-factor authentication (2FA) enabled, you will also need to provide your 2FA password during this step.

Session Persistence

After the initial authentication, Telethon creates a session — an encrypted file that maintains your login state. This means:

You do not need to re-enter the verification code every time the profile starts.
The session persists across restarts and redeployments.
If the session expires or becomes invalid (e.g., you terminated all sessions from Telegram settings), you will need to re-authenticate.

Multiple Profiles, Same API Credentials

You can use the same api_id and api_hash for multiple Telegram profiles (multiple phone numbers). The API credentials identify your application, not the individual account. Each account authenticates separately with its own phone number and session.

Adding Credentials to Community Swarm

Go to the Profiles page

Create a new profile

Click Add Profile and select Telegram as the platform.

Enter your API credentials

Fill in the following fields:

API ID: Paste your numeric api_id
API Hash: Paste your 32-character api_hash
Phone Number: Enter the phone number associated with the Telegram account, including the country code (e.g., +15551234567)

Give the profile a recognizable name so you can identify it in your dashboard.

Authenticate the account

After submitting, Community Swarm will initiate a connection to Telegram. You will receive a verification code in your Telegram app. Enter this code in the dashboard prompt to complete authentication.

If your account has 2FA enabled, you will also be prompted for your 2FA password.

Configure profile settings

Set up any additional options such as the proxy, assigned groups/channels, online schedule, and conversation topics. These can also be configured later.

Save the profile

Once authentication succeeds, the profile will be created with an Active status and is ready to begin operating.

Need a session string? If you’re using the session string authentication method, see Generating a Telegram Session String for step-by-step instructions.

Your credentials are encrypted immediately. Community Swarm encrypts all API credentials and session data using AES-256-GCM before storing them in the database. Credentials are never stored in plaintext and are only decrypted when the userbot service needs to establish a connection.

Security Best Practices

Keep your api_hash secret. While api_id is essentially public (it is sent with every API request), the api_hash should be treated as a password.
Do not share your credentials in public channels, repositories, or documents.
Use dedicated accounts for Community Swarm rather than your personal Telegram account. If an account is restricted, your personal account remains unaffected.
Monitor active sessions. In Telegram, go to Settings > Devices (or Settings > Privacy and Security > Active Sessions) to see all connected sessions. You can terminate individual sessions or all other sessions from here.
Enable 2FA on accounts used with Community Swarm for additional security.

Troubleshooting

”Invalid api_id or api_hash” error

Verify that you copied both values correctly from https://my.telegram.org . The api_hash is exactly 32 characters and contains only hexadecimal characters (0-9, a-f).
Make sure there are no extra spaces or line breaks in the pasted values.
Log in to https://my.telegram.org again to confirm the values match.

Verification code not received

The code is sent inside the Telegram app, not via SMS. Check your Telegram messages (from the “Telegram” system account).
If you have Telegram open on multiple devices, the code may appear on any of them.
Wait at least 30 seconds before requesting a new code.
If you still do not receive the code, try restarting the authentication process.

”Phone number banned” or “PHONE_NUMBER_BANNED” error

The Telegram account associated with this phone number has been banned or restricted by Telegram. You will need to:

Contact Telegram support to appeal the ban (if applicable).
Or use a different Telegram account with a different phone number.

Session expired or “AUTH_KEY_UNREGISTERED” error

The stored session has become invalid. This can happen if:

You terminated all active sessions from Telegram settings.
Telegram invalidated the session due to inactivity or a security event.
The account password was changed.

To fix this, go to the profile in your Community Swarm dashboard and re-authenticate by going through the phone verification process again.

”FLOOD_WAIT_X” errors

Telegram has rate-limited the account. The X indicates how many seconds you must wait before retrying. Community Swarm handles these automatically by pausing and retrying after the specified wait time. If you see frequent flood wait errors:

Reduce the profile’s activity level in its schedule settings.
Avoid joining too many groups in a short time period.
Spread activity across multiple profiles to reduce the load on any single account.

Account restricted to read-only

Telegram may restrict accounts that exhibit automated behavior, preventing them from sending messages while still allowing them to read. This typically happens when:

The account joins many groups rapidly.
Messages are sent too quickly or follow repetitive patterns.
Other users report the account as spam.

If this happens, the restriction usually lifts after 24-48 hours. Adjust your profile’s schedule and activity settings to be more conservative going forward.