Skip to main content

Approve slides agent proposal

POST https://api.rollstack.com/public/v1/reports/{id}/messages/{messageId}/replies/{replyId}/approve

Approves the proposal of a settingsproposal or emailsendproposal reply, as its Approve button in the app's chat does: Rollstack makes the change, or sends the email. Only approve what the user approved after seeing the reply's proposal. Answers the reply with the proposal's status: applied once the change is made, and queued for a send, which getReportMessage then follows through sending to sent, partiallysent, failed or unconfirmed, with its counts. Needs also slidedecks:email for an email change or send, and slidedecks:write for the rest. Approving a send answers 409 while the report is updating, such as after a filter change the same message asked for, and counts against the 5 email sends a minute, as sendReportEmail does. Only the user who sent the message may, while they can edit the report. A proposal already decided answers 409. From an AI client, approving a send only asks the user to confirm it in Rollstack: it answers confirmation-required and runs once they confirm.

Requires the slide_decks:run scope.

Operation ID: approveReportMessageProposal.

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.
  • replyId (string, required): The reply that makes the proposal: the id of a settings_proposal or email_send_proposal reply that getReportMessage lists for the message.

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.

Response 200

Success

application/json

  • 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)
              • name (string, required)
              • dashboardName (string, required)
            • datasheets (array of string, required): Defaults to [].
            • datasheetCount (integer, required)
            • unlinkedDatasheets (array of string, required)
            • columns (array of object, required): Defaults to [].
              • datasheetName (string, required)
              • column (string, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, required)
        • When type is parameters.update
          • type (parameters.update, required)
          • before (object, required)
            • name (string, required)
            • value (string, required)
            • filters (array of object, required)
              • name (string, required)
              • dashboardName (string, required)
            • datasheets (array of string, required): Defaults to [].
            • datasheetCount (integer, required)
            • unlinkedDatasheets (array of string, required)
            • columns (array of object, required): Defaults to [].
              • datasheetName (string, required)
              • column (string, required)
          • after (object, required)
            • name (string, required)
            • value (string, required)
            • filters (array of object, required)
              • name (string, required)
              • dashboardName (string, required)
            • datasheets (array of string, required): Defaults to [].
            • datasheetCount (integer, required)
            • unlinkedDatasheets (array of string, required)
            • columns (array of object, required): Defaults to [].
              • datasheetName (string, required)
              • column (string, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, required)
        • When type is parameters.delete
          • type (parameters.delete, required)
          • before (object, required)
            • name (string, required)
            • value (string, required)
            • filters (array of object, required)
              • name (string, required)
              • dashboardName (string, required)
            • datasheets (array of string, required): Defaults to [].
            • datasheetCount (integer, required)
            • unlinkedDatasheets (array of string, required)
            • columns (array of object, required): Defaults to [].
              • datasheetName (string, required)
              • column (string, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, 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)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, required)
        • When type is email.template.create
          • type (email.template.create, required)
          • before (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • after (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • impact (object or null, required)
            • consumers (array of string, required)
            • anonymousCount (integer, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, required)
        • When type is email.template.update
          • type (email.template.update, required)
          • before (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • after (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • impact (object or null, required)
            • consumers (array of string, required)
            • anonymousCount (integer, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, required)
        • When type is email.template.select
          • type (email.template.select, required)
          • before (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • after (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • impact (object or null, required)
            • consumers (array of string, required)
            • anonymousCount (integer, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, required)
        • When type is email.template.reset
          • type (email.template.reset, required)
          • before (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • after (object or null, required)
            • id (string or null, required)
            • name (string or null, required)
            • subject (string, required)
            • content (string, required)
            • button (object, required)
              • textColor (string, required)
              • bgColor (string, required)
            • editable (boolean, required)
          • impact (object or null, required)
            • consumers (array of string, required)
            • anonymousCount (integer, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, 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)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, 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)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, 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)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, required)
        • When type is email.config.update
          • type (email.config.update, required)
          • before (object or null, 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)
          • 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)
              • id (string, required)
              • label (string, required)
          • warnings (array of object, required)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, 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)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, 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)
            • code (string, required): One of duplicate-schedule, never-runs, distant-next-run, skips-short-months, scheduled-email-stops, scheduled-delivery-without-schedule, no-recipients, template-shared, template-sends-pending, overwrites-datasheet-values, datasheets-keep-last-value.
            • message (string, 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)