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
| Name | In | Type | |
|---|
nonce (required) | query | string | 16 to 128 letters or digits, fresh and random for each check. |
Responses
| Status | | Fields |
|---|
200 | The proof. | proof: string |
400 | Refused or failed. | error: string |
GET /v1/me
The bot's account. Needs the bot's token.
Responses
| Status | | Fields |
|---|
200 | The bot. | veil_id: string | null, owner: string | null, online: boolean |
401 | Refused or failed. | error: string |
GET /v1/groups
The groups the bot is in. Needs the bot's token.
Responses
| Status | | Fields |
|---|
200 | The groups. | groups: Group[] |
401 | Refused 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
| Name | In | Type | |
|---|
after | query | integer | The last event number seen; 0 for all kept. |
wait | query | integer | Seconds to wait for an event, at most 60. |
Responses
| Status | | Fields |
|---|
200 | The events. | events: Event[], oldest: integer, next: integer, run: integer |
401 | Refused or failed. | error: string |
GET /v1/commands
The commands the bot declares. Needs the bot's token.
Responses
| Status | | Fields |
|---|
200 | The commands. | commands: Command[] |
401 | Refused 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)
| Field | Type | |
|---|
commands (required) | Command[] | at most 32. |
Responses
| Status | | Fields |
|---|
200 | Kept and declared. | commands: Command[], groups: integer, failed: integer |
400 | Refused or failed. | error: string |
401 | Refused or failed. | error: string |
POST /v1/groups/{group}/messages
Send a text into a group. Needs the bot's token.
Parameters
| Name | In | Type | |
|---|
group (required) | path | string | A group of the bot (an id from `/v1/groups`). |
Body (application/json)
| Field | Type | |
|---|
text (required) | string | |
reply_to | string | The id of a message of this group to reply to. |
Responses
| Status | | Fields |
|---|
200 | Sent. | message: string |
400 | Refused or failed. | error: string |
401 | Refused or failed. | error: string |
404 | Refused or failed. | error: string |
502 | Refused 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
| Name | In | Type | |
|---|
group (required) | path | string | A group of the bot (an id from `/v1/groups`). |
Body (application/json)
| Field | Type | |
|---|
path (required) | string | |
caption | string | |
Responses
| Status | | Fields |
|---|
200 | Sent. | message: string |
400 | Refused or failed. | error: string |
401 | Refused or failed. | error: string |
403 | Refused or failed. | error: string |
404 | Refused or failed. | error: string |
502 | Refused 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
| Name | In | Type | |
|---|
group (required) | path | string | A group of the bot (an id from `/v1/groups`). |
Body (application/json)
| Field | Type | |
|---|
message (required) | string | |
emoji (required) | string | |
Responses
| Status | | Fields |
|---|
200 | Done. | |
400 | Refused or failed. | error: string |
401 | Refused or failed. | error: string |
404 | Refused or failed. | error: string |
502 | Refused or failed. | error: string |
POST /v1/groups/{group}/leave
Leave a group. Needs the bot's token.
Parameters
| Name | In | Type | |
|---|
group (required) | path | string | A group of the bot (an id from `/v1/groups`). |
Responses
| Status | | Fields |
|---|
200 | Done. | |
401 | Refused or failed. | error: string |
404 | Refused or failed. | error: string |
502 | Refused 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
| Name | In | Type | |
|---|
group (required) | path | string | A group of the bot (an id from `/v1/groups`). |
secret (required) | path | string | |
Body (text/plain)
The message text.
Body (application/json)
| Field | Type | |
|---|
text (required) | string | |
Responses
| Status | | Fields |
|---|
200 | Sent. | message: string |
400 | Refused or failed. | error: string |
404 | Refused or failed. | error: string |
502 | Refused or failed. | error: string |
Objects
Group
| Field | Type | |
|---|
id (always) | string | |
title (always) | string | |
members (always) | integer | |
closed (always) | boolean | Read-only: the group was closed. |
Command
| Field | Type | |
|---|
name (always) | string | 1 to 32 of a-z, 0-9 and _; a leading slash and capitals are accepted.pattern ^/?[A-Za-z0-9_]{1,32}$. |
description | string | up to 100 characters. |
args | string | A hint for the arguments, e.g. `SERVICE`.up to 32 characters. |
MessageEvent
| Field | Type | |
|---|
type (always) | "message" | |
seq (always) | integer | |
group (always) | string | |
message (always) | string | The message's id. |
author | string | The author's name as the bot knows it. |
text (always) | string | |
sent_at | integer | Unix milliseconds. |
file | string | null | An attached file's name. |
StatusEvent
| Field | Type | |
|---|
type (always) | "status" | |
seq (always) | integer | |
group (always) | string | |
message (always) | string | |
status (always) | string | The delivery state of one of the bot's messages. |
GroupAddedEvent
| Field | Type | |
|---|
type (always) | "group_added" | |
seq (always) | integer | |
group (always) | string | |
title | string | null | |
GroupRemovedEvent
| Field | Type | |
|---|
type (always) | "group_removed" | |
seq (always) | integer | |
group (always) | string | |