---
title: "message.received — Customer message"
locale: en
url: https://tlg.builera.app/en/docs/reference/events/message.received
verified: 2026-10-24
app_version: "2.0"
generated: true
---

# message.received — Customer message

An incoming message on an account (not the history loaded by the first sync).

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](https://tlg.builera.app/schemas/events/message.received/2.json)

## Sample payload (exactly what `webhooks.test` sends)

```json
{
  "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"
    ]
  }
}
```