Talk to users.
In their own chat.

How users connect

Creating a bot also creates a chat for its owner. A private bot is available to its owner; make the bot public in the console so other users can start a chat with it.

Share the bot’s link or QR code from the console. After signing in, a user can open the bot’s profile and select Start chat. BotComm creates a session for that user and bot, or opens their existing conversation.

Messages go to existing sessions. To reach a new user, they need to connect to your public bot first. If a user deletes a chat, they can start it again to create a new session.

Sessions identify recipients

A session belongs to one user and one bot. Its sessionID is the destination for messages to that user; it is separate from the bot’s handle and client ID.

Users can copy their Session ID from Chat Settings on web or iOS. A running bot can retrieve its sessions or receive a new_session event when a user starts a chat. Incoming messages also include their sessionID, so replies can return to the same conversation.

Use only sessions belonging to your bot. Each user sees the messages in their own chat.

Message types

A message can contain text, answer buttons, and uploaded attachments. Choose the content and interaction that fit the update you want to send.

Text and Markdown

Put your message in content. Plain text works as-is; Markdown lets you add bold and italic text, links, lists, quotes, and code. Text content is limited to 4,096 Unicode characters.

{
  "content": "**Deployment complete**\n\nYour app is live. [View release](https://example.com/releases/42)"
}

Message formatting belongs in the content string; no separate format field is needed. Upload an image as an attachment when you want it displayed as an image in chat.

Answer buttons

Attach a keyboard to a bot message to offer one-tap answers. Each option has a label shown to the user and a value your code receives.

{
  "content": "Would you like a daily report?",
  "keyboard": {
    "options": [
      { "label": "Yes, please", "value": "daily_report_yes" },
      { "label": "No, thanks", "value": "daily_report_no" }
    ]
  }
}

This can be sent with the same HTTP request as a text message. Include sessionID to choose a conversation, or broadcast: true to give every connected user their own copy and selection.

When the user taps “Yes, please,” the bot receives an answer message containing these fields:

{
  "sessionID": "USER_SESSION_ID",
  "content": "Yes, please",
  "replyTo": "ORIGINAL_MESSAGE_ID",
  "value": "daily_report_yes"
}

Use value to decide what to do, replyTo to identify the question, and sessionID to reply to the same user. Sending buttons uses the HTTP endpoint; receiving their answers requires your bot’s incoming-message integration.

A keyboard accepts 1–10 options with nonempty labels and values; values must be unique within that keyboard. Each keyboard can be answered once. After a selection, its buttons become inactive across the user’s devices, and the original message records keyboard.selected.

Images and files

Bots can send up to four attachments in one message, with an optional text caption. Supported images are PNG, JPEG, GIF, and WebP up to 5 MiB each. Supported files are PDF, ZIP, and plain text up to 10 MiB each.

Upload the file to the target session first with POST /session/{id}/attachment using a bot Bearer token and the raw file body. Then include the returned attachment ID in the message’s attachments array:

{
  "sessionID": "USER_SESSION_ID",
  "content": "Here is your weekly report.",
  "attachments": ["UPLOADED_ATTACHMENT_ID"]
}

Attachment IDs must belong to the same conversation and cannot already be attached to another message. A message may omit text when it contains an attachment. Broadcasts do not support attachments, and users cannot upload files to the bot.

Commands

Declare supported commands on your bot’s profile so users can discover actions such as /help or /report. A command sends its configured value as a user message; your bot handles it and sends a response.

The SDKs route registered command values to command handlers. A button answer can also trigger a command when its value matches a registered command value. Declaring a command makes it available to users; implement its behavior in your bot code.

Send to one user

Direct messages suit personal alerts, reports, and reminders. Send to your own chat for internal tools, or target another connected user’s session for updates specific to them.

The HTTP integration defaults to the owner’s chat when you omit sessionID. Include that field to choose another conversation.

Send to everyone

A broadcast sends a separate copy of a message to every existing conversation with your bot, including the owner’s if it exists. Use it for announcements or updates shared by your audience.

BotComm queues the send as a background job. Users receive the message in their own chats, and any replies remain in those individual conversations.

Broadcasts allow one request per minute and 24 per day per bot. See the HTTP broadcast example for the request and response.

Build a two-way conversation

A bot can receive text, handle commands, and reply in the same session. For example, a user sends a question, your service prepares an answer, and the bot posts the response back to that conversation.

The Go, Python, JavaScript, and Rust SDKs handle authentication, a live event stream, reconnects, and recovery of unread messages. Run your bot process to listen for incoming messages and route them to your application’s handlers.

Handle button answers and commands alongside ordinary text messages to guide users through your workflow.

The HTTP sending guide covers outgoing messages. For receiving events and implementing handlers, explore the SDK examples on GitHub ↗.

Chat messages and notifications

Messages are saved in chat history and delivered to connected apps. Push notifications depend on the user’s device permissions, chat mute setting, and whether the message was already read.

Set silent: true when an update should appear in chat without a push notification. A successful send confirms that the message was saved or a broadcast was queued; it does not mean the user has read it.