Guide / Controls / Readouts

Chat

Messages back and forth

When to use it. A real-time messaging interface that supports sending and receiving messages over MeshSocket. Ideal for device-to-device communication, command logs, or interactive chatbots.

Type
chat
Default size
4 rows × 4 columns
Symbol
bubble.left.and.bubble.right.fill
Docs
Docs complete
Search for it as
  • messages
  • conversation
  • assistant
  • ai
  • talk
  • inbox
Chat: Device-to-device chat
Rendered by the app

Fields

12 fields you can set on a chat control. Every control also takes the shared fields (id, position, span, sync, action).

Fields
FieldTypeDefaultWhat it does
Titlelabeltext—

The name shown above the chat

Shows this text in the chat's header bar.

configconfigobject—

Chat settings grouped together

Holds the chat's options (target, typing dots, receipts, reactions, replies, images, history, color) in one object.

allowClearconfig.allowClearon / off—

Lets you wipe the chat from here

Shows a Clear Chat menu in the header that empties this device's messages only; other people's windows are untouched.

Imagesconfig.allowImageson / off—

Lets people attach pictures

Turns image attachments on or off for this chat.

Reactionsconfig.allowReactionson / off—

Lets people react to messages

Adds a React choice to the long-press menu and shows emoji reactions on messages when on.

Repliesconfig.allowReplieson / off—

Lets people reply to a message

Adds a Reply choice to the long-press menu and shows replies in threads when on.

historyCountconfig.historyCountnumber1–50step 1—

How many messages are kept

Keeps only this many of the latest messages (1 to 50, default 50) in the window and in history sent to peers.

Read receiptsconfig.showReadReceiptson / off—

Shows when messages are delivered

Shows delivery and read marks under your messages when on.

Typing dotsconfig.showTypingIndicatorson / off—

Shows when someone is typing

Shows animated typing dots while the other side is typing when on.

systemMessageEventsconfig.systemMessageEventsstring[]—

Events that show as notices

Lists event names meant to appear as system notes in the chat; the app does not act on it yet.

targetconfig.targettext—

Who to chat with

Sends your messages to the named MeshSocket peer as a private companion chat; leave it empty to chat with the whole channel.

Colorconfig.tintcolor—

The chat's accent color

Sets the accent color used by the chat bubbles.

Emits and receives

What this control sends when you use it, and what it can show or follow when data arrives.

Emits

Emits
SendsWhenTypeWhat it sends
When you send a messagemessagesubmitstring

the message text

It goes to the MeshSocket peer named in Target, or to the whole channel when Target is empty

Example: Sample A

Receives

Receives
TakesFromTypeWhat it does
linesshowhubjson

a reply broadcast with its text and an optional sender name

the reply is added to the bottom of the conversation, shown under the sender name or the Target name

Example: {"text": "Sample A"}

Sample

The placeholder value the editor shows before real data arrives.

  • {"lines": [{"name": "Sample A", "text": "Sample A"}, {"name": "Sample B", "text": "Sample B"}]}

Examples

3 examples, each one a control you can paste into a layout.

Device-to-device chat

Chat with a hub peer, with typing dots, receipts, reactions and replies on, and a long history.

JSON 15 lines
{
  "type": "chat",
  "id": "team-chat",
  "position": [0, 0],
  "span": [4, 4],
  "label": "Team Chat",
  "config": {
    "target": "hub-server",
    "showTypingIndicators": true,
    "showReadReceipts": true,
    "allowReactions": true,
    "allowReplies": true,
    "historyCount": 100
  }
}

Open in CAR-TER

Chat: Device-to-device chat
Rendered by the app

Companion chat

Talk privately to one named peer, with no images and a short history.

JSON 13 lines
{
  "type": "chat",
  "id": "companion-chat",
  "position": [0, 0],
  "span": [4, 4],
  "label": "Assistant",
  "config": {
    "target": "companion",
    "allowImages": false,
    "allowReplies": false,
    "historyCount": 20
  }
}

Open in CAR-TER

Quiet read-only log

Show channel messages without typing dots, receipts, reactions or a Clear Chat control.

JSON 15 lines
{
  "type": "chat",
  "id": "channel-log",
  "position": [4, 0],
  "span": [4, 4],
  "label": "Channel Log",
  "config": {
    "showTypingIndicators": false,
    "showReadReceipts": false,
    "allowReactions": false,
    "allowReplies": false,
    "allowClear": false,
    "tint": "#34C759"
  }
}

Open in CAR-TER

Try it on your phone

carterkit serves a small hub on your computer and pushes one example to CAR-TER on your iPhone or iPad. Pair once with the code it prints.

  1. Install the Python kit.

    pip install carterkit
  2. Show “Device-to-device chat” on your phone.

    carterkit demo chat --example 'Device-to-device chat'
  3. Swap in any example name from this page, or leave --example off for the first one.

carterkit quickstart · Get CAR-TER

Message actions (long-press)

Long-press any message bubble for an iMessage-style menu: Copy (the message text), Reply (when allowReplies), React (emoji, when allowReactions), and Delete (removes it from this device's window only). The old tap-to-reveal reaction bar is gone — reactions now live in this menu.

Clearing the window

Two independent ways to wipe the log:

  • Local — the header's Clear Chat menu (shown when config.allowClear is true, the default) empties this device's window only. It does not notify peers.
  • Server-driven — the channel/companion authority clears every member's window by emitting a chat_clear frame. In channel mode it rides the shared broadcast multiplexer like every other chat frame; in companion (config.target) mode it arrives as a broadcast:

json // channel mode "broadcast_request": { "msg_type": "chat_clear", "chatId": "team-chat" } // companion mode "broadcast": { "event": "chat_clear" }

An absent chatId clears every chat control on the channel; a present one targets just that control's id. chat_clear is wire API — never rename it.

Wire Protocol

When config.target is set, the chat routes to that peer by name (companion mode):

Outgoing — every message you send:

"route_msg_noreply": {
  "target_name": "companion",
  "type": "chat_message",
  "payload": { "text": "your message" }
}

Incoming — the companion replies with a broadcast the chat listens for:

"broadcast": { "event": "chat_response", "text": "the reply" }

The optional name / sender.name / from field on the broadcast sets the reply's display name; otherwise it falls back to the target name.

The companion (server side) must wait for the MeshSocket welcome before routing — connect, wait_until_ready(), then wait for the welcome event before sending.

Without config.target (channel mode) the chat sends a chat_message event and listens on chat_message for the whole channel.

Generated from ControlDocs/chat.md. Something unclear or missing? Tell me.