Skip to main content

Send message to slides agent

POST https://api.rollstack.com/public/v1/reports/{id}/messages

Asks the slides agent to build or change a report, or to answer a question about it, as the app's chat does. Answers the message's id at once: follow it with getReportMessage. When the client can show one, a view shows the user the slides as the agent drafts them. Without chatId the message starts a new chat, which shows in the user's chat history in the app. With it, the message continues that chat and waits its turn while a reply is still generating. Several chats on a report can generate at once; an agent working on a part of the report another chat is editing works on something else or says so. For slides built from your own data, a connected dashboard, a warehouse table or a spreadsheet, upload the data with createDataset, find the dashboard or Salesforce report with searchDashboards, the Snowflake, Databricks or BigQuery table with searchTables or the spreadsheet with searchSpreadsheets, add any of them with addReportDatasheets and pass the datasheet ids as datasheetIds. For a brief, a report or notes to build from, upload it with createDocument and pass its id in documentIds. Only its editors may. At most 6 messages a minute per user. To write the slides yourself instead, start with getReportDesign.

Requires the slide_decks:run scope.

Operation ID: sendReportMessage.

Path parameters

  • id (string, required): The report to act on, by its id from listReports or createReport. Only reports whose type is SlideDeck work here: another type, such as a Google Slides presentation, returns 400. You can also copy it from the report's link in Rollstack: it's the part right after /slides/.

Headers

  • Idempotency-Key (string): A unique value, such as a UUID, that makes retrying this call safe. A retry with the same key within 24 hours answers the first call's result instead of running it again. Use a new key for each new call. From 1 to 255 printable ASCII characters.

Request body, required

application/json

  • content (string): Your message to the slides agent, as you would write it in the chat in the app: for example, slides to build or change, or a question about the report. On a report with no slides yet, the agent takes it as a request to build the report. A link to a picture in the message, such as a logo or a photo to place, is downloaded and given to the agent. Required unless you send answers; with them, it's sent after your answers as a note. At most 10,000 characters: send a longer text, such as a brief, as a document with createDocument. Defaults to `. Example: Add a slide comparing revenue by region`.
  • chatId (string): The chat to continue: the chatId returned for an earlier message. The agent reads the chat's earlier messages as context, and if it's still replying in that chat, your message waits its turn (queued). If omitted, the message starts a new chat, which shows in your chat history on the report in the app. Must be one of your own chats on this report. Example: 0e4c2b7a-9d1f-4a3b-8c5e-6f7a8b9c0d1e.
  • slideIds (array of string): The slides your message is about, as when you select slides in the app before writing in the chat. The agent knows you selected them and uses the datasheets on them for your request. Slide ids come from getReportContent. 1 to 100 slides of this report.
  • datasheetIds (array of string (uuid)): Datasheets of this report for the agent to work from, on top of those on the slides in slideIds, as when you pick data in the chat in the app. To have the agent build slides from data you just added, pass the ids addReportDatasheets returned; for data already on the report, take them from listReportDatasheets. 1 to 100 datasheets of this report.
  • documentIds (array of string): Documents for the agent to read, as when you attach documents in the chat in the app: the ids createDocument returned. The agent reads their text and looks at their pages, for example to build slides from a brief or to rebuild a report as slides. 1 to 5 documents your organization can read.
  • answers (array of object): Your answers to the questions of a clarification reply, as when you pick options in the chat in the app: one entry per question you answer. Send them as the next message on the same chat, by passing its chatId. When a picked option offers a dashboard, table or spreadsheet, Rollstack adds it to the report as a datasheet before the agent goes on. To add a note, send it in content with the answers.
    • header (string, required): The header of the question you're answering, copied unchanged from the clarification reply's questions. Example: Chart type.
    • question (string, required): The question you're answering, copied unchanged from the clarification reply's questions. With header, it tells Rollstack which question your picks are for. Example: Which chart should show revenue by region?.
    • answers (array of string, required): The label of each option picked: one for a question whose multiSelect is false, one or more when it's true.

Response 202

Success

application/json

  • chatId (string, required): Identifies the chat the message is in, which also shows in your chat history on the report in the app. Pass it as chatId to sendReportMessage to continue the conversation, for example to answer a clarification reply.
  • messageId (string, required): Identifies your message to the slides agent. Pass it as messageId to getReportMessage to follow its progress and read the agent's replies, or to cancelReportMessage to stop it.
  • status (string, required): Where the message stands. sendReportMessage always returns queued or running.

    • queued: the agent is still replying to an earlier message of the same chat; this one starts once that reply is finished.
    • running: the slides agent is working on it. While other chats keep the agent busy on this report, it can first wait here for its turn.
    • completed: every reply is finished; getReportMessage lists them in replies.
    • failed: at least one of its replies failed.
    • cancelled: it was stopped while running, for example with cancelReportMessage or the stop button in the app. Cancelling a queued message removes it from the chat instead, so it is no longer found.

    One of queued, running, completed, failed, cancelled.

  • appUrl (string (uri), required): Link to the report in Rollstack, with this chat open, where you can follow the conversation and review the changes the agent made.