GREEN-API Integration for Telegram

Support

Guides and News

• Документация на русском языке

This integration enables interaction with WhatsApp in Telegram through the GREEN-API platform. It is built on the Universal Integration Platform from GREEN-API and consists of an adapter that converts messages between Telegram and WhatsApp.

Architecture

Components

• TelegramAdapter - Express.js application that handles message conversion between Telegram and WhatsApp
• TelegramHandler - Processes Telegram commands and user interactions
• TelegramTransformer - Transforms messages between platforms
• PartnerApiClient - Client for working with GREEN-API Partner API
• Localization - Multi-language support system (English/Russian)
• SQLiteStorage - Database for storing user data and instances

Telegram commands

The bot provides the following commands:

• /help - Command reference
• /start - Start working with the bot
• /me - Information about current user
• /instance [idInstance] [apiTokenInstance] - Connect GREEN-API instance
• /resetInstance - Reconnect instance
• /status or /getStateInstance - Check instance status
• /notifications [type] [on|off] - Manage notifications (receiving incoming messages, statuses of sent messages, and instance status)
• /setchat [chat_id] — Set up forwarding to another Telegram chat
• /reply or /sendMessage [WhatsApp number] [text] - Send message to WhatsApp
• /setpartnertoken [token] - Set partner token
• /createinstance - Create new instance
• /getinstances - Get list of instances
• /deleteinstance [idInstance] - Delete instance
• /language or /lang - Change language

Features

• Multi-language support (English/Russian)
• Notification management
• Partner API integration
• Instance management via bot
• Webhook handling for both platforms
• SQLite database for data persistence

Prerequisites

• .js 20 or higher
• GREEN-API account and instance
• Telegram bot (get from @BotFather)
• Publicly accessible URL for webhooks (when deploying on server)

Installation

Local Installation

1. Clone or create the project:

mkdir greenapi-integration-telegram

2. Clone the repository:

git clone https://github.com/green-api/greenapi-integration-telegram.git

3. Install dependencies:

npm install

4. Configure environment variables in .env file:

TELEGRAM_BOT_TOKEN=your_telegram_bot_token_here
PORT=3000
WEBHOOK_URL= https://your-webhook-url/

• TELEGRAM_BOT_TOKEN - via @BotFather
• PORT - by default 3000
• WEBHOOK_URL - public server adress

5. Start the application:

npm start

Deployment

Docker Deployment

Create Dockerfile:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
EXPOSE 3000
CMD ["npm", "start"]

And docker-compose.yml:

version: '3.8'
services:
  adapter:
    build: .
    ports:
      - "3000:3000"
    environment:
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_BOT_TOKEN}
      - PORT=3000
    volumes:
      - ./storage.db:/app/storage.db

Start:

docker-compose up -d

App usage

1. Getting Started

Send the /start command to the bot in Telegram to register.

2. Connect GREEN-API instance

/instance [idInstance] [apiTokenInstance]

• idInstance: Your GREEN-API instance ID
• apiTokenInstance: Your GREEN-API instance API token

Example:

/instance 1101111111 abcdef123456789abcdef123456789

3. Checking Instance Status

/status

или

/getStateInstance

4. Replying to WhatsApp Messages

/reply [WhatsApp number] [message text]

or

/sendMessage [WhatsApp number] [message text]

5. Reset connected instance

/resetInstance

6. Change language

/language en

or

/language ru

7. Manage notifications

• Enable all notifications

  /notifications all on
  

• Disable all notifications:

  /notifications all off
  

• Enable notifications about incoming messages

  /notifications incoming on
  

• Disable notifications about incoming messages

  /notifications incoming off
  

• Enable notifications about sent message statuses

  /notifications outgoing on
  

• Disable notifications about sent message statuses

  /notifications outgoing off
  

• Enable notifications about instance status

  /notifications status on
  

• Disable notifications about instance status

  /notifications status off
  

8. Help

/help

Important Notes

Obtaining GREEN-API Credentials

For the integration to work, you will need:

1. idInstance - ID of your instance in GREEN-API
2. apiTokenInstance - Access token of your instance

These credentials can be obtained in the GREEN-API console after creating an instance.

Supported Message Types

The integration forwards the following types of messages from WhatsApp to Telegram:

• Text messages
• Images (with captions)
• Videos (with captions)
• Audio (with captions)
• Documents (with captions)
• Locations
• Contacts
• Polls

The integration forwards the following types of messages from Telegram to WhatsApp:

• Text messages

Data Storage

The integration uses SQLite database to store:

• Telegram user data
• GREEN-API instance connections
• User settings and preferences
• Language preferences
• Settings and states

The database file storage.db is created automatically on first run.

Troubleshooting

Bot Not Responding to Commands

1. Check that TELEGRAM_BOT_TOKEN is set correctly
2. Make sure the Telegram webhook is configured properly
3. Check application logs for errors

Messages Not Delivered to WhatsApp

1. Check instance status with /status command
2. Make sure the instance is authorized in GREEN-API
3. Check webhook settings in GREEN-API personal account

File Sending Errors

1. Make sure your adapter URL is publicly accessible
2. Check file size (Telegram and GREEN-API limitations)
3. Make sure the file type is supported

Partner API Issues

1. Check the correctness of the partner token
2. Ensure the partner API is accessible
3. Check the logs for authentication errors

Localization Issues

1. Ensure the localization files are present
2. Check the language installation using the /language command