SDK reference

Every mini app page has a global th object. Every method returns a Promise.

th.ready()

Resolves once the app is connected. Call it first.

const info = await th.ready();
// { app: { slug, name }, user: { name }, lang: "zh-CN" }

user.name is the name on the person's account, or null. Apps never receive an email address.

th.chat.send(options)

Sends one message in your app's conversation and resolves with the full reply.

const r = await th.chat.send({
  text: "Translate this menu into Chinese.",   // required, up to 8,000 characters
  images: [photoDataUrl],                      // optional, up to 4 pictures
  onDelta: (text) => { /* each new piece of the reply */ },
  onImage: ({ url }) => { /* a picture, as soon as it is ready */ },
});
// r = { text, images: [url, ...], messageId }

• The conversation remembers. Each message sees the earlier ones, so a follow-up question works. Start over with th.chat.reset().
• Your app's instructions (set in the dashboard) are given to the model before the conversation, like a chat's own instructions.
• Pictures. Ask for one in plain words ("draw a photo of …") and the reply carries it in images — ready to put in an <img>.
• Structured answers. Ask for JSON in your text, then read it with th.util.parseJson(r.text).
• Photos in. images takes JPEG, PNG, WebP or GIF data URLs, each under 1 MB. th.media.pickImage() gives you one of the right size.
• One message is answered at a time; a second send waits for the first.
• Errors reject with an Error whose code says why — for example rate_limited, or a daily limit being reached. Show error.message to the user; it is written for them.

th.chat.reset()

Forgets the conversation. The next send starts a new one.

th.media.pickImage(options)

Opens the camera or photo library and resolves with a JPEG data URL, or null if the person cancelled. Call it from a tap or click.

const photo = await th.media.pickImage({ camera: true });   // camera: open the camera on phones
if (photo) await th.chat.send({ text: "What is in this picture?", images: [photo] });

Options: camera (default false), maxSide (default 1600 pixels), quality (default 0.82).

th.storage.get(key) / th.storage.set(key, value)

Keeps a little JSON on the person's device, visible only to your app.

await th.storage.set("prefs", ["no spicy food"]);
const prefs = await th.storage.get("prefs");   // null if never set

Keys are 1–64 letters, digits, _, . or -. A value can be up to 200 KB of JSON.

th.util.parseJson(text)

Finds the first JSON object or array in text and parses it, ignoring code fences and anything around it. Returns null if there is none.

Limits