Get slides agent message
- OpenAPI 3.1.0 document: https://api.rollstack.com/public/v1/openapi.json
- The whole reference in Markdown: https://docs.rollstack.com/llms-full.txt
- An index of the reference: https://docs.rollstack.com/llms.txt
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 itsidfromlistReportsorcreateReport. Only reports whosetypeisSlideDeckwork here: another type, such as a Google Slides presentation, returns400. 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: themessageIdthatsendReportMessagereturned. 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 ongetReportMessage, the run ongetReportRun, the batch of variants being added ongetBurstVariantBatch, the runs of a burst's variants ongetBurstRun. It returns as soon as the work is done, or as things stand once the time is up, so call it again whilestatusis stillqueuedorrunning.0returns at once. Defaults to20; at most30. Defaults to20.
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 aschatIdtosendReportMessageto continue the conversation, for example to answer aclarificationreply.messageId(string, required): Identifies your message to the slides agent. Pass it asmessageIdtogetReportMessageto follow its progress and read the agent's replies, or tocancelReportMessageto stop it.status(string, required): Where the message stands.sendReportMessagealways returnsqueuedorrunning.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;getReportMessagelists them inreplies.failed: at least one of its replies failed.cancelled: it was stopped while running, for example withcancelReportMessageor the stop button in the app. Cancelling aqueuedmessage 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 asUnderstanding your request,Refreshing data,DesignorFinishing up. Use it to show progress whilestatusisrunning.nullwhen no step is under way: while the message isqueued, 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 fromrunninguntil the reply is finished, so you can follow each reply across calls.status(string, required): Where this reply stands.runningwhile the agent works on it or it waits its turn; on adatasheet_filters_proposal, until Rollstack has applied the filters.completedonce the reply is finished:typesays what it is.failedwhen 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.cancelledwhen it was stopped, for example withcancelReportMessageor the stop button in the app. One ofrunning,completed,failed,cancelled.type(string or null, required): What the reply is, which tells you what to do next.nullwhile 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.changedSlideIdslists the slides it added or changed;versionBeforeIdundoes them withrestoreReportVersion, and they can also be reviewed or reverted in the app.partial_result: the same asresult, on replies written by an earlier version of the slides agent.clarification: the agent needs more from you before it goes on. Answer itsquestions, or the question incontentwhen there are none, in the next message on the same chat.answer: the agent replied incontentwithout 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 thesereplies, 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 whatproposalchanges, then approve it withapproveReportMessageProposalor reject it withrejectReportMessageProposal, 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 inreplies.
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 aclarificationreply: the multiple-choice questions the agent needs answered before it goes on. Send the options picked asanswersin the next message on the same chat, or answer in your own words incontent. Absent on other replies, and on a clarification that asks its question only incontent.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 asChart type, shown before it in the app. Send it back unchanged, withquestion, when you answer.multiSelect(boolean, required): Whether more than one option can be picked. Whentrue, the app shows the options as checkboxes; whenfalse, as a single choice, so answer with one option.options(array of object, required): The options to choose from. Answer with thelabelof each one picked.label(string, required): The option's text, as shown in the app. Send it back inanswersto 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 itslabelin the next message on the same chat is enough.templateId(string): Set when the option offers a saved template, by itsidinlistTemplates: the app shows the template's look. You don't send it back: picking the option by itslabelis enough.
changedSlideIds(array of string): On aresultorpartial_resultreply: the slides the agent added or changed, in report order. Slides it deleted aren't listed. Pass them asslideIdstogetReportSlideImagesto check how they look, or togetReportContentto read them.versionBeforeId(string): On aresultorpartial_resultreply: the report's version saved just before the agent changed it. Restore it withrestoreReportVersionto undo the reply, which also undoes any change made to the report since.proposal(object): On asettings_proposaloremail_send_proposalreply: what the proposal changes, or the email it sends, and where it stands. Absent on other replies.- Option 1
status(string, required):proposedwhile it waits for the user to decide.appliedonce approved and applied,rejectedonce rejected.supersededwhen a later proposal in the chat replaced it.conflictwhen the report changed after it was proposed, so approving it applied nothing, andfailedwhen applying it failed. One ofproposed,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.warningspoint out what the user should know before approving, such as a schedule that never runs.- When
typeisparameters.createtype(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
typeisparameters.updatetype(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
typeisparameters.deletetype(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
typeisparameters.setDatasheetLinkedtype(parameters.setDatasheetLinked, required)parameterName(string, required)filterName(string, required)datasheetName(string, required)isLinked(boolean, required)warnings(array of object, required)
- When
typeisemail.template.createtype(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
typeisemail.template.updatetype(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
typeisemail.template.selecttype(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
typeisemail.template.resettype(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
typeisschedule.addtype(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
typeisschedule.removetype(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
typeisschedule.modifytype(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
typeisemail.config.updatetype(email.config.update, required)before(object or null, required)after(object, required)trigger(string, required): One ofall,none,scheduled.sharingFormat(string, required): One oflink,pdf,ppt,cloudLink.sendAttachmentAsLink(boolean, required)sender(object or null, required)
warnings(array of object, required)
- When
typeisemail.recipients.updatetype(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
typeisemail.recipients.createGrouptype(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)
- When
- Option 2
status(string, required):awaiting_confirmationwhile it waits for the user to decide,cancelledonce rejected, andsupersededwhen a later proposal in the chat replaced it. Once approved:queuedandsendinguntil every email is handed to the email provider, thensent,partially_sentorfailed.unconfirmedwhen Rollstack lost track of the send, so some emails may have gone out. One ofawaiting_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 ofpdf,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.nulluntil the send starts.total(integer, required)sent(integer, required)failed(integer, required)unknown(integer, required)
- Option 1