Dashboard
Accounts
| Account | Status ?Active = connected and ready. Pending = waiting for verification. Disabled = turned off. Banned = restricted by Telegram | Proxy ?SOCKS5 proxy required for each account. Protects your IP and prevents Telegram bans | API ID | Added | |
|---|---|---|---|---|---|
|
|
|
||||
|
No accounts yet. Add your first Telegram or WhatsApp account to get started.
|
|||||
All registered users and their Telegram accounts
Contacts
| Name | Username ?Telegram @username | Phone | Company | Position | Country | City | Lists | |||
|---|---|---|---|---|---|---|---|---|---|---|
|
|
||||||||||
|
No contacts found. Import contacts or add them manually.
|
||||||||||
No lists yet. Create one to organize your contacts.
Contacts and lists per user
Get Contacts
Get Contacts coming soon
Get contacts in companies, industries, and countries through our integrations with key data providers — coming in a future update.
PlannedMarketplace
Marketplace coming soon
Purchase ready-to-use Telegram and WhatsApp accounts, SOCKS5 proxies, and other resources for your outreach needs — all in one place.
PlannedCampaigns
| RECIPIENT | STATUS | MESSAGE | CREATED | SENT | ERROR |
|---|---|---|---|---|---|
|
|
|||||
| No campaign messages found | |||||
| Recipient | Status | Step | Replied | Last Sent | Error |
|---|---|---|---|---|---|
Messaging
Choose recipient
For TG: @username or phone. For WhatsApp: phone with country code (e.g. +12025551234)
Compose message
Write the message text. You can optionally schedule it for later
Review & send
Confirm the details before sending
| RECIPIENT | STATUS | MESSAGE | CREATED | SENT | ERROR |
|---|---|---|---|---|---|
|
|
|||||
| No messages found | |||||
Documentation
Getting Started
Contactd is a multi-platform outreach tool that lets you send personalized messages at scale via Telegram and WhatsApp.
2. Import or create your contact list
3. Create a campaign with your message
4. Launch and monitor results on the Dashboard
Add Telegram Account
Before you can send messages, you need to connect at least one Telegram account. Each account requires API credentials from Telegram.
Step 1 — Get Telegram API credentials
- Go to my.telegram.org in your browser
- Log in with your Telegram phone number — you will receive a confirmation code in the Telegram app
- Click API development tools
- Fill out the form:
- App title — any name (e.g. "My App")
- Short name — any short name (e.g. "myapp")
- Platform — select Desktop
- Click Create application
- You will see your api_id (a number) and api_hash (a long string). Save both — you'll need them in the next step.
Step 2 — Add the account in Contactd
- Navigate to Accounts page and click Add Account
- Step 1: Enter a display name for the account
- Step 2: Enter your phone number (with country code), api_id, api_hash, and optionally your TG username
- Step 3: Configure a SOCKS5 proxy (required) — enter host, port, username and password, then test the connection
- Click Create — the account will appear in the table with status "pending"
Step 3 — Verify the account
You have two options to verify:
Once verified, the account status changes to active and it's ready to send messages.
Step 4 — Cloud Password (2FA)
If your Telegram account has Two-Step Verification enabled, you will be prompted to enter your cloud password after the verification code. If 2FA is not enabled yet, we strongly recommend turning it on:
- Open Telegram on your phone
- Go to Settings → Privacy and Security → Two-Step Verification
- Set a strong password and save the recovery email
Add WhatsApp Account
WhatsApp accounts connect via QR code — no API credentials needed. Your phone must have WhatsApp installed and active.
Step 1 — Create the account
- Go to Accounts and click Add Account
- Select platform: WhatsApp
- Enter a display name and your phone number (with country code, e.g. +7912...)
- Configure a SOCKS5 proxy (required) — enter host, port, username and password, then test the connection
- Click Create
Step 2 — Scan QR code
- After creation, a QR code will appear on screen
- Open WhatsApp on your phone
- Go to Settings → Linked Devices → Link a Device
- Scan the QR code displayed in Contactd
- The account will automatically switch to active
Troubleshooting
Authentication can drop unexpectedly
Common reasons authentication drops:
- Phone went offline — if your phone loses internet for more than ~14 days, all linked devices are automatically disconnected
- WhatsApp app update — major updates on your phone can reset linked device sessions
- Server-side session expiry — WhatsApp periodically rotates encryption keys, which can invalidate existing sessions
- Too many linked devices — WhatsApp allows up to 4 linked devices. Adding a 5th disconnects the oldest
- Account flagged — if WhatsApp detects suspicious activity, it may force-disconnect all linked devices
- Platform restarts — server deployments or container restarts require sessions to re-authenticate. Most will auto-reconnect, but some may need a new QR scan
- Check account status on the Accounts page — look for disconnected or error status
- Click Reconnect — if the session is still valid, it will auto-reconnect without a QR scan
- If reconnect fails, you'll see a new QR code — scan it from your phone to re-link
- Running campaigns will automatically resume once the account is back to active
Managing Contacts
Contacts are the people you want to reach. You can add them manually or import in bulk.
Importing contacts
- Go to Contacts → click Import
- Upload a CSV file with columns:
username, first_name, last_name, phone(at minimum) - Select or create a Contact List to organize them
- Click Import — contacts will be added and deduplicated automatically
Contact Lists
Lists help you organize contacts into groups. When creating a campaign, you select one or more lists as recipients. You can manage lists from the Lists tab on the Contacts page.
Campaigns
Campaigns let you send messages to an entire contact list with just a few clicks. You can use Telegram accounts, WhatsApp accounts, or both in a single campaign — messages will be distributed across all selected accounts.
Creating a campaign
- Go to Campaigns and click New Campaign
- Give your campaign a name
- Select the contact lists you want to target
- Select which accounts should be used for sending — you can select multiple accounts to distribute the load
- Write your message. Use personalization variables like
$first_name(see Template Variables) - Optionally add follow-up steps (sent after a delay if the recipient doesn't reply)
- Optionally enable AI Auto-Reply — the AI will automatically respond to incoming messages from recipients (see AI Auto-Reply section below)
- Click Create Campaign, then start it from the campaign detail page
Campaign statuses
Editing a running campaign
You can edit campaigns even while they are running — no need to pause or restart. Changes apply to all future messages immediately.
- Message text — edit any step's text, and new recipients will receive the updated version
- AI settings — change the system prompt or model at any time
- Accounts — add or remove sending accounts to adjust load distribution
Tracking replies
Open a campaign and switch to the Replies tab to see all incoming replies. You can also see analytics like delivery rate, reply rate, and per-step performance.
Template Variables
Personalize your campaign messages using template variables. Each variable is replaced with the corresponding field from the recipient's contact data.
Available variables
| Variable | Description | Example output |
|---|---|---|
$first_name | Contact's first name | Alex |
$last_name | Contact's last name | Smith |
$username | Telegram @username | alexsmith |
$company | Company name | Acme Inc |
$position | Job title | CTO |
$city | City | London |
$country | Country | UK |
$phone | Phone number | +44123456789 |
$email | Email address | alex@acme.com |
Fallback values
If a contact doesn't have a field filled in, the variable will be empty. Use the $variable|fallback syntax to provide a default value:
In this example, if the contact has no first name, the message will say "Hi there" instead of "Hi ".
Tips
- Always use fallbacks for optional fields like
$companyand$position - Click the variable buttons in the message composer to insert them automatically
- Variables work in all message steps (initial + follow-ups)
- You can add up to 3 follow-up messages per campaign
Direct Messaging
The Messaging page lets you send a single message to a specific recipient without creating a campaign. Use it to test your accounts before launching a campaign.
Send Message wizard
- Step 1: Enter the recipient and select which account to send from. For Telegram: phone number, @username, or chat_id. For WhatsApp: phone number in international format (e.g. +79121234567)
- Step 2: Write your message. Optionally schedule it for later
- Step 3: Review and send
History
The History tab shows all messages sent from the Messaging page. Campaign messages are shown separately under Campaigns → Messages.
Rate Limits
Both Telegram and WhatsApp enforce rate limits on messaging. Contactd automatically manages sending speed per platform to keep your accounts safe.
You can configure rate limits per platform in Settings → Rate Limits. Telegram and WhatsApp have separate rate settings.
AI Auto-Reply
Campaigns can optionally use AI to automatically reply to incoming messages from recipients. All AI replies are visible in the campaign's Replies tab.
Setting up AI Provider
First, configure your AI provider in Settings → AI Provider. Contactd supports two providers:
sk-...).
sk-ant-...).
Select your provider, enter your API key, choose a model, and click Save.
Enabling AI in a campaign
- When creating a campaign, enable AI Auto-Reply
- Write a system prompt that describes how the AI should respond
- Optionally provide an example reply for better quality
Best Practices
Follow these recommendations to keep your accounts safe and maximize delivery rates across both platforms.
Telegram
- Warm up new accounts — start with 5–10 messages/hour for the first week, then gradually increase to 20/hour
- Use dedicated proxies — each account should have its own SOCKS5 proxy. Shared proxies raise ban risk
- Personalize messages — use template variables ($first_name, $company). Identical messages trigger spam detection
- Enable quiet hours — avoid sending at night (22:00–08:00 in the recipient's timezone)
- Distribute across accounts — assign multiple accounts to a campaign to split the load
- Enable jitter — random delays between messages (10–30 sec) make sending patterns look natural
- Monitor FloodWait — if you see frequent FloodWait warnings on the Dashboard, reduce your rate
- Don't exceed 10 msg/hour — going higher significantly increases FloodWait and temporary bans
- Warm up is critical — start with 3–5 messages/hour for new numbers. Increase by 2–3 per week. Never jump to high volumes immediately
- Avoid links in the first message — WhatsApp flags links in initial outreach. Send a text-only first message, share links in follow-ups after a reply
- Keep it conversational — WhatsApp users expect natural, personal messages. Short messages (2–3 sentences) work best
- Don't exceed 10 msg/hour — WhatsApp rate limits are stricter and bans can be permanent
- Use aged numbers — newly registered WhatsApp numbers are flagged more aggressively. Accounts with 2+ weeks of normal usage are safer
- Use dedicated proxies — same as Telegram, each WhatsApp account should have its own proxy for best results
- Monitor for disconnections — check account status regularly. If an account shows "disconnected" or "encryption error", reconnect it before continuing campaigns
- Keep your phone online — WhatsApp Web requires the phone to have an active internet connection. If the phone goes offline for too long, the session disconnects
General tips
- Always use fallback values —
$first_name|thereprevents sending "Hi " when a name is missing - Test before launching — send a test message from the Messaging page to your own number before running a campaign
- Use follow-up steps wisely — space follow-ups at least 24 hours apart. Don't send more than 2–3 follow-ups total
- Clean your contact lists — remove bounced or invalid contacts to improve delivery rates
Settings
The Settings page lets you manage your profile, configure rate limits, set up AI providers, and control sending behavior.
Profile
Update your display name, email, and password. Changes are saved immediately when you click Save Profile.
Rate Limits
Control how fast messages are sent per account. The settings include:
- Messages per Hour — maximum messages sent per hour per account. Recommended maximum: 10 messages per hour
- Jitter (Random Delay) — adds a random delay between messages to make sending patterns look more natural. Set min and max delay in seconds
Quiet Hours
Pause all sending during specific hours to respect recipients' time. When enabled, messages are queued and sent automatically after quiet hours end.
- Start / End Hour — define the window (0–23) when no messages are sent
- Timezone — select the timezone for your quiet hours schedule
AI Provider
Configure the AI model used for campaign auto-replies. See the AI Auto-Reply section for full setup instructions and available models.
Need help? Contact your administrator or reach out to support.
Settings
Root key from .env — for admin onboarding
Service keys for clients. Each key = one tenant workspace.
| Name | Key | Role | Plan | Messages | Expires | Status | Created | |
|---|---|---|---|---|---|---|---|---|
| / / ∞ | — | Active Expired Inactive | ||||||
| No service keys yet | ||||||||
Your sending speed — capped by plan
Global defaults for all tenants
Configure your AI API key. Auto-reply is enabled per campaign.
Service plans assigned to service keys
Telegram & WhatsApp accounts across all users
| Owner | Platform | Account | Status | Proxy | Added |
|---|---|---|---|---|---|
|
@
|
None |
All message records across all clients
| Client | Recipient | Message | Status | Account | Date | |
|---|---|---|---|---|---|---|
|
|
||||||
| Click Load to fetch messages | ||||||
Permanently failed messages
| Message ID | Reason | |
|---|---|---|
| Click Load to check queue | ||
Permanently delete your account and all data
- Disconnect and remove all Telegram accounts
- Delete all contacts and contact lists
- Delete all campaigns and their history
- Remove your profile and all settings
Platform-wide usage overview