App chats
Put a message in the user's composer, send one from a click, or start a new chat tagged with your app — chat.compose, chat.send, chat.create, chat.list and chat.open.
Your panel can talk to the user's chats in two ways. It can fill the composer, so the user reads the message and sends it. Or, from the user's own click, it can send. With app API 4 it can also create chats of its own: real chats, tagged with your app, that the user finds in the sidebar like any other.
| Method | What it does | Needs |
|---|---|---|
chat.compose | Fills the composer. Never sends. | — (prompt kits: requires.hostApi 4) |
chat.send | Sends a message as the user | A click |
chat.create | A new chat tagged with your app, opened, with the first message filled or sent | Grant chats, a click |
chat.list | The chats your app created in this project | Grant chats |
chat.open | Opens one of your app's chats | Grant chats, a click |
#Fill the composer
await app.chat.compose({
text: 'Turn the outline in notes/plan.md into a project brief.',
attachments: [exportRef], // refs/rels of your storage, or Blobs (up to 20)
});| Option | |
|---|---|
text | Text to put in the composer. |
attachments | Files: refs or rels from your own storage, or Blobs your page holds. Up to 20. |
promptId, values | Fill one of your prompt kits instead of text. Chataway fills the placeholders; an id that isn't one of your kits is denied. |
mode | append (default) adds to what the user typed; replace replaces it. |
chatId | A chat other than the panel's own. |
You need text or attachments (or a kit). The result is { status }: filled when the chat's composer is on screen, queued when it isn't — the next matching composer that opens within two minutes gets it (a newer queued fill replaces an older one). Chataway shows a short note that your app added to the message.
#Send from a click
askButton.onclick = async () => {
const { status } = await app.chat.send({ text: `Review ${file.name} and list what's missing.` });
if (status === 'no-chat') await app.chat.compose({ text: '…' });
};chat.send speaks for the user, so it works only inside a click or Enter handler in your panel, one send per click (click only; needs-gesture otherwise). It needs no grant. It goes to the chat named by chatId, else the panel's chat, else the chat on screen — and only to a chat that is open in this window. A named chatId must be the panel's chat, the chat on screen or one of your app chats (denied otherwise).
The message goes to an agent that may act on the user's computer, so Chataway shows it to the user first — "Send this message from Sketch Notes?", with Send, Don't send and Always allow Sketch Notes to send messages (remembered on that device). Don't send is cancelled. Chataway's own apps don't ask.
The result is { status, chatId? }: sent, busy (the chat can't take a message right now) or no-chat (that chat isn't open here, so nothing was sent).
#Create a chat
{
"requires": { "hostApi": 4 },
"grants": ["chats"],
"permissions": ["Start chats about your notes when you ask it to"]
}discussButton.onclick = async () => {
const { chatId } = await app.chat.create({
title: `About ${note.name}`,
text: `Let's work on @notes/${note.name}. Start by summarizing it.`,
send: false,
});
};| Option | |
|---|---|
title | The chat's title (≤ 120 characters). Default: your app's name. |
text, attachments | The first message (up to 20 attachments). |
send | false (default): the message waits in the composer. true: Chataway asks the user first, as for chat.send, then sends it once the chat is ready; it then needs text or attachments. |
Chataway creates the chat, opens it, then fills or sends the first message. The result is { chatId, status }: created (no first message), filled or queued (the message waits in the composer), or with send: true sent, busy or no-chat (the chat wasn't ready to send within 10 seconds; the message wasn't sent). chat.create needs a click.
App chats are ordinary chats. They show in the sidebar and in Activity, they use the provider the user picked for new chats, and your instructions apply because your app is on. The only difference is the tag: chat.list() returns the chats your app created in this project, latest first (up to 100: [{ chatId, title, createdAt, lastMessageAt }], times in milliseconds), and chat.open(chatId) opens one of them from a click. Other chats can't be opened this way (denied).
#Good practice
- Fill, don't send, unless the click means "send". A button labelled Ask the agent may send. A button labelled Discuss should fill.
- Write the message for the user. They will read it in their own chat. Name files as
@pathso the agent finds them. - Don't create chats on your own. Every
chat.createcomes from a click, and a chat per click is plenty.
#In the mock host
The mock host records what these calls would do in app.mockHost.composed ({ method, text, attachments, chatId, mode? }, with attachments as a count), keeps a list of created chats (chats sets the initial ones), and refuses chat.open for chats your app didn't create. With manifest it also checks the chats grant.