Il 2026-11-17 SocQ ha aggiunto una piattaforma Telegram con sei endpoint per i canali Telegram pubblici. Insieme coprono l'intero ciclo di ricerca: valutare un canale, leggerne il feed, recuperare post specifici, leggere la discussione sotto un post, trovare canali correlati e cercare una parola nella cronologia di un canale.
Questa guida elenca cosa restituisce ogni endpoint, la richiesta che accetta, quanto costa e quando usarlo. Ogni endpoint lavora a partire da link pubblici t.me e viene eseguito come task SocQ asincrono.
Risposta rapida: invia il link pubblico di un canale o di un post a uno dei sei endpoint
POST /v1/telegram/...conAuthorization: Bearer $SOCQ_API_KEY. Salva iltask_idrestituito, interrogaGET /v1/tasks/{task_id}finchéstatusnon èsucceedede leggi i record indata.results.items. Ogni endpoint è addebitato per risultato: 0.3 o 0.5 crediti per riga, cioè $0.0015 o $0.0025 a $0.005 per credito.
I sei nuovi endpoint di Telegram
| Endpoint | Cosa restituisce | Input | Prezzo |
|---|---|---|---|
| Channel Info | Titolo, descrizione, avatar, badge di verifica, numero di iscritti | Fino a 50 link di canali | 0.5 crediti ($0.0025) per canale |
| Channel Scraper | Post dal più recente, con testo, ora, visualizzazioni, totale delle reazioni, foto e video | Un link di canale | 0.3 crediti ($0.0015) per post |
| Post Detail | Post specifici con testo completo, ora, visualizzazioni, reazioni e media | Fino a 50 link di post | 0.5 crediti ($0.0025) per post |
| Comments | Fino a 100 commenti dal gruppo di discussione collegato, con autore, testo, ora, reazioni e commento a cui rispondono | Un link di post | 0.3 crediti ($0.0015) per commento |
| Similar Channels | Canali che Telegram consiglia accanto a un canale, con username, titolo, badge e iscritti | Un link di canale | 0.5 crediti ($0.0025) per canale |
| Channel Search | Post dell'intera cronologia di un canale che corrispondono a una parola o frase | Un link di canale + query | 0.5 crediti ($0.0025) per post corrispondente |
Tutti e sei addebitano solo le righe restituite, senza costo base per richiesta.
Telegram Channel Info: valuta i canali in blocco
La Telegram Channel Info API cerca canali pubblici tramite link t.me/name o t.me/s/name e restituisce una riga per canale: nome, descrizione, avatar, badge di verifica e numero di iscritti (metrics.followers_count). Usala per valutare un canale prima di una sponsorizzazione, aggiornare una watchlist di canali di notizie o crypto, oppure arricchire link di canali raccolti altrove. Il file dei risultati grezzi riporta anche il numero di foto, video e link condivisi da ogni canale.
curl -X POST "https://api.socq.ai/v1/telegram/channel-info" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://t.me/durov", "https://t.me/tginfo"]
}'
Invia fino a 50 link per richiesta. I link a canali non pubblici vengono saltati; il task fallisce con rimborso solo se nessuno di essi è leggibile. Consulta la documentazione di Channel Info.
Telegram Channel Scraper: leggi il feed di un canale
La Telegram Channel Scraper API legge un canale pubblico partendo dall'ultimo post e andando a ritroso. Ogni post include testo, ora di pubblicazione, numero di visualizzazioni, il totale delle reazioni emoji e Star, e le foto e i video allegati. Recupera gli ultimi giorni per un digest quotidiano, oppure alza il limite per ricostruire la cronologia di un canale.
curl -X POST "https://api.socq.ai/v1/telegram/channel-posts" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://t.me/durov",
"results_limit": 20
}'
results_limit vale 20 per impostazione predefinita e accetta da 1 a 1,000. Un canale che non può essere letto fallisce con rimborso. Consulta la documentazione di Channel Scraper.
Telegram Post Detail: aggiorna i post che conosci già
Quando sai già quali post contano, la Telegram Post Detail API prende i loro link e restituisce ciascuno per intero: testo, ora di pubblicazione, visualizzazioni, reazioni totali, foto e video. In una stessa richiesta puoi mescolare post di canali diversi, il che è utile per aggiornare i numeri di annunci o post di campagna che stai monitorando. Il file dei risultati grezzi conserva il conteggio delle reazioni per ogni emoji e la fonte dell'inoltro.
curl -X POST "https://api.socq.ai/v1/telegram/post-detail" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": ["https://t.me/durov/510"]
}'
Invia fino a 50 link nel formato t.me/channel/post_id. I post eliminati e quelli di canali privati vengono saltati. Consulta la documentazione di Post Detail.
Telegram Comments: leggi la discussione sotto un post
I canali che collegano un gruppo di discussione permettono ai lettori di commentare sotto ogni post. La Telegram Comments API legge quel thread per un post e restituisce ogni commento con nome dell'autore, testo, ora, totale delle reazioni e il commento a cui risponde (parent_id). Usala per capire come una community ha reagito a un annuncio o per inviare i commenti a un flusso di supporto o di ricerca.
curl -X POST "https://api.socq.ai/v1/telegram/post-comments" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://t.me/tginfo/4455",
"results_limit": 100
}'
results_limit vale 100 per impostazione predefinita, che è anche il massimo. Paghi solo i commenti restituiti. Consulta la documentazione di Comments.
Telegram Similar Channels: mappa una nicchia
Telegram mostra una fila di canali correlati su ogni canale pubblico. La Telegram Similar Channels API restituisce quell'elenco per un canale, di solito una decina, nell'ordine in cui Telegram li presenta, ciascuno con username, titolo, badge di verifica e numero di iscritti. Parti da un concorrente o da un canale su cui fai già pubblicità per ampliare la tua lista di media.
curl -X POST "https://api.socq.ai/v1/telegram/similar-channels" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://t.me/durov"
}'
Consulta la documentazione di Similar Channels.
Telegram Channel Search: cerca nella cronologia di un canale
La Telegram Channel Search API cerca una parola o una frase nell'intera cronologia di un canale pubblico e restituisce i post corrispondenti con testo, data, visualizzazioni e reazioni. Verifica se un canale influente ha mai menzionato un progetto, oppure raccogli tutti i post che un canale ha pubblicato su un lancio.
curl -X POST "https://api.socq.ai/v1/telegram/channel-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://t.me/durov",
"query": "TON",
"results_limit": 20
}'
results_limit vale 20 per impostazione predefinita e accetta da 1 a 100. Una ricerca senza corrispondenze non costa nulla. Le foto nei risultati di ricerca rimandano al post che le mostra. Consulta la documentazione di Channel Search.
Autenticazione e flusso asincrono dei task
Ogni richiesta contiene la tua chiave API e un content type JSON:
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Ogni chiamata di invio avvia un task in background:
submit -> task_id -> queued -> running -> succeeded
\-> failed
La risposta all'invio restituisce data.task_id e data.status. Interroga il task con la stessa chiave:
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=50" \
-H "Authorization: Bearer $SOCQ_API_KEY"
Finché il task è queued, running o failed, la risposta contiene solo i metadati del task; in caso di failed, leggi error_message. Quando è succeeded, la stessa risposta include la prima pagina di record normalizzati in data.results.items. limit vale 50 per impostazione predefinita e arriva fino a 500. Se has_more è true, passa results.next_cursor come cursor per leggere la pagina successiva. fields accetta fino a 50 campi o percorsi con punto separati da virgole, quando vuoi una proiezione più ridotta.
Un timeout lato client non annulla il task, quindi riprendi con lo stesso task_id invece di inviare e pagare un duplicato. Per evitare il polling, aggiungi callback_url al body dell'invio; al termine del task SocQ invia una sola POST con un riepilogo e poi leggi i record dall'endpoint del task.
Quanto costa un lavoro tipico
- Valutare 50 canali con Channel Info: 50 × 0.5 = 25 crediti, $0.125.
- Ricostruire 1,000 post di un canale: 1,000 × 0.3 = 300 crediti, $1.50.
- Leggere 100 commenti sotto un annuncio: 30 crediti, $0.15.
- Cercare in un canale e ottenere 20 corrispondenze: 10 crediti, $0.05.
Domande frequenti
Questi endpoint funzionano con canali o gruppi privati?
No. Leggono i canali pubblici tramite i loro link t.me. Channel Info e Post Detail saltano i link che non riescono a leggere, e Comments legge il gruppo di discussione che un canale pubblico collega ai propri post.
Quanto indietro può arrivare il Channel Scraper?
Legge dal più recente e results_limit accetta fino a 1,000 post per richiesta. Per trovare post più vecchi su un argomento specifico, usa Channel Search, che lavora sull'intera cronologia del canale.
Cosa include il conteggio delle reazioni?
Per i post dei canali, metrics.likes_count contiene il totale delle reazioni emoji e Star. Il file dei risultati grezzi di Post Detail conserva il conteggio per ogni emoji.
Pago per canali o post che non vengono trovati?
No. L'addebito è per riga restituita, senza costo base. Una Channel Search senza corrispondenze non costa nulla, e un task in cui nessuno dei link è leggibile fallisce con rimborso.
Come trovo nuovi canali da monitorare?
Parti da un canale che conosci e chiama Similar Channels, poi passa i link restituiti a Channel Info per confrontare il numero di iscritti. Trovi tutti gli endpoint nella pagina della piattaforma Telegram e le tariffe attuali nella pagina dei prezzi.
TELEGRAM API
Prova il flusso di lavoro con un URL pubblico di Telegram
Invia input pubblici e ricevi record normalizzati con un contesto di origine tracciabile.
Scopri le API di Telegram