Reference
message.received — Customer message
An incoming message on an account (not the history loaded by the first sync).
View MarkdownThis page is generated from the source code on every release.
An incoming message on an account (not the history loaded by the first sync).
Since web 1.0.0, worker —.
| Name | Value |
|---|---|
| Code | message.received |
| Group | Messages |
| Status | Subscribable |
| Scope needed to receive it | messages.read |
| Tied to one account | Yes |
| Only the connection that caused it receives it | No |
| Filters that apply | chat_types, mention_only, exclude_self, include_backfill, conversation_ids, conversation_tags, keywords, has_media, person_stage_ids, campaign_ids |
Fields dropped in thin content mode |
message.text, message.reply_to.text, message.reply_to.sender_name, message.quote_text, message.attachments[].name, message.forwarded_from, conversation.title, conversation.topic.title, sender.name, sender.username |
| Fields written by outside people (untrusted) | message.text, message.reply_to.text, message.quote_text, message.attachments[].name, message.forwarded_from.name, sender.name, conversation.title, conversation.topic.title |
JSON Schema
https://tlg.builera.app/schemas/events/message.received/2.json
Sample payload (exactly what webhooks.test sends)
{
"specversion": "1.0",
"id": "evt_01JDOCSSAMPLE",
"source": "https://tlg.builera.app/ws/07c2e5e1-c42f-4212-851b-c55b6dd7989d",
"type": "message.received",
"time": "2026-10-21T13:45:00.123Z",
"datacontenttype": "application/json",
"dataschema": "https://tlg.builera.app/schemas/events/message.received/2.json",
"platform": "telegram",
"workspaceid": "07c2e5e1-c42f-4212-851b-c55b6dd7989d",
"accountid": "1a7d2c40-5b1e-4e7a-9d3f-6c2b8e1f0a11",
"seq": "000000000000000",
"schemaversion": "2",
"correlationid": null,
"causationid": null,
"test": true,
"replay": false,
"data": {
"message": {
"id": "6b1c3d5e-7f9a-4b2c-8d4e-6f8a0b2c4d6e",
"tg_message_id": 8812,
"direction": "in",
"type": "text",
"text": "Shop ơi còn size M không?",
"attachments": [],
"reply_to": null,
"quote_text": null,
"mentions": [],
"is_mention": false,
"is_reply_to_me": false,
"is_self": false,
"is_backfill": false,
"topic_id": null,
"grouped_id": null,
"forwarded_from": null,
"service_action": null,
"sent_at": "2026-10-21T13:45:00.123Z"
},
"conversation": {
"id": "9f2e4b6a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
"chat_type": "direct",
"title": "Nguyễn Văn A",
"peer_tg_id": "456789",
"topic": null,
"assignee_id": null,
"tags": [
"vip"
],
"campaign_id": null,
"lock": null
},
"sender": {
"tg_user_id": "456789",
"name": "Nguyễn Văn A",
"username": "nva",
"person_id": "c41b7e2a-9d3c-4b1f-8e2a-7c5d3b1f9e08",
"stage_id": "3e5f7a9b-1c3d-4e5f-9a1b-2c3d4e5f6a7b",
"is_contact": true,
"internal": false
},
"account": {
"id": "1a7d2c40-5b1e-4e7a-9d3f-6c2b8e1f0a11",
"label": "Sale 1",
"username": "sale_demo_1",
"tg_user_id": "100200300"
},
"links": {
"app": "https://tlg.builera.app/w/07c2e5e1-c42f-4212-851b-c55b6dd7989d/inbox?c=9f2e4b6a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
"reply": {
"operation": "messages.send",
"rest": "POST /api/public/v2/ops/messages.send",
"mcp_tool": "messages_send",
"input": {
"conversationId": "9f2e4b6a-1c3d-4e5f-8a9b-0c1d2e3f4a5b",
"replyToMessageId": 8812,
"inReplyToEventId": "evt_01JDOCSSAMPLE"
}
}
},
"untrusted_fields": [
"message.text",
"sender.name",
"conversation.title"
]
}
}