Prerequisites

Before installing, make sure your environment meets these requirements:

Installation

1. Upload the sm_telegram module folder to your server's custom addons directory.
2. Restart the Odoo service to detect the new module.
3. Navigate to Apps menu, click Update Apps List.
4. Search for "Telegram Integration Advanced" and click Install.

Step 1: Talk to BotFather

1. Open Telegram on your phone or desktop.
2. Search for @BotFather and start a conversation.
3. Send the /newbot command.
4. Follow the instructions — choose a name and a username for your bot.
5. BotFather will provide you with a unique API Token.

Step 2: Register Bot in Odoo

1. Navigate to Telegram → Bots → New.

2. Fill in the following fields:

   Token:	Paste the API Token you received from BotFather.
   Company:	Select the company this bot belongs to. Each company can have its own bot.

3. Click the Verify Bot button.

   The system calls the Telegram getMe API to validate the token and automatically fetches the bot's name and username.

4. Click the Setup Webhook button.

   This registers your Odoo server URL with Telegram via the setWebhook API. A cryptographically secure secret token is auto-generated for webhook validation.

Setup

1. Navigate to Telegram → Model Configuration → New.
2. Configure the following fields:

   Model:	Select the Odoo model (e.g. sale.order, account.move, res.partner).
   Allowed Reports:
   	Whitelist which QWeb PDF reports can be sent via Telegram for this model. If left empty, all PDF reports for the model are available.
   Allowed Users:	Optionally restrict which users can send Telegram messages for this model. If left empty, all users can send.
   Default Template:
   	Optionally select a template that will be auto-loaded when a user opens the send wizard for this model.

How It Works

1. Your customer opens Telegram and searches for your bot (e.g. @YourCompanyBot).
2. They send the /start command.
3. The webhook controller receives the update and automatically:
   • Extracts the Telegram username and chat_id from the message.
   • Searches for a res.partner with a matching telegram_username field.
   • Writes the telegram_chat_id on that partner record.

Partner Fields

Two fields are added to res.partner:

From the Chatter

1. Open any record (Sale Order, Invoice, Partner, etc.) that has a configured model.
2. In the chatter, click the Send Telegram button.
3. The Send Wizard opens with the following options:

   Recipients:	Select one or more partners who have a telegram_chat_id. You can send to up to 50 recipients at once.
   Template:	Select a pre-configured template, or leave empty to write a custom message. If the model has a default template, it is auto-loaded.
   Message:	The message body. If a template is selected, it is rendered with Jinja2 variables and pre-filled here. You can still edit it before sending.
   Parse Mode:	Choose between Markdown, HTML, or Plain Text formatting.
   Report:	Optionally attach a QWeb PDF report (only whitelisted reports are shown).
   Attachments:	Attach any ir.attachment files. Images are automatically sent as Telegram photos, other files as documents.
   Scheduled Date:	Leave empty to send immediately, or set a future date/time for deferred delivery.

4. Click Send.

Creating a Template

1. Navigate to Telegram → Templates → New.
2. Configure the following:

   Name:	A descriptive name for the template (e.g. "Order Confirmation").
   Model:	The Odoo model this template applies to.
   Body:	The message body using Jinja2 template syntax.
   Parse Mode:	Markdown or HTML for rich text formatting.
   Report:	Optionally attach a PDF report action — it auto-generates on send.

Available Variables

These variables are available inside the template body:

Example template body (Markdown):

*Order Confirmation* 🎉

Hello **{{ partner.name }}**,

Your order **{{ object.name }}** has been confirmed!

Total: {{ object.amount_total }} {{ object.currency_id.name }}

Thank you for your business.
— {{ company.name }}

Inline Keyboard Buttons

Add clickable URL buttons that appear below the message in Telegram:

1. In the template form, go to the Buttons tab.
2. Click Add a line and fill in:

   Label:	The button text (e.g. "View Order")
   URL:	The destination URL
   Row:	Row number (buttons on the same row appear side by side)

Scheduled Messages

Instead of sending immediately, set a scheduled date/time in the send wizard. The message will be saved with status "scheduled" and a background cron job will process it when the time comes.

Auto-Retry for Failed Messages

If a message fails to send (network error, Telegram API downtime, etc.), the system can automatically retry it.

Configuration: Navigate to Settings → General Settings → Telegram.

Log Fields

Chatter Audit Trail

After every send operation, a summary note is automatically posted on the chatter of the source document. The note includes:

• ✅ Recipients that received the message successfully
• ❌ Recipients that failed, with error details

End-to-End Flow

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  BotFather   │────▶│  Odoo Bot    │────▶│  setWebhook     │
│  (get token) │     │  (verify)    │     │  (register URL) │
└─────────────┘     └──────────────┘     └─────────────────┘
                                                   │
                     ┌──────────────────────────────┘
                     ▼
┌────────────────────────────────────┐
│  /telegram/webhook/<secret>        │
│  (controller receives updates)     │
└────────────────────────────────────┘
                     │
         ┌───────────┴───────────┐
         ▼                       ▼
┌─────────────────┐   ┌──────────────────┐
│  /start command  │   │  Other messages   │
│  (map chat_id)  │   │  (future use)     │
└─────────────────┘   └──────────────────┘

┌─────────────────────────────────────────────────────┐
│  Send Wizard (from chatter)                         │
│  ┌─────────┐  ┌──────────┐  ┌─────────┐           │
│  │ Message  │  │ Template │  │ Report  │           │
│  │ (text)   │  │ (Jinja2) │  │ (PDF)   │           │
│  └────┬─────┘  └────┬─────┘  └────┬────┘           │
│       └──────────────┴─────────────┘                │
│                      │                              │
│              ┌───────┴───────┐                      │
│              ▼               ▼                      │
│     ┌──────────────┐ ┌──────────────┐              │
│     │ Send Now     │ │ Schedule     │              │
│     │ (Telegram    │ │ (cron job    │              │
│     │  API call)   │ │  picks up)   │              │
│     └──────┬───────┘ └──────┬───────┘              │
│            └────────┬───────┘                       │
│                     ▼                               │
│          ┌─────────────────┐                        │
│          │  Message Log    │                        │
│          │  (audit trail)  │                        │
│          └─────────────────┘                        │
└─────────────────────────────────────────────────────┘

Models

API Endpoints

Cron Jobs