Guida Telegram

UniMsg supporta l'invio di messaggi tramite bot Telegram, ideale per notifiche, alert e comunicazioni con utenti che preferiscono questo canale.

Caratteristiche

• Invio messaggi via Bot Telegram
• Supporto formattazione Markdown e HTML
• Invio media (foto, documenti, video)
• Tastiere inline per interazioni
• Notifiche silenziose
• Costo: 0.5 crediti per messaggio

Prerequisiti

Per inviare messaggi Telegram, hai bisogno di:

1. Un bot Telegram (creato tramite @BotFather)
2. Il chat_id dell'utente destinatario

Ottenere il Chat ID

Il chat_id è l'identificativo unico dell'utente o gruppo Telegram. L'utente deve prima avviare una conversazione con il tuo bot. Puoi ottenere il chat_id:

• Tramite webhook quando l'utente invia /start al bot
• Usando bot come @userinfobot
• Tramite l'API di Telegram getUpdates

Endpoint

Metodo	Endpoint	Descrizione
POST	/v1/telegram/send	Invia messaggio di testo
POST	/v1/telegram/photo	Invia foto
POST	/v1/telegram/document	Invia documento
GET	/v1/telegram/{id}	Stato messaggio

Invio Messaggio di Testo

Richiesta

POST /v1/telegram/send
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "chat_id": "123456789",
    "message": "Ciao! Questo è un messaggio da UniMsg.",
    "parse_mode": "Markdown"
}

Parametri

Parametro	Tipo	Obbligatorio	Descrizione
chat_id	string	Sì	ID chat Telegram del destinatario
message	string	Sì	Testo del messaggio (max 4096 caratteri)
parse_mode	string	No	Formato: "Markdown", "MarkdownV2", "HTML"
disable_notification	boolean	No	Invia senza suono (default: false)
reply_markup	object	No	Tastiera inline o reply

Risposta

{
    "success": true,
    "data": {
        "message_id": "msg_tg_xxxxxxxxxxxx",
        "chat_id": "123456789",
        "telegram_message_id": 456,
        "status": "sent",
        "credits_used": 0.5,
        "created_at": "2024-01-15T10:30:00Z"
    }
}

Formattazione Messaggi

Markdown

{
    "chat_id": "123456789",
    "message": "*Testo in grassetto*\n_Testo in corsivo_\n`codice inline`\n[Link](https://unimsg.app)",
    "parse_mode": "Markdown"
}

HTML

{
    "chat_id": "123456789",
    "message": "<b>Grassetto</b>\n<i>Corsivo</i>\n<code>Codice</code>\n<a href='https://unimsg.app'>Link</a>",
    "parse_mode": "HTML"
}

Invio con Tastiera Inline

Puoi aggiungere pulsanti interattivi ai messaggi:

{
    "chat_id": "123456789",
    "message": "Vuoi confermare l'ordine?",
    "reply_markup": {
        "inline_keyboard": [
            [
                {"text": "✅ Conferma", "callback_data": "confirm_order"},
                {"text": "❌ Annulla", "callback_data": "cancel_order"}
            ],
            [
                {"text": "📞 Contattaci", "url": "https://unimsg.app/support"}
            ]
        ]
    }
}

Tipi di Pulsanti

Tipo	Proprietà	Descrizione
Callback	callback_data	Invia dati al bot (webhook)
URL	url	Apre un link esterno

Invio Media

Foto

POST /v1/telegram/photo
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "chat_id": "123456789",
    "photo_url": "https://example.com/image.jpg",
    "caption": "Ecco la foto richiesta!"
}

Documento

POST /v1/telegram/document
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
    "chat_id": "123456789",
    "document_url": "https://example.com/report.pdf",
    "caption": "Report mensile"
}

Limiti Media

Tipo	Dimensione Max	Formati
Foto	10 MB	JPG, PNG, GIF
Documento	50 MB	Qualsiasi
Video	50 MB	MP4
Audio	50 MB	MP3, OGG

Stati del Messaggio

Stato	Descrizione
sent	Messaggio inviato a Telegram
delivered	Consegnato (Telegram non fornisce conferme)
failed	Invio fallito

Errori Comuni

Codice	Descrizione	Soluzione
INVALID_CHAT_ID	Chat ID non valido	Verifica l'ID
BOT_BLOCKED	L'utente ha bloccato il bot	L'utente deve sbloccare il bot
CHAT_NOT_FOUND	Chat non trovata	L'utente deve avviare il bot
MESSAGE_TOO_LONG	Messaggio troppo lungo	Max 4096 caratteri