Message¶

{
    "id": "<string>",
    "customer_id": "<string>",
    "owner_type": "<string>",
    "owner_id": "<string>",
    "chat_id": "<string>",
    "parent_id": "<string>",
    "type": "<string>",
    "text": "<string>",
    "medias": [
        {
            "type": "<string>",
            "address": "<object>",
            "agent_id": "<string>",
            "file_id": "<string>",
            "link_url": "<string>"
        }
    ],
    "metadata": {
        "reactions": [
            {
                "emoji": "<string>",
                "owner_type": "<string>",
                "owner_id": "<string>",
                "tm_create": "<string>"
            }
        ]
    },
    "tm_create": "<string>",
    "tm_update": "<string>",
    "tm_delete": "<string>"
}

id (UUID): The message’s unique identifier. Returned when creating via POST /service_agents/talk_messages or listing via GET /service_agents/talk_messages.
customer_id (UUID): The customer’s unique identifier. Obtained from GET /customers.
owner_type (enum string): Type of the message owner. Currently only "agent" for user-sent messages, or "system" for system-generated messages.
owner_id (UUID): The agent’s unique identifier who sent the message. Obtained from GET /agents.
chat_id (UUID): The talk’s unique identifier that this message belongs to. Obtained from GET /service_agents/talk_chats.
parent_id (UUID, optional): Parent message ID for threaded replies. Must be the id of an existing message in the same talk. Omit or set to empty string for top-level messages.
type (enum string): Message type. See Type.
text (String): Message text content.
medias (Array of Object): Array of media attachments. Each object contains type (enum string: address, agent, file, or link) and exactly one corresponding value field: address (Object, set only when type is address), agent_id (UUID, set only when type is agent), file_id (UUID, set only when type is file), or link_url (String, set only when type is link).
metadata (Object): Message metadata including reactions. Contains a reactions array.
tm_create (string, ISO 8601): Timestamp when the message was created.
tm_update (string, ISO 8601): Timestamp when the message was last updated.
tm_delete (string, ISO 8601, nullable): Timestamp when the message was deleted (soft delete).

Note

AI Implementation Hint

A tm_delete value of null means the message has not been deleted. To create a threaded reply, set parent_id to the id of the message you want to reply to. The parent message must exist in the same talk.

Example¶

{
    "id": "a3c5e8f2-4d3a-4b5c-9e7f-1a2b3c4d5e6f",
    "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
    "owner_type": "agent",
    "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
    "chat_id": "e8b2e976-f043-44c8-bb89-e214e225e813",
    "parent_id": "b2d4f7a1-3c2e-4f5a-8d9c-2e3f4a5b6c7d",
    "type": "normal",
    "text": "That's a great idea! Let's proceed with that approach.",
    "medias": [],
    "metadata": {
        "reactions": [
            {
                "emoji": "👍",
                "owner_type": "agent",
                "owner_id": "47fe0b7c-7333-46cf-8b23-61e14e62490a",
                "tm_create": "2024-01-17 10:35:00.000000"
            }
        ]
    },
    "tm_create": "2024-01-17 10:32:00.000000",
    "tm_update": "2024-01-17 10:32:00.000000",
    "tm_delete": null
}

Type¶

Message type indicates whether it’s a regular message or system notification.

Type	Description
normal	Regular message sent by an agent. Contains user-authored text and optional media attachments.
system	System-generated notification message. Automatically created when participants join or leave the talk.

Threading¶

Messages can form conversation threads by specifying a parent message ID. When a message includes a parent_id, it appears as a reply to the parent message, creating a nested conversation structure within the talk.

Threading Rules:

Parent message must exist in the same talk.
Parent message can be deleted (soft delete) - the thread structure is preserved.
Replies can have their own replies, creating multi-level threads.

Reactions¶

Agents can add emoji reactions to messages. Reactions are stored in the message metadata and include:

emoji (String): The emoji character (e.g., “thumbsup”, “heart”).
owner_type (enum string): Type of the reactor. Currently only "agent".
owner_id (UUID): Unique identifier of the agent who reacted. Obtained from GET /agents.
tm_create (string, ISO 8601): Timestamp when the reaction was added.

Multiple agents can react to the same message, and the same agent can add multiple different emoji reactions. Reactions provide quick feedback without sending a full message response.

Pin¶

A pin marks a chat or a message that the calling agent wants to keep at hand. A pin is personal: only the agent who created it can see it.

{
    "id": "<string>",
    "target_type": "<string>",
    "target_id": "<string>",
    "chat_id": "<string>",
    "message": { ... },
    "tm_create": "<string>"
}

id (UUID): The pin’s unique identifier. Returned when pinning via POST /service_agents/talk_pins or listing via GET /service_agents/talk_pins.
target_type (enum string): What is pinned. "chat" or "message".
target_id (UUID): The pinned chat ID (from GET /service_agents/talk_chats) or the pinned message ID (from GET /service_agents/talk_messages), depending on target_type.
chat_id (UUID): The chat that the pinned chat or message belongs to. Obtained from GET /service_agents/talk_chats.
message (Object, optional): The pinned message, see Message. Present only in the items of GET /service_agents/talk_pins and only when target_type is "message". The responses of POST and DELETE do not include it.
tm_create (string, ISO 8601): Timestamp when the pin was created.

Note

AI Implementation Hint

Pinning the same target again does not create a second pin; the request returns the existing pin. A pin is listed only while the agent can still see its target: the chat is not deleted, and in a direct or group chat the agent is still a participant. When the agent leaves such a chat the pins stay stored but are not listed, and they are listed again after the agent joins the chat again. A pinned message that was deleted is not listed.

Example¶

{
    "id": "6f1c1a52-8d3b-4c1e-9a5e-0b7f2d9a1c10",
    "target_type": "message",
    "target_id": "0d4b7a3e-2f5c-4b8e-8a21-9c3e6f1d7a42",
    "chat_id": "9a2b5c7d-1e3f-4a6b-8c9d-0e1f2a3b4c5d",
    "message": {
        "id": "0d4b7a3e-2f5c-4b8e-8a21-9c3e6f1d7a42",
        "customer_id": "5e4a0680-804e-11ec-8477-2fea5968d85b",
        "owner_type": "agent",
        "owner_id": "eb1ac5c0-ff63-47e2-bcdb-5da9c336eb4b",
        "chat_id": "9a2b5c7d-1e3f-4a6b-8c9d-0e1f2a3b4c5d",
        "type": "normal",
        "text": "Meeting moved to 3 PM",
        "medias": [],
        "metadata": {"reactions": []},
        "tm_create": "2026-11-02T09:00:00.000000Z",
        "tm_update": "2026-11-02T09:00:00.000000Z",
        "tm_delete": null
    },
    "tm_create": "2026-11-02T09:15:30.123456Z"
}