Filter is cloud software for filtering and forwarding telegram messages. It's Webhooks API gives a way to access Telegram messages in JSON format.
How to configure Webhook
In the web console for your Telegram account, add a filter rule and then press Add action
to choose Webhook
.
Note that you can use a wildcard rule to forward all messages. To do that create a condition as this When any user in any common chat posts anything
.
To forward your messages sent from your Telegram account USER FILTER
-> Include my messages
, so you will get When any user (including me) in any common chat posts anything
Webhook payload
Filter backend receives a message, downloads attachments and re-upload it to temporary storage (so consumers can download them for up to 24 hours) and then sends post request. Filter webhooks implementation is similar to Github's one.
Delivery headers
HTTP POST payloads that are delivered to your webhook's configured URL endpoint will contain a special header:
X-Filter-Signature
. The HMAC hex digest of the response body. This header will be sent if the webhook is configured with a secret. The HMAC hex digest is generated using the sha1 hash function and the secret as the HMAC key.
Also, the User-Agent
for the requests will have the prefix Telegram Filter
.
Example delivery
POST /handler HTTP/1.1
User-Agent: Telegram Filter
Accept: */*
X-Filter-Signature: sha1=ef2b441f473af57d428053fa5bce64cd9101c9c0
Content-Type: application/json
TE: gzip, deflate; q=0.5
Host: 127.0.0.1:3001
Connection: keep-alive
Content-Length: 1557
{
_type: 'Filter$WebhookMessage',
message: {
_type: 'TdApi$Message',
id: 648019968,
...
content: {
_type: 'TdApi$MessageText',
text: { _type: 'TdApi$FormattedText', text: 'message text', entities: [] }
}
},
chat: {
_type: 'Filter$WebhookChat',
id: -1001424174136,
type: { _type: 'TdApi$ChatTypeSupergroup', supergroupId: 1424174136, isChannel: false },
title: 'Test group'
},
chatMember: {
_type: 'TdApi$ChatMember',
userId: 18283932,
...
status: { _type: 'TdApi$ChatMemberStatusCreator', customTitle: '', isMember: true }
},
user: {
_type: 'Filter$WebhookUser',
id: 18283932,
firstName: 'Ask',
lastName: 'Me',
username: 'askmek',
...
photoUrl:
'https://filter-files-store.s3.amazonaws.com/telegram-avatars/34783478343id_293949404/18283932'
}
}
Body format
In the POST-request you receive a JSON object of the following format:
interface WebhookMessage extends TelegramObject {
_type: 'Filter$WebhookMessage'
chat: WebhookChat | null
chatMember: ChatMember | null
fileUrl: string | null
message: Message
user: WebhookUser | null
}
Type definitions for TypeScript
./types/webhool-message.d.ts. Those type definitions are derived from auto-generated java bindings TdApi.java
.
If interface has _type
starting with TdApi$
it means it was generated from TdApi.java
without modifications. If _type
starts with Filter$
- it's one of WebhookMessage
, WebhookChat
or WebhookUser
that are enriched with URLs to the media linked to the message, chat or user.
A fileUrl
field in WebhookMessage
is URL to the message attachment which Filter
uploads to it's own S3-storage.
A photoUrl
field in WebhookChat
and WebhookUser
is URL to the picture (when it exists) of chat
or user
Filter
stores files for 24 hours during which clients should download them (if they need). A current size limit is 100 MB
per attachment. If attachment is bigger it would be skipped.
Example Webhook implementation
TODO