Skip to content
WM KeyboardWM Keyboard
Accessibility

The internet and AI

Call web APIs with http, keep keys in secrets, let users point at their own server, and ask the user's AI model.

A plugin can call web APIs and the AI model the user set up in the keyboard. Both are risky permissions: the user sees them before install, and they stay off until the user turns them on for your plugin.

Two lines in the manifest:

plugin.json (excerpt)
"permissions": ["network"],
"hosts": ["api.open-meteo.com", "*.openfoodfacts.org"]
  • hosts lists every website your plugin may reach. Write only the name: no https://, no port, no path. *.example.com covers example.com and every name under it. Up to 16.
  • A plugin with network and no hosts is refused at install, unless it has a host setting.

In the editors, risky permissions count as allowed so you can test. After a real install, each call raises PermissionError until the user turns network on. When that happens, the keyboard shows the permission in your panel with an Allow button that leads the user to the switch. They also need risky permissions allowed for plugins as a whole:

WM Keyboard  Tools  Plugins  Allow risky permissions

The http module looks like the popular requests library:

from wm import http
r = http.get("https://api.open-meteo.com/v1/forecast",
params={"latitude": 23.8, "longitude": 90.4, "current": "temperature_2m"})
r.raise_for_status()
temp = r.json()["current"]["temperature_2m"]
CallSends
http.get(url, params=, headers=)a GET request; params become ?a=1&b=2
http.post(url, json=)a JSON body
http.post(url, data={"a": "1"})a form
http.post(url, data="text") or data=b"..."text or bytes as they are
http.post(url, data={"a": "1"}, files={"photo": ("front.jpg", jpeg, "image/jpeg")})a multipart form, the way a web page uploads a file
http.put, http.patch, http.deletethe same, with that method
http.request(method, url, ...)any method

Every call also takes headers=, timeout= (15 seconds at most) and binary=True (keep the reply’s bytes for a picture or a file). A Content-Type you put in headers is sent as it is, so data=png_bytes with headers={"Content-Type": "image/png"} uploads a picture.

A value in files is (name, bytes, type), (name, bytes), plain bytes, or the dict that files.pick and files.photo give, so a picture the user took goes straight on:

files.photo(then=lambda photo: http.post(UPLOAD, data={"code": code}, files={"image": photo}, then=sent))

What you get back is a Response:

r.status_code200, 404 and so on
r.okTrue when the status is under 400
r.textthe body as text
r.json()the body read as JSON
r.contentthe body as bytes
r.headersa dict, with lowercase names
r.urlthe address that answered, after redirects
r.raise_for_status()raises http.HTTPError for 400 and up, else gives back r
ErrorMeans
PermissionErrornetwork is not in the manifest, the host is not in hosts, or the user has not turned network on
ConnectionErrorno connection, the server could not be reached, or Data saver is on
TimeoutErrorno answer in time
http.HTTPErrorfrom raise_for_status(); e.response is the Response

Catch them and tell the user. A plugin that lets an error escape stops, and the panel shows the error instead of your interface:

try:
r = http.get(URL, params={"q": query})
r.raise_for_status()
except PermissionError:
state.error = "Allow internet access to search."
except (ConnectionError, TimeoutError) as e:
state.error = f"No connection: {e}"
except http.HTTPError as e:
state.error = f"The server said {e.response.status_code}."

http.get(url) waits for the answer, and the panel cannot react while it waits. Pass then= and the call returns at once:

def search():
state.busy = True
http.get(URL, params={"q": state.query}, then=got, on_error=failed)
def got(r):
state.busy = False
state.results = r.json()["items"] if r.ok else []
def failed(error):
state.busy = False
state.error = str(error)

The keyboard calls got with the Response when it arrives, then draws the panel again. If anything goes wrong, it calls failed with the exception instead, even when the keyboard refused to send the request at all (the internet not allowed, Data saver on, a host not in your list). Without on_error, a refusal raises right at the call, and a later failure raises when the answer arrives. Show ui.progress() while state.busy is true. The tutorial builds this step by step.

  • https only. No IP addresses and no localhost, except the user’s own server on the local network (below).
  • Every redirect is checked against hosts again.
  • Replies up to 1 MB. 15 seconds at most. 60 requests a minute.
  • Nothing is sent while Data saver is on.
  • Each request shows in the keyboard’s Network activity under your plugin’s name, so the user can see what you sent and where.
  • No cookies are kept between requests.
  • The User-Agent is WMKeyboard-Plugin, your plugin’s id and its version, such as WMKeyboard-Plugin com.example.weather/1.0.0. Services that ask apps to name themselves, such as Open Food Facts, Nominatim and Wikipedia, can tell your plugin apart. You cannot change it.

