Send a message.
With one request.

Quick start

1. Create a bot. Sign in to the web console, open Bots, and select New bot.
2. Save your credentials. Copy the Client ID and Client secret shown after creation. They are shown only once. Store them in your sending app’s server-side configuration.
3. Open your bot’s chat. BotComm creates your own chat when you create the bot. If you deleted that chat, connect to the bot again using its handle or share link.

Set these environment variables in your terminal, replacing the placeholders with your bot credentials:

export CLIENT_ID='YOUR_CLIENT_ID'
export CLIENT_SECRET='YOUR_CLIENT_SECRET'

Then send your first message:

curl --fail-with-body https://api.botcomm.app/message \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{"content":"Your deployment finished!"}'

A successful request returns 200 OK with the created message as JSON. Open your bot’s chat to see it. Push notifications depend on your device permissions and chat notification settings.

Choose a recipient

Omit sessionID to send to the bot owner’s chat. To send to another connected user, include the Session ID of their conversation with your bot.

Copy it from Chat Settings on web or iOS. A Session ID identifies a conversation, and must belong to the bot whose credentials you use.

curl --fail-with-body https://api.botcomm.app/message \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{"sessionID":"YOUR_SESSION_ID","content":"Your report is ready."}'

An empty sessionID also selects the owner’s chat. An unknown session or a session belonging to another bot returns 404.

Broadcast a message

Set broadcast to true to send to everyone connected to your bot, including its owner.

curl --fail-with-body https://api.botcomm.app/message \
  --user "$CLIENT_ID:$CLIENT_SECRET" \
  --header 'Content-Type: application/json' \
  --data '{"broadcast":true,"content":"Hello everyone!"}'

This returns 202 Accepted with a broadcast job as JSON. Sending happens in the background; acceptance does not mean all recipients have received the message.

Broadcasts allow one request per minute and 24 per day per bot. These limits are shared with the token-authenticated broadcast endpoint. A broadcast cannot include a nonempty sessionID or attachments.

From your app

This server-side JavaScript example uses Node.js 18 or later and its built-in fetch. Set CLIENT_ID and CLIENT_SECRET in the process environment, then run it as an .mjs file.

const { CLIENT_ID, CLIENT_SECRET } = process.env;
if (!CLIENT_ID || !CLIENT_SECRET) {
  throw new Error("Set CLIENT_ID and CLIENT_SECRET");
}

const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64");
const response = await fetch("https://api.botcomm.app/message", {
  method: "POST",
  headers: {
    "Authorization": `Basic ${credentials}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Your deployment finished!" }),
  signal: AbortSignal.timeout(30_000),
});

if (!response.ok) {
  throw new Error(`BotComm HTTP ${response.status}: ${await response.text()}`);
}

const message = await response.json();
console.log(message.id);

Add sessionID, broadcast: true, or silent: true to the JSON body as needed. Other languages use the same URL, Basic auth credentials, and JSON payload.

Request reference

Send a JSON body with Content-Type: application/json and Authorization: Basic <base64(clientID:clientSecret)>. The fields below cover text messages.

Responses & limits

The endpoint allows 120 requests per minute per IP. Individual sends also share limits of 10 messages per 5 seconds per bot/session and 100 per 5 seconds per bot with token-authenticated message sends.

A successful response confirms that the message was saved or the broadcast was queued. It does not guarantee a device notification or that the user has read it. Retrying a send after a timeout can create a duplicate message.