# WhatsApp & Telegram Number Checker (`kernlabs/whatsapp-telegram-phone-checker`) Actor

Bulk phone validator for WhatsApp and Telegram with 0-100 lead scoring and CRM CSV passthrough.

- **URL**: https://apify.com/kernlabs/whatsapp-telegram-phone-checker.md
- **Developed by:** [Bilel Bouzid](https://apify.com/kernlabs) (community)
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$3.90 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## CRM Phone & Messaging Validator (WhatsApp & Telegram)

**CRM Phone & Messaging Validator** is a bulk phone and messaging availability checker: feed it a list of phone numbers or an Apollo/HubSpot CSV and get back standardized formatting, carrier details, and registered availability for WhatsApp and Telegram. Download the results as JSON, CSV, Excel, HTML, or XML.

Use it to check if a number is on WhatsApp or Telegram, clean CRM phone lists, detect timezones, and verify leads before a sales campaign. It runs in the cloud and needs no coding.

**Full CRM CSV Passthrough:** Upload your Apollo, HubSpot, or Salesforce CSV export. The Actor keeps all your original columns (`First Name`, `Company`, `Email`, `Custom Tags`, etc.) and appends the validation results directly to each row.

***

### What does it do?

For each phone number or CSV lead, the Actor:

- **Standardizes format first** — parses numbers to international E.164 format and identifies carrier brand and line type (`Mobile`, `Fixed Line`, `VoIP`, `Toll Free`), so every charge goes to a real check.
- **Checks WhatsApp registration** — confirms whether the number is a registered WhatsApp account and identifies Business vs. Regular profiles.
- **Checks Telegram registration** — confirms whether the number is registered on Telegram, extracts public `@username`, and checks Telegram Premium status.
- **Detects Timezone & Business Hours** — resolves the local IANA timezone and calculates whether it is safe to contact right now (Monday–Friday, 9:00 AM – 6:00 PM local time).
- **Calculates Lead Quality Score** — gives an instant 0–100 reachability score and recommends the best outreach channel (`WhatsApp`, `Telegram`, `SMS / Phone`, or `Email Only`).

***

### What data does it return?

Each result is one row per phone number (or one row per CSV record):

| Data | Details |
| :--- | :--- |
| **🏢 CRM Columns** | All your original columns from your uploaded CSV (First Name, Company, Email, etc.) preserved intact |
| **📱 Number (E.164)** | The standardized phone number with country prefix (e.g., `+14155552671`) |
| **🏷️ Carrier & Type** | Network carrier name (e.g., Orange, Verizon) and line classification (`Mobile`, `Fixed Line`, `VoIP`) |
| **💬 WhatsApp** | Registration status (`true` / `false`) and account type (`business` / `regular`) |
| **✈️ Telegram** | Registration status (`true` / `false`), public `@username`, and Telegram Premium badge |
| **🕒 Timezone & Local Time** | Lead's local IANA timezone (e.g., `America/Los_Angeles`) and current local time |
| **☀️ Business Hours** | Whether the lead is currently within business hours (`true` / `false`) |
| **📊 Lead Quality Score** | 0–100 composite deliverability score and recommended outreach channel |
| **🕒 Verified At** | UTC timestamp of when the check was performed |

Every number that could be processed gets its own row with full intelligence. If a number is malformed or invalid, it is flagged with `validFormat: false`, `leadQualityScore: 0`, and a clear error explanation so you can purge dead leads immediately.

***

### Input

Provide an array of phone numbers, or paste raw CSV text with lead details:

#### Option A: Simple Phone List

```json
{
  "phoneNumbers": [
    "+14155552671",
    "+33612345678",
    "+447911123456"
  ],
  "platforms": ["whatsapp", "telegram"],
  "defaultCountry": "US"
}
```

#### Option B: CRM CSV Passthrough (Apollo / HubSpot)

```json
{
  "csvContent": "First Name,Company,Email,phone\nSarah,FinTech Corp,sarah@fintech.io,+14155552671\nMarc,SaaS Lab,marc@saas.com,+33612345678",
  "platforms": ["whatsapp", "telegram"]
}
```

***

### Output

```json
[
  {
    "First Name": "Sarah",
    "Company": "FinTech Corp",
    "Email": "sarah@fintech.io",
    "input": "+14155552671",
    "e164": "+14155552671",
    "country": "US",
    "validFormat": true,
    "carrier": "T-Mobile",
    "leadQualityScore": 95,
    "recommendedChannel": "WhatsApp",
    "riskLevel": "Low",
    "timezone": "America/Los_Angeles",
    "localTime": "09:15 AM",
    "isBusinessHours": true,
    "whatsapp": {
      "isRegistered": true,
      "accountType": "business"
    },
    "telegram": {
      "isRegistered": true,
      "hasUsername": true,
      "isPremium": true
    },
    "verifiedAt": "2026-09-17T16:07:11Z"
  },
  {
    "First Name": "Marc",
    "Company": "SaaS Lab",
    "Email": "marc@saas.com",
    "input": "+33612345678",
    "e164": "+33612345678",
    "country": "FR",
    "validFormat": true,
    "carrier": "Orange",
    "leadQualityScore": 75,
    "recommendedChannel": "WhatsApp",
    "riskLevel": "Low",
    "timezone": "Europe/Paris",
    "localTime": "06:15 PM",
    "isBusinessHours": false,
    "whatsapp": {
      "isRegistered": true,
      "accountType": "regular"
    },
    "telegram": {
      "isRegistered": false,
      "hasUsername": false,
      "isPremium": false
    },
    "verifiedAt": "2026-09-17T16:07:11Z"
  }
]
```

***

### Pricing

Pay only for the results you get — one flat charge per lead verified. Numbers that are completely invalid or couldn't be checked are never charged.

***

### Real-time API

Need checks on demand? Call the Actor like a live API from your backend, CRM, or automation platform (Make.com, Zapier, n8n):

```bash
curl -X POST "https://api.apify.com/v2/acts/<YOUR_USERNAME>~crm-phone-messaging-validator/run-sync-get-dataset-items?token=<YOUR_APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumbers": ["+14155552671", "+33612345678"],
    "platforms": ["whatsapp", "telegram"]
  }'
```

The response is a JSON array containing the verified data, lead scores, timezones, and messaging availability straight back in the HTTP response.

# Actor input Schema

## `phoneNumbers` (type: `array`):

List of phone numbers to sanitize and check. Can be in international, national, or raw format.

## `csvContent` (type: `string`):

Optional raw CSV or newline-delimited text containing phone numbers. If provided, numbers are merged with phoneNumbers array.

## `platforms` (type: `array`):

Select messaging platforms to query for account registration.

## `defaultCountry` (type: `string`):

Two-letter country code used as fallback for parsing national numbers missing an international prefix (+).

## `concurrencyLimit` (type: `integer`):

Maximum number of phone validations executed concurrently.

## `proxyConfiguration` (type: `object`):

Apify Proxy or custom proxies used for network queries and platform lookups.

## `whatsappApiToken` (type: `string`):

Meta Graph API / WhatsApp Cloud API access token for contact lookups. Can also be set via WHATSAPP\_API\_TOKEN environment variable.

## `whatsappPhoneNumberId` (type: `string`):

Meta Phone Number ID associated with your WhatsApp Business Account. Can also be set via WHATSAPP\_PHONE\_NUMBER\_ID env var.

## `telegramApiId` (type: `integer`):

Telegram App API ID obtained from my.telegram.org. Can also be set via TELEGRAM\_API\_ID env var.

## `telegramApiHash` (type: `string`):

Telegram App API Hash obtained from my.telegram.org. Can also be set via TELEGRAM\_API\_HASH env var.

## `telegramSessionString` (type: `string`):

Pre-authenticated Telethon StringSession. Can also be set via TELEGRAM\_SESSION\_STRING env var.

## `simulationMode` (type: `boolean`):

If enabled (or when live credentials are not provided), simulates messaging platform responses for pipeline testing.

## Actor input object example

```json
{
  "phoneNumbers": [
    "+33612345678",
    "+14155552671",
    "+447911123456",
    "0612345678"
  ],
  "platforms": [
    "whatsapp",
    "telegram"
  ],
  "defaultCountry": "FR",
  "concurrencyLimit": 5,
  "simulationMode": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

Enriched records with E.164 phone numbers, messaging availability, and lead quality scores.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "phoneNumbers": [
        "+33612345678",
        "+14155552671",
        "+447911123456",
        "0612345678"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("kernlabs/whatsapp-telegram-phone-checker").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "phoneNumbers": [
        "+33612345678",
        "+14155552671",
        "+447911123456",
        "0612345678",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("kernlabs/whatsapp-telegram-phone-checker").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "phoneNumbers": [
    "+33612345678",
    "+14155552671",
    "+447911123456",
    "0612345678"
  ]
}' |
apify call kernlabs/whatsapp-telegram-phone-checker --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kernlabs/whatsapp-telegram-phone-checker"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/etPPga8hF46ClcJmN/builds/iN7uQmEBb3CqhLuYt/openapi.json