Some services need a key. Never put yours in the plugin: anyone can unzip a .wmplugin and read it. Let the user paste their own.

The simplest way is a secret setting. The app draws the row on your plugin’s page with a hidden box, and you read the key like any other setting:

plugin.json (excerpt)
"permissions": ["network", "storage"],
"settings": [
{"key": "api_key", "type": "secret", "label": "API key"}
]
from wm import plugin, ui, http
def render():
if not plugin.settings.api_key:
ui.empty("Add your API key on this plugin's settings page.", icon="key")
return
...

The key is kept in secrets, which never appears in backups or the storage inspector. secrets needs the storage permission.

You can also ask for the key inside your panel and save it with secrets yourself. Saved under the same name as a secret setting, it shows on the page as saved:

from wm import plugin, ui, http, secrets
state = plugin.state(api_key=secrets.get("api_key", ""))
def save_key(text):
secrets.set("api_key", text.strip())
state.api_key = text.strip()
def render():
if not state.api_key:
ui.input(label="Your API key", kind="password", on_submit=save_key)
return
...
def search(q):
return http.get(URL, params={"q": q}, headers={"Authorization": "Bearer " + state.api_key})

For a self-hosted service (a home server, a company instance), you cannot know the address. Add a host setting. The app draws a box for it on your plugin’s page, and the website the user types there is added to your hosts:

plugin.json (excerpt)
"permissions": ["network"],
"settings": [
{"key": "server", "type": "host", "label": "Your server"}
]

The user may type a bare name (money.example.com) or a whole address with a port and a path (https://money.example.com:8443/firefly). Only the host is checked, so build your addresses from what they typed:

def base_url():
text = plugin.settings.server.strip().rstrip("/")
if "://" not in text:
text = "https://" + text
return text
r = http.get(base_url() + "/api/items")

Many self-hosted services are reached at home as http://192.168.1.20:8080 or http://nas:9283. Add network.local to reach a server like that:

plugin.json (excerpt)
"permissions": ["network", "network.local"],
"settings": [
{"key": "server", "type": "host", "label": "Your server",
"summary": "Like https://money.example.com or http://192.168.1.20:8080"}
]

It is a risky permission with its own warning, and it covers only the server the user typed: a private IP address, a one-word name, or a name ending in .local, .lan, .home, .home.arpa, .internal or .localdomain. There, plain http works too. Until the user turns it on, a request to that server raises PermissionError.

The web editor cannot reach local servers, because browsers block a page from doing so; a request there raises ConnectionError. Test those on the phone, or with mock answers in automatic tests.

With the ai permission, your plugin can ask the AI model the user chose in the keyboard’s settings. That may be a model on the phone or a provider they signed in to. You never see their key or which provider it is.

from wm import ai
reply = ai.ask("Write a short, friendly reply to: " + text,
system="You write short text messages.")
CallDoes
ai.ask(prompt, system=, max_tokens=)waits, and returns the reply as text
ai.ask(prompt, then=fn, on_error=fn)returns at once; fn gets the reply
ai.stream(prompt, on_chunk=fn, then=done)fn gets each piece of the reply as it is written; done gets the whole reply
ai.available()whether the user has a model set up

Models are slow, so prefer then= or ai.stream. Streaming feels fastest:

def write():
state.reply = ""
ai.stream(state.prompt, on_chunk=add_piece)
def add_piece(piece):
state.reply += piece

ai raises RuntimeError when no model is set up, and ConnectionError when Data saver is on. Check ai.available() first and show a hint instead of a broken button.

The web editor sends real requests from your browser to your hosts. A browser can read the answer only if the website allows other pages to read it (CORS). Many public APIs do. If one does not, the console says so; the phone has no such limit.

The web editor has no AI model. ai.ask and ai.stream answer with a pretend reply of the same shape, and the console marks it, so your code paths still run. Install the plugin to try a real model.