Skip to content
WM KeyboardWM Keyboard
Accessibility

Answering for a provider list

Make your plugin a web search engine, a translator, a dictionary, a GIF source, a music recogniser or a voice engine the keyboard's own tools can use.

Many of the keyboard’s tools ask a provider list: web search asks Brave, SearXNG or the Built-in search, translate asks DeepL or Google, and so on (see Provider lists). A plugin can add rows to those lists. The tool then asks your plugin the same way it asks any other provider. It sends a request, you send results back, and the tool draws them as its own.

This works for these lists:

toolThe listYou getYou return
searchWeb search, and its Images tab with "images": truea queryresults
translateTranslatetext and two languagesthe translation
dictionaryDictionarya wordentries
synonymsSynonymsa wordwords
vocab_autofillVocabulary’s look-upa worda vocabulary record
currency_fiat, currency_cryptoCurrency ratesa baserates
grammarGrammartext and a languageproblems found
gif, stickerGIFs and stickersa querypictures by address
ocrOnline text readinga photoits text
musicMusic IDa sound clipthe song
voiceVoice typinga sound clipits words

The AI list, smart homes, the sticker generator, photo translation, the speed test and background photos are not on it.

List each provider in plugin.json, then answer it with @plugin.provider(tool, id). A plugin can offer up to 8.

plugin.json
{
"format": "wmkeyboard-plugin",
"id": "com.example.wikisearch",
"name": "Wiki search",
"pluginVersion": "1.0.0",
"apiVersion": 5,
"panel": false,
"permissions": ["network"],
"hosts": ["en.wikipedia.org"],
"providers": [
{"tool": "search", "id": "wiki", "name": "Wikipedia titles", "summary": "Article titles only"}
]
}
FieldRequiredMeaning
toolyesOne of the lists in the table above.
idnoLowercase letters, digits, - and _. The tool’s name when left out. Unique for its tool.
namenoThe row’s name in the list. Your plugin’s name when left out.
summarynoOne line under the name in the Add a provider sheet.
imagesnoFor search only: the Images tab asks you too.

A plugin with providers and nothing else sets "panel": false. It needs no panel and no selection actions.

main.py
from wm import plugin, http
@plugin.provider("search", "wiki")
def search(request):
reply = http.get("https://en.wikipedia.org/w/api.php", params={
"action": "opensearch", "format": "json", "limit": request["count"], "search": request["query"],
})
_, titles, _, links = reply.json()
return [{"title": t, "url": u} for t, u in zip(titles, links)]

The function gets the request as a dict and returns plain data: dicts, lists, strings, numbers and None. Returning None or an empty list means “nothing found”, and the list asks its next row.

Installing a plugin adds nothing to any list. The user adds your row on the plugin’s page, under Providers, or from the list’s own Add a provider sheet, where your provider appears by name. From then on the list asks it in its turn: in fallback order only after the rows above it fail or find nothing, and first when the user moves it up or picks it in the panel.

If the plugin is switched off or removed, the row stays in the list and reads “Its plugin is off or removed”. It isn’t asked until the plugin is back.

Each call starts a fresh copy of your script, calls your function once and ends. It has the same limits as a selection action: about 3 seconds of your own work, with time spent waiting on http not counted. Storage and secrets work. Nothing that needs the field (field, clipboard, share) does, because the user is busy in the tool, not in your panel.

network is a risky permission, so it does nothing until the user turns it on on your plugin’s page. Until then a call that uses http fails, and the list moves on to its next row. Data saver, the hosts list and the network log apply as they do everywhere else; see Internet and AI.

An exception you raise ends the call. The list moves on and, when nothing else answers, shows your message, so make it one a user can read: raise RuntimeError("The service is busy, try again in a minute").

Every reply below can also be the list on its own when the shape is “an object with a list in it”. Fields marked ? may be left out. An item without its address, or with one that isn’t http or https, is skipped.

# request
{"kind": "web", "query": "cats", "count": 10, "safe": True, "page": 0}
{"kind": "images", "query": "cats", "count": 30, "safe": True, "page": 0} # with "images": true
# reply, web
{"results": [{"title": "...", "url": "https://...", "snippet": "...", "thumbnail?": "https://..."}],
"answer?": "a short answer, drawn above the results"}
# reply, images
[{"image": "https://...", "thumb?": "https://...", "title?": "...", "page?": "https://...", "mime?": "image/png"}]

page counts from 0, for More results. Each result shows your row’s name as the engine that found it.

{"text": "Good morning", "to": "de", "from": "auto"} # request
"Guten Morgen" # reply, or {"text": "...", "from": "en"}
{"word": "serene"} # request; vocab_autofill adds "translations": ["de", "bn"]
# dictionary reply: entries
[{"word": "serene", "phonetic?": "/səˈriːn/", "audio?": "https://...",
"meanings": [{"pos": "adjective",
"definitions": ["calm and untroubled", {"definition": "...", "example?": "..."}],
"synonyms?": ["calm"]}]}]
# synonyms reply
["calm", "peaceful"] # or {"groups": [{"pos?": "adj", "sense?": "...", "words": [...]}]}

vocab_autofill takes the dictionary reply, or a vocabulary record as a pack stores it ({"word", "senses": [{"pos", "definition", "example"}], ...}).

{"base": "USD"} # fiat request
{"base": "EUR", "rates": {"USD": 1.08, "GBP": 0.85}} # reply: units of each for one of the base
{"base": "USD", "codes": ["BTC", "ETH"]} # crypto request
{"BTC": 65000.0, "ETH": 3100.0} # reply: each coin's price in US dollars

A fiat reply against another base needs USD among its rates, so the keyboard can turn it into dollars.

{"text": "Their is a cat.", "language": "en-US"} # request
[{"start": 0, "end": 5, "message": "Did you mean “There”?", "suggestions": ["There"],
"title?": "Wrong word", "rule?": "THEIR_THERE"}]

start and end count UTF-16 code units, as Kotlin and JavaScript strings do; for most text that is one per character. Grammar rows are never asked in a password field or incognito, and Data saver holds them like a server.

{"query": "happy", "kind": "gif", "limit": 24, "safe": True} # "kind" is "sticker" for the sticker list
[{"url": "https://...gif", "preview?": "https://...", "width?": 200, "height?": 150,
"title?": "...", "creator?": "...", "mime?": "image/gif"}]
{"image": "<base64 JPEG>", "mime": "image/jpeg"} # request
"the text in the photo" # reply, or {"text": "..."}
{"audio": "<base64>", "encoding": "pcm16le", "sampleRate": 16000, "channels": 1,
"language?": "en"} # voice sends the dictation language
# music reply
{"title": "...", "artist": "...", "album?": "...", "year?": "...", "art?": "https://...",
"links?": {"spotify": "https://..."}} # None for no match
# voice reply
"what was said" # or {"text": "..."}

audio is the clip as 16-bit little-endian samples, mono. Decode it with base64.b64decode. A voice row is asked the way a transcription server is: once the user stops, with the whole clip.

In the plugin editor, on the phone or the web, the Try tab calls your provider with the request its list sends and shows the reply, with whether the list can read it. The editor also offers request[" keys as you type, flags a provider plugin.json does not declare, and writes a stub for one it declares that nothing answers.

wm-python-cli calls a provider the way the keyboard does: through transform, with the action id provider:<tool>/<id> and the request as JSON. The reply comes back wrapped as {"value": ...}.

test.py
import json, plugin_test
s = plugin_test.session(mock={"http.request": {"status": 200, "text": '["cats", ["Cat"], [""], ["https://en.wikipedia.org/wiki/Cat"]]'}})
s["load"]()
r = s["transform"](json.dumps({"kind": "web", "query": "cats", "count": 5, "safe": True, "page": 0}), "provider:search/wiki")
results = json.loads(r["value"])["value"]
assert results[0]["url"] == "https://en.wikipedia.org/wiki/Cat"

See Testing for the rest of plugin_test.

A provider reaches only the hosts your manifest lists, over https. What you do with a site is between you and that site: read its terms before you depend on its pages, prefer a published API where there is one, and expect markup you parse to change. Plugins come from wherever their author shares them, so a provider that reads a site’s pages lives in your plugin, not in the keyboard.