API reference

The local API of veilmesh-bot 0.1.0, at http://127.0.0.1:8471 by default.

`veilmesh-bot` is an end-to-end encrypted member of the VeilMesh groups its owner adds it to. It holds the bot's keys; this API lets your own software on the same machine read the groups' new messages and write into them. Only group chats: a bot has no one-to-one chats, calls or channels.

The API listens on a loopback address only (127.0.0.1 or ::1) and refuses connections from anywhere else. Every request under `/v1`, except `/v1/hello`, needs the bot's token (`veilmesh-bot token`) as `Authorization: Bearer <token>`. Before a client sends the token it should check `/v1/hello`: the daemon proves it holds the token, so a program that took the port while the daemon was down gets nothing. The client libraries do this.

Webhooks (`/hooks/...`) have no token: each belongs to one group and has its own secret (`veilmesh-bot hook add`).

Every answer is JSON. An error is `{"error": "<reason>"}` with an HTTP status: 400 a malformed request, 401 a missing or wrong token, 403 not allowed, 404 not found (an unknown group, endpoint or hook), 413 a body over 256 KiB, 502 the bot's core failed.

The spec this page is built from, for code generators and tools: openapi.yaml (OpenAPI 3.1).

Endpoints

GET /v1/hello

The daemon proves it holds the token. No token.

Answers HMAC-SHA256 of `veilmesh-bot-hello\0` followed by the nonce, keyed with the API token, in lower-case hex. A client computes the same and sends its token only when they match. No token is asked here.

Parameters

NameInType
nonce (required)querystring16 to 128 letters or digits, fresh and random for each check.

Responses

StatusFields
200The proof.proof: string
400Refused or failed.error: string

GET /v1/me

The bot's account. Needs the bot's token.

Responses

StatusFields
200The bot.veil_id: string | null, owner: string | null, online: boolean
401Refused or failed.error: string

GET /v1/groups

The groups the bot is in. Needs the bot's token.

Responses

StatusFields
200The groups.groups: Group[]
401Refused or failed.error: string

GET /v1/events

New events, by long-poll. Needs the bot's token.

The events after `after`, numbered from 1 on each start of the daemon (`run`). Waits up to `wait` seconds for one when there is none. The daemon keeps the last 1000; `oldest` tells a client what it missed. When `run` changes, the daemon restarted: read again from 0.

Parameters

NameInType
afterqueryintegerThe last event number seen; 0 for all kept.
waitqueryintegerSeconds to wait for an event, at most 60.

Responses

StatusFields
200The events.events: Event[], oldest: integer, next: integer, run: integer
401Refused or failed.error: string

GET /v1/commands

The commands the bot declares. Needs the bot's token.

Responses

StatusFields
200The commands.commands: Command[]
401Refused or failed.error: string

PUT /v1/commands

Declare the bot's commands. Needs the bot's token.

Members' apps list them when someone types `/` in a group; older apps get the list as a message. They go to every group the bot is in and to groups it joins later. An empty list withdraws them. Kept in `commands.json` of the bot's directory.

Body (application/json)

FieldType
commands (required)Command[]at most 32.

Responses

StatusFields
200Kept and declared.commands: Command[], groups: integer, failed: integer
400Refused or failed.error: string
401Refused or failed.error: string

POST /v1/groups/{group}/messages

Send a text into a group. Needs the bot's token.

Parameters

NameInType
group (required)pathstringA group of the bot (an id from `/v1/groups`).

Body (application/json)

FieldType
text (required)string
reply_tostringThe id of a message of this group to reply to.

Responses

StatusFields
200Sent.message: string
400Refused or failed.error: string
401Refused or failed.error: string
404Refused or failed.error: string
502Refused or failed.error: string

POST /v1/groups/{group}/files

Send a file into a group. Needs the bot's token.

Only files under the daemon's `--files-dir` (a path in it, or relative to it), by their real path once links are resolved. Without `--files-dir` no files are sent (403).

Parameters

NameInType
group (required)pathstringA group of the bot (an id from `/v1/groups`).

Body (application/json)

FieldType
path (required)string
captionstring

Responses

StatusFields
200Sent.message: string
400Refused or failed.error: string
401Refused or failed.error: string
403Refused or failed.error: string
404Refused or failed.error: string
502Refused or failed.error: string

POST /v1/groups/{group}/reactions

React to a message of a group (again to take it back). Needs the bot's token.

Parameters

NameInType
group (required)pathstringA group of the bot (an id from `/v1/groups`).

Body (application/json)

FieldType
message (required)string
emoji (required)string

Responses

StatusFields
200Done.
400Refused or failed.error: string
401Refused or failed.error: string
404Refused or failed.error: string
502Refused or failed.error: string

POST /v1/groups/{group}/leave

Leave a group. Needs the bot's token.

Parameters

NameInType
group (required)pathstringA group of the bot (an id from `/v1/groups`).

Responses

StatusFields
200Done.
401Refused or failed.error: string
404Refused or failed.error: string
502Refused or failed.error: string

POST /hooks/{group}/{secret}

Post a message into a group through its webhook. No token.

The body is the message: plain text, or JSON with a `text` field. An unknown group and a wrong secret answer the same 404.

Parameters

NameInType
group (required)pathstringA group of the bot (an id from `/v1/groups`).
secret (required)pathstring

Body (text/plain)

The message text.

Body (application/json)

FieldType
text (required)string

Responses

StatusFields
200Sent.message: string
400Refused or failed.error: string
404Refused or failed.error: string
502Refused or failed.error: string

POST /hooks/{group}

Post through a webhook, the secret in a header. No token.

The same as `/hooks/{group}/{secret}`; the secret stays out of URLs and access logs.

Parameters

NameInType
group (required)pathstringA group of the bot (an id from `/v1/groups`).
X-VeilMesh-Hook-Secret (required)headerstring

Body (text/plain)

The message text.

Body (application/json)

FieldType
text (required)string

Responses

StatusFields
200Sent.message: string
400Refused or failed.error: string
404Refused or failed.error: string
502Refused or failed.error: string

Objects

Group

FieldType
id (always)string
title (always)string
members (always)integer
closed (always)booleanRead-only: the group was closed.

Command

FieldType
name (always)string1 to 32 of a-z, 0-9 and _; a leading slash and capitals are accepted.pattern ^/?[A-Za-z0-9_]{1,32}$.
descriptionstringup to 100 characters.
argsstringA hint for the arguments, e.g. `SERVICE`.up to 32 characters.

MessageEvent

FieldType
type (always)"message"
seq (always)integer
group (always)string
message (always)stringThe message's id.
authorstringThe author's name as the bot knows it.
text (always)string
sent_atintegerUnix milliseconds.
filestring | nullAn attached file's name.

StatusEvent

FieldType
type (always)"status"
seq (always)integer
group (always)string
message (always)string
status (always)stringThe delivery state of one of the bot's messages.

GroupAddedEvent

FieldType
type (always)"group_added"
seq (always)integer
group (always)string
titlestring | null

GroupRemovedEvent

FieldType
type (always)"group_removed"
seq (always)integer
group (always)string