Skip to main content
All endpoints in this family authenticate with X-AgentFlow-Bot-Token and proxy to the Matrix Client-Server API under the hood.

​
POST /api/v1/sendMessage

Send m.text to a room the bot has joined. 
curl -X POST https://bots.agentflow.website/api/v1/sendMessage \
  -H "X-AgentFlow-Bot-Token: $AF_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "room_id": "!abc:agentflow.website",
    "text": "Hello, **world**",
    "markdown": true
  }'

​
Request

FieldTypeRequiredDescription
room_idstringyesMatrix room id starting with !
textstringyesmessage body, max 40 000 chars
markdownboolnorender **bold**, *italic*, `code`, line breaks
reply_tostringnoevent_id to reply to (Matrix m.in_reply_to)

​
Response

{ "ok": true, "event_id": "$abc123:agentflow.website" }
Use event_id for follow-ups (edit, redact, react).

​
Errors

StatusBody errorMeaning
400invalid_bodyschema validation failed (check detail)
403forbiddenbot is not in this room — call /api/v1/joinRoom first
404room_not_found
502send_failedupstream Matrix returned 5xx — retry safe

​
TypeScript

import { BotClient } from '@agentflowx/bot-sdk';
const bot = new BotClient({ token: process.env.AF_BOT_TOKEN! });

const { event_id } = await bot.sendMessage({
  room_id: '!abc:agentflow.website',
  text: 'Hello, **world**',
  markdown: true,
});

​
Python (planned v0.2)

from agentflowx import BotClient
bot = BotClient(token=os.environ['AF_BOT_TOKEN'])

event_id = await bot.send_message(
    room_id='!abc:agentflow.website',
    text='Hello, **world**',
    markdown=True,
)

​
POST /api/v1/joinRoom

Bot joins a room by id or alias. 
curl -X POST https://bots.agentflow.website/api/v1/joinRoom \
  -H "X-AgentFlow-Bot-Token: $AF_BOT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "room_id_or_alias": "#lobby:agentflow.website" }'

​
Response

{ "ok": true, "room_id": "!abc:agentflow.website" }
The bot has to be either:
  • already invited to the room (DM, manual invite), OR
  • joining a public-discoverable room by alias

​
Coming soon (v0.2)

  • POST /api/v1/sendPhoto — upload + send m.image
  • POST /api/v1/sendDocument — m.file
  • POST /api/v1/editMessage — m.replace relation
  • POST /api/v1/deleteMessage — redact
  • POST /api/v1/setReaction — annotate with emoji
  • POST /api/v1/inviteUser
  • GET /api/v1/rooms / GET /api/v1/rooms/:id/members
Tracked in bot-platform issues.