Skip to main content

Get slides agent message

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

A message to the slides agent and its replies. Waits up to waitSeconds for the message to finish and answers as soon as it does, so call it again while the status is queued or running. A clarification reply asks questions: ask the user, then send the options they pick as answers in a new message on the same chat. A proposal reply changes nothing until it is approved: show the user what its proposal changes, then approve or reject it as they decide. Only the user who sent the message may read it, while they can edit the report.

Requires the slide_decks:read scope.

Operation ID: getReportMessage.

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/.
  • messageId (string, required): The message to the slides agent: the messageId that sendReportMessage returned. Only the user who sent the message can read, cancel or decide its proposals, and only while they can edit the report.

Query parameters

  • waitSeconds (integer): How long this call waits for the work to finish, in seconds: the message to the slides agent on getReportMessage, the run on getReportRun, the batch of variants being added on getBurstVariantBatch, the runs of a burst's variants on getBurstRun. It returns as soon as the work is done, or as things stand once the time is up, so call it again while status is still queued or running. 0 returns at once. Defaults to 20; at most 30. Defaults to 20.

Response 200

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.
  • stage (string or null, required): What the slides agent is doing right now, in the words the chat in the app shows, such as Understanding your request, Refreshing data, Design or Finishing up. Use it to show progress while status is running. null when no step is under way: while the message is queued, before the agent's first step, and once the message is finished.
  • createdAt (string (date-time), required): When you sent the message to the slides agent.
  • updatedAt (string (date-time), required): When the message or any of its replies last changed, for example as the agent reports progress or finishes a reply.
  • replies (array of object, required): The slides agent's replies to this message, in order. The first one is listed, running, as soon as the message is sent. The agent can split a message that asks for several things into parts, each with its own reply; the message is finished only once every part is.

    • id (string, required): Identifies the reply. It stays the same from running until the reply is finished, so you can follow each reply across calls.
    • status (string, required): Where this reply stands. running while the agent works on it or it waits its turn; on a datasheet_filters_proposal, until Rollstack has applied the filters. completed once the reply is finished: type says what it is. failed when the agent couldn't finish it, never got to it because an earlier part failed or was stopped, or the filters couldn't be applied. cancelled when it was stopped, for example with cancelReportMessage or the stop button in the app. One of running, completed, failed, cancelled.
    • type (string or null, required): What the reply is, which tells you what to do next. null while the agent is still working on it, and when it failed or was stopped.

      • result: the agent changed the report, and the changes are already saved. changedSlideIds lists the slides it added or changed; versionBeforeId undoes them with restoreReportVersion, and they can also be reviewed or reverted in the app.
      • partial_result: the same as result, on replies written by an earlier version of the slides agent.
      • clarification: the agent needs more from you before it goes on. Answer its questions, or the question in content when there are none, in the next message on the same chat.
      • answer: the agent replied in content without changing the report, for example to a question about the report or about how Rollstack works.
      • datasheet_filters_proposal: the agent changes the values of filters that some of the report's datasheets apply when they read their source. For a message sent through the API, Rollstack applies them right away, without approval in the app. If your request needed more than that, it then goes on by itself as a new message in the same chat, unless you send one there first; that message isn't in these replies, so follow it in the app.
      • settings_proposal, email_send_proposal: a change to the report's update schedules, email settings, email template or parameters, or sending the report by email. Nothing changes until it is approved: show the user what proposal changes, then approve it with approveReportMessageProposal or reject it with rejectReportMessageProposal, as they decide. It can also be decided in the app. The agent makes one for a message sent through the API only when your API key has the scope the change needs.
      • report_proposal: a change elsewhere in Rollstack, such as to reports, folders or members. The agent doesn't make them for messages sent through the API.
      • proposal_applied: a note the chat in the app adds once a proposal is decided. It is never listed in replies.

      One of result, partial_result, clarification, answer, settings_proposal, proposal_applied, email_send_proposal, datasheet_filters_proposal, report_proposal.

    • content (string, required): The reply's text, as the chat in the app shows it: what the agent did, its answer, or its questions. Empty until the agent has written it. When the reply failed or was stopped, it says so. Can contain Markdown.
    • questions (array of object): On a clarification reply: the multiple-choice questions the agent needs answered before it goes on. Send the options picked as answers in the next message on the same chat, or answer in your own words in content. Absent on other replies, and on a clarification that asks its question only in content.
      • question (string, required): The question the agent is asking, as the chat in the app shows it.
      • header (string, required): A short label for the question, such as Chart type, shown before it in the app. Send it back unchanged, with question, when you answer.
      • multiSelect (boolean, required): Whether more than one option can be picked. When true, the app shows the options as checkboxes; when false, as a single choice, so answer with one option.
      • options (array of object, required): The options to choose from. Answer with the label of each one picked.
        • label (string, required): The option's text, as shown in the app. Send it back in answers to pick this option. The agent may mark the option it recommends with (Recommended), which you can keep or drop.
        • description (string): What picking this option means, shown under its label in the app.
        • value (string): Set when the option offers data the agent found: a connection for the agent to search next, or a dashboard, table or spreadsheet that Rollstack adds to the report as a datasheet when you pick the option. It isn't shown in the app, and you don't send it back: picking the option by its label in the next message on the same chat is enough.
        • templateId (string): Set when the option offers a saved template, by its id in listTemplates: the app shows the template's look. You don't send it back: picking the option by its label is enough.
    • changedSlideIds (array of string): On a result or partial_result reply: the slides the agent added or changed, in report order. Slides it deleted aren't listed. Pass them as slideIds to getReportSlideImages to check how they look, or to getReportContent to read them.
    • versionBeforeId (string): On a result or partial_result reply: the report's version saved just before the agent changed it. Restore it with restoreReportVersion to undo the reply, which also undoes any change made to the report since.
    • proposal (object): On a settings_proposal or email_send_proposal reply: what the proposal changes, or the email it sends, and where it stands. Absent on other replies.
      • Option 1
        • status (string, required): proposed while it waits for the user to decide. applied once approved and applied, rejected once rejected. superseded when a later proposal in the chat replaced it. conflict when the report changed after it was proposed, so approving it applied nothing, and failed when applying it failed. One of proposed, applying, applied, rejected, superseded, conflict, failed.
        • changes (array of object, required): What approving it changes, as the approval card in the app shows it: one entry per change, with the setting before and after it. warnings point out what the user should know before approving, such as a schedule that never runs.
          • When type is parameters.create
            • type (parameters.create, required)
            • after (object, required)
              • name (string, required)
              • value (string, required)
              • filters (array of object, required)
              • datasheets (array of string, required): Defaults to [].
              • datasheetCount (integer, required)
              • unlinkedDatasheets (array of string, required)
              • columns (array of object, required): Defaults to [].
            • warnings (array of object, required)
          • When type is parameters.update
            • type (parameters.update, required)
            • before (object, required)
              • name (string, required)
              • value (string, required)
              • filters (array of object, required)
              • datasheets (array of string, required): Defaults to [].
              • datasheetCount (integer, required)
              • unlinkedDatasheets (array of string, required)
              • columns (array of object, required): Defaults to [].
            • after (object, required)
              • name (string, required)
              • value (string, required)
              • filters (array of object, required)
              • datasheets (array of string, required): Defaults to [].
              • datasheetCount (integer, required)
              • unlinkedDatasheets (array of string, required)
              • columns (array of object, required): Defaults to [].
            • warnings (array of object, required)
          • When type is parameters.delete
            • type (parameters.delete, required)
            • before (object, required)
              • name (string, required)
              • value (string, required)
              • filters (array of object, required)
              • datasheets (array of string, required): Defaults to [].
              • datasheetCount (integer, required)
              • unlinkedDatasheets (array of string, required)
              • columns (array of object, required): Defaults to [].
            • warnings (array of object, required)
          • When type is parameters.setDatasheetLinked
            • type (parameters.setDatasheetLinked, required)
            • parameterName (string, required)
            • filterName (string, required)
            • datasheetName (string, required)
            • isLinked (boolean, required)
            • warnings (array of object, required)
          • When type is email.template.create
            • type (email.template.create, required)
            • before (object or null, required)
            • after (object or null, required)
            • impact (object or null, required)
            • warnings (array of object, required)
          • When type is email.template.update
            • type (email.template.update, required)
            • before (object or null, required)
            • after (object or null, required)
            • impact (object or null, required)
            • warnings (array of object, required)
          • When type is email.template.select
            • type (email.template.select, required)
            • before (object or null, required)
            • after (object or null, required)
            • impact (object or null, required)
            • warnings (array of object, required)
          • When type is email.template.reset
            • type (email.template.reset, required)
            • before (object or null, required)
            • after (object or null, required)
            • impact (object or null, required)
            • warnings (array of object, required)
          • When type is schedule.add
            • type (schedule.add, required)
            • after (object, required)
              • frequency (string, required)
              • recurrence (string, required)
              • timezone (string, required)
              • startDate (string, required)
              • endDate (string or null, required)
              • syncNames (array of string or null, required)
              • nextRunAt (string or null, required)
            • warnings (array of object, required)
          • When type is schedule.remove
            • type (schedule.remove, required)
            • before (object, required)
              • frequency (string, required)
              • recurrence (string, required)
              • timezone (string, required)
              • startDate (string, required)
              • endDate (string or null, required)
              • syncNames (array of string or null, required)
              • nextRunAt (string or null, required)
            • warnings (array of object, required)
          • When type is schedule.modify
            • type (schedule.modify, required)
            • before (object, required)
              • frequency (string, required)
              • recurrence (string, required)
              • timezone (string, required)
              • startDate (string, required)
              • endDate (string or null, required)
              • syncNames (array of string or null, required)
              • nextRunAt (string or null, required)
            • after (object, required)
              • frequency (string, required)
              • recurrence (string, required)
              • timezone (string, required)
              • startDate (string, required)
              • endDate (string or null, required)
              • syncNames (array of string or null, required)
              • nextRunAt (string or null, required)
            • warnings (array of object, required)
          • When type is email.config.update
            • type (email.config.update, required)
            • before (object or null, required)
            • after (object, required)
              • trigger (string, required): One of all, none, scheduled.
              • sharingFormat (string, required): One of link, pdf, ppt, cloudLink.
              • sendAttachmentAsLink (boolean, required)
              • sender (object or null, required)
            • warnings (array of object, required)
          • When type is email.recipients.update
            • type (email.recipients.update, required)
            • before (object, required)
              • to (array of string, required)
              • cc (array of string, required)
              • bcc (array of string, required)
              • replyTo (array of string, required)
              • id (string, required)
              • label (string, required)
            • after (object, required)
              • to (array of string, required)
              • cc (array of string, required)
              • bcc (array of string, required)
              • replyTo (array of string, required)
              • id (string, required)
              • label (string, required)
            • warnings (array of object, required)
          • When type is email.recipients.createGroup
            • type (email.recipients.createGroup, required)
            • after (object, required)
              • to (array of string, required)
              • cc (array of string, required)
              • bcc (array of string, required)
              • replyTo (array of string, required)
            • warnings (array of object, required)
      • Option 2
        • status (string, required): awaiting_confirmation while it waits for the user to decide, cancelled once rejected, and superseded when a later proposal in the chat replaced it. Once approved: queued and sending until every email is handed to the email provider, then sent, partially_sent or failed. unconfirmed when Rollstack lost track of the send, so some emails may have gone out. One of awaiting_confirmation, cancelled, superseded, queued, sending, sent, partially_sent, failed, unconfirmed.
        • recipients (array of object, required): Who receives the report: one email per group, each with its own addresses.
          • to (array of string, required)
          • cc (array of string, required)
          • bcc (array of string, required)
          • replyTo (array of string, required)
          • id (string, required)
          • label (string, required)
        • sharingFormat (string, required): The file sent: the report's visible slides as a PDF (pdf) or PowerPoint file (ppt). One of pdf, ppt.
        • sendAttachmentAsLink (boolean, required): Whether the file is behind a download button in the email instead of attached.
        • counts (object or null, required): How many emails were handed to the email provider, failed, or ended unknown. null until the send starts.
          • total (integer, required)
          • sent (integer, required)
          • failed (integer, required)
          • unknown (integer, required)