Anything that can make an HTTP request can post to a Gná conversation and read the replies:
a shell script, a cron job, Home Assistant, a camera, a bot in any language. This guide covers
everything an integration can do. The examples use https://api.gna.rymdvarel.se; use your own
server's address.
Gná is named after the messenger of Norse mythology who carries Frigg's errands between the
worlds. In code and URLs the name is written gna.
Each conversation has its own tokens. Create one in the app (the conversation's settings,
New token) or with gna token create on the server. The token is shown once; it starts with
gna_. Send it with every request:
Authorization: Bearer gna_…
The token decides the conversation, so requests never name one. A bot holding a token sees only that conversation.
Give each bot or script its own token, named after it. You can then revoke one without breaking the others, and the app shows which token sent each message. Revoking a token, or deleting the conversation, makes every request with it fail with 401.
To check a token and see its conversation:
curl -H "Authorization: Bearer $GNA_TOKEN" https://api.gna.rymdvarel.se/me
{
"kind": "integration",
"token": {"id": "tok_lusab-babad", "name": "garage script", "send_only": false,
"created_at": "2026-11-21T10:00:00Z", "last_used_at": "2026-11-21T10:05:00Z",
"revoked_at": null},
"conversation": {"id": "conv_gutih-tugad", "name": "Garage", "encrypted": false}
}
POST /messages with a JSON body:
curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
-d '{"text": "Backup finished: 42 GB in 18 minutes"}' \
https://api.gna.rymdvarel.se/messages
The answer (201) is the stored message; its id is what replies and button presses refer to.
Messages from integrations appear under the conversation's name; sender.token_name says which
token sent it.
| Field | Type | Default | Meaning |
|---|---|---|---|
text |
string, 1–4096 characters | The message. Plain text; line breaks are kept. | |
silent |
boolean | false |
Notify without sound, and without lighting up the screen. |
reply_to |
message ID | Show the message as a reply, quoting that message. It must be in this conversation. | |
buttons |
rows of buttons | [] |
See Buttons. |
buttons_single_use |
boolean | true |
See Buttons. |
notification_buttons |
"ok", "yes_no", "ok_cancel" |
See Buttons in notifications. | |
attachments |
attachment IDs, at most 10 | [] |
Images uploaded earlier. See Images. |
image_url |
URL | An image for the server to fetch. See Images. |
A message needs text, an image, or both. Unknown fields are rejected, so a typo fails instead
of being ignored.
The phone gets a notification, titled with the conversation's name, unless the user has muted the conversation or has the app open.
Buttons are rows: up to 8 rows of up to 8 buttons each.
curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
-d '{"text": "Front door is unlocked. Lock it?",
"buttons": [[{"label": "Lock", "data": "lock"}, {"label": "Ignore", "data": "ignore"}],
[{"label": "Open camera", "url": "https://camera.example.com/front"}]]}' \
https://api.gna.rymdvarel.se/messages
Each button has a label (1–64 characters) and exactly one of:
data (1–256 characters): a callback button. Pressing it sends your bot a callback
event carrying this data (see Receiving). Put in it
whatever your bot needs to act, such as "lock" or "approve:1234".url (http or https): a link button. The app opens the link; your bot is not told.Callback buttons are single-use by default: after the first press the app shows which one
was chosen and disables them all, so a double tap cannot lock and unlock the door. With
"buttons_single_use": false they stay pressable and every press reaches your bot.
A message with callback buttons nobody has pressed stays on the server for up to 7 days (see What the server keeps), so the button still works when the user gets to it.
iOS only shows buttons in a notification if the app registered them beforehand, with fixed
labels. Gná has three sets. Choose one with notification_buttons, and put matching callback
buttons first in the first row:
notification_buttons |
Notification shows | Needs, at the start of the first row |
|---|---|---|
"ok" |
OK | 1 callback button |
"yes_no" |
Yes, No | 2 callback buttons |
"ok_cancel" |
OK, Cancel | 2 callback buttons |
The notification's first action presses the first button, the second the second. Inside the app
the message shows your own labels and all its buttons. Without notification_buttons, the
notification offers Reply, which sends a text reply to your message.
{"text": "Garage door has been open for 30 minutes. Close it?",
"notification_buttons": "yes_no",
"buttons": [[{"label": "Close", "data": "close"}, {"label": "Leave open", "data": "leave"}]]}
JPEG, PNG, GIF and WebP, up to 20 MB and 50 megapixels (the server's operator can change both). The server checks that the file really is an image, removes metadata such as GPS location, and makes a thumbnail for notifications. There are three ways to send one.
With the message, in one request (multipart; the file field is image):
curl -H "Authorization: Bearer $GNA_TOKEN" \
-F text="Motion at the front door" -F image=@snapshot.jpg \
https://api.gna.rymdvarel.se/messages
The other form fields are silent, reply_to, buttons (as a JSON string),
buttons_single_use and notification_buttons.
Upload first, then refer to it (the file field is file), for example to send several
images in one message:
curl -H "Authorization: Bearer $GNA_TOKEN" -F file=@front.jpg https://api.gna.rymdvarel.se/attachments
# → {"id": "att_…", "content_type": "image/jpeg", "width": 1920, "height": 1080, …}
curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
-d '{"text": "Both doors", "attachments": ["att_…", "att_…"]}' \
https://api.gna.rymdvarel.se/messages
An upload that is not used in a message within an hour is deleted.
Let the server fetch it with image_url. Useful for a camera's snapshot URL: the camera
needs no extra step, and the phone never contacts it.
curl -H "Authorization: Bearer $GNA_TOKEN" -H "Content-Type: application/json" \
-d '{"text": "Motion at the front door", "image_url": "http://192.168.1.50/snapshot.jpg"}' \
https://api.gna.rymdvarel.se/messages
The server fetches the image while handling your request (5 seconds at most, following up to 3
redirects on the same host). Private network addresses such as 192.168.… are only fetched if
the conversation's Allow internal URLs setting is on, which the server's operator can
forbid; localhost and link-local addresses never are.
If fetching fails the message is still sent, with its text, and image_fetch_error in the
answer says why: invalid_url, dns_failed, blocked_address (an internal address the
conversation does not allow), redirect_blocked, too_many_redirects, timeout,
connection_failed, http_error, too_large, invalid_image, unsupported_image_type,
image_too_large, processing_failed or fetch_failed.
Your bot asks GET /updates for what happened after the last event it has seen. The request
waits until something happens, or until timeout seconds have passed (a long-poll), so a bot
reacts at once without hammering the server.
curl -H "Authorization: Bearer $GNA_TOKEN" \
"https://api.gna.rymdvarel.se/updates?after=0&timeout=30"
Here the user replied to a question and then pressed its Lock button (messages trimmed to
the interesting fields; they carry the same fields as the answer to POST /messages):
{
"events": [
{
"id": 4813,
"type": "message",
"conversation_id": "conv_gutih-tugad",
"message": {
"id": 4813,
"sender": {"kind": "user", "name": "Johan", "token_id": null, "token_name": null},
"text": "Lock it",
"reply_to": {"id": 4812, "sender": "Garage", "excerpt": "Front door is unlocked. Lock it?",
"has_image": false, "deleted": false},
"attachments": []
},
"callback": null
},
{
"id": 4815,
"type": "callback",
"conversation_id": "conv_gutih-tugad",
"message": {
"id": 4812,
"text": "Front door is unlocked. Lock it?",
"buttons_disabled": true,
"pressed": {"row": 0, "col": 0, "label": "Lock", "pressed_at": "2026-11-21T10:06:12Z"}
},
"callback": {
"message_id": 4812, "row": 0, "col": 0, "label": "Lock", "data": "lock",
"user": {"id": "acc_lusab-babad", "name": "Johan"},
"pressed_at": "2026-11-21T10:06:12Z"
}
}
],
"next": 4815
}
Then ask again with after set to next. An empty events list means the wait ran out; ask
again with the same after.
There are two kinds of event:
message: the user wrote in the conversation. message.reply_to is set when they replied to
one of your messages, which tells you which question they are answering. Images they send are
in message.attachments; download them with your token from the url (or the smaller
thumb_url) given there, relative to the server's address.callback: the user pressed one of your callback buttons. callback.data is the button's
data; message is the message the button is on.Your own messages are not included.
| Parameter | Default | Meaning |
|---|---|---|
after |
0 |
Return events with an ID above this. |
timeout |
30 | Seconds to wait when nothing has happened yet. At most 60; 0 answers at once. |
limit |
100 | Most events per answer (1–500). |
Set your HTTP client's timeout longer than timeout, say 40 seconds for timeout=30.
While your bot is waiting on /updates, the app shows it as online.
Asking for what follows after tells the server you have handled everything up to it. Keep
next somewhere that survives a restart (a file is enough). A bot that starts again from
after=0 receives, a second time, every event the server still has.
Gná relays messages; the app keeps the history. The server deletes a message 10 minutes after
the user's devices and every bot reading the conversation have fetched it, and after 7 days in
any case. So /updates brings what is new, not the conversation's history.
A read token holds messages back until its bot has fetched them, as long as the token has been used in the last 7 days. A token that is not used for 7 days, or a send-only token, does not.
GET /messages (same parameters, read tokens only) returns everything in the conversation
instead, your own messages included, plus message_updated events when a message changes (for
example when its buttons are pressed). Most bots want /updates.
No libraries needed. Set GNA_TOKEN, and run it: it asks whether to lock the door, answers the
button, and answers ping with pong.
"""A minimal Gná bot."""
import json
import os
import pathlib
import time
import urllib.error
import urllib.request
SERVER = "https://api.gna.rymdvarel.se"
TOKEN = os.environ["GNA_TOKEN"]
CURSOR = pathlib.Path("gna-cursor.txt")
def call(method, path, body=None, timeout=10):
request = urllib.request.Request(
SERVER + path,
data=None if body is None else json.dumps(body).encode(),
method=method,
headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"},
)
with urllib.request.urlopen(request, timeout=timeout) as response:
return json.load(response)
def send(text, **fields):
return call("POST", "/messages", {"text": text, **fields})
def handle(event):
message = event["message"]
if event["type"] == "callback":
if event["callback"]["data"] == "lock":
send("Locked.", reply_to=message["id"])
else:
send("Leaving it unlocked.", reply_to=message["id"])
elif (message["text"] or "").strip().lower() == "ping":
send("pong", reply_to=message["id"])
def main():
after = int(CURSOR.read_text()) if CURSOR.exists() else 0
send(
"Front door is unlocked. Lock it?",
notification_buttons="yes_no",
buttons=[[{"label": "Lock", "data": "lock"}, {"label": "Ignore", "data": "ignore"}]],
)
while True:
try:
batch = call("GET", f"/updates?after={after}&timeout=30", timeout=40)
except urllib.error.HTTPError as error:
if error.code in (401, 403):
raise # Revoked or send-only token: retrying will not help.
time.sleep(5)
continue
except OSError: # Network trouble or a timeout: try again shortly.
time.sleep(5)
continue
for event in batch["events"]:
handle(event)
after = batch["next"]
CURSOR.write_text(str(after))
if __name__ == "__main__":
main()
Errors answer with an HTTP status and a body like:
{"error": "empty_message", "detail": "message needs text, attachments or image_url"}
error is a stable code to act on; detail is for people (for 422 it lists each problem with
the field it concerns).
| Status | error |
Meaning |
|---|---|---|
| 400 | empty_message |
Neither text nor an image. |
| 400 | invalid |
Something else is wrong, such as reply_to naming another conversation's message or notification_buttons without matching buttons; detail says what. |
| 400 | invalid_image, unsupported_image_type, image_too_large, processing_failed |
An uploaded file is not an image, not a supported type, has too many pixels, or could not be processed. |
| 401 | unauthorized |
Missing, unknown or revoked token, or the conversation was deleted. |
| 403 | send_only |
A send-only token tried to read. |
| 403 | forbidden |
The endpoint is for the app, not for tokens. |
| 413 | too_large |
The request or image is too big. |
| 415 | unsupported_media_type |
POST /messages takes application/json or multipart/form-data. |
| 422 | validation_error |
The body does not match the fields above. |
| 429 | demo_limit |
Demo accounts only: too many messages this hour. |
Retry on network errors and 5xx, with a pause. Do not retry 4xx unchanged: the same request fails the same way.
| What | Limit |
|---|---|
text |
4096 characters |
| Buttons | 8 rows of 8; label 64 characters, data 256, url 2048 |
| Images per message | 10 |
| Image size | 20 MB and 50 megapixels by default |
image_url fetch |
5 seconds, 3 redirects on the same host |
Long-poll timeout |
60 seconds by default |
| Unused uploads | Deleted after an hour |
| Messages on the server | 10 minutes after delivery, 7 days at most |
The size, time and retention limits are defaults the server's operator can change.
A conversation created as encrypted rejects text: messages carry ciphertext, nonce and
key_version instead, and images are not supported yet. Encryption needs a client library, so
the examples here are for ordinary conversations.
Every endpoint, with its fields and answers, is in the server's OpenAPI description at
/openapi.json, which you can browse and try at /docs. Those
endpoints that need an app session rather than a token are for the Gná app.