Working with notes

Get a webhook when a user mentions your agent in a note on a thread, and reply with a note of your own.

Notes are internal comments on a thread. A user can mention your agent in a note to hand it a question about that thread, and your agent can answer with a note.

Notes are never shown to the customer.

To work with notes, your machine user’s API key needs note:create permissions as well as thread:read and customer:read to read the thread.

Get notified when you’re mentioned

Subscribe your webhook target to thread.note_mention_created.

It fires when a note mentions a machine user, including when a user edits a note to add the mention. The payload has the thread, the note, and mentions, the list of machine users mentioned.

Check that your agent is among them:

if (event.payload.eventType === "thread.note_mention_created") {
  const mentioned = event.payload.mentions.some(
    (machineUser) => machineUser.id === process.env.AGENT_MACHINE_USER_ID,
  );
  if (!mentioned) return;

  await runAgent(event.payload.thread, event.payload.note);
}

note.markdown holds what the user wrote. Mentions appear in it as tokens: <@mu_…> for a machine user and <@u_…> for a user. Only machine users are listed in mentions; strip or resolve the tokens before you pass the text to a model.

To see every note on a thread, not only the ones that mention you, subscribe to thread.note_created as well. It fires for your own notes too, so skip notes where note.createdBy.actorType is machineUser and machineUserId is yours.

Reply with a note

The createNote mutation adds a note to the thread under the machine user’s name. Send text as the plain version and markdown for formatting. To mention the user who asked, put their <@u_…> token in markdown; Plain renders it as a mention and notifies them.

const author = event.payload.note.createdBy;
const mention = author.actorType === "user" ? `<@${author.userId}> ` : "";

const result = await plain.mutation.createNote({
  input: {
    customerId: event.payload.thread.customer.id,
    threadId: event.payload.thread.id,
    text: "The invoice failed because the card was declined on 3 September.",
    markdown: `${mention}The invoice failed because the card was **declined** on 3 September.`,
  },
});

if (result.error) throw new Error(result.error.message);

Notes have a maximum length of 10k characters. See notes for updating and deleting.

Notes also work without a mention. An agent that triages threads can leave what it found as a note, and an agent that hands off can use notes to say why it’s handing off.