> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Apostra in Slack

> What the Apostra Slack app does, who can install it, which Slack permissions it asks for and why, and what it does with your messages.

The Apostra Slack app lets people in a Slack workspace talk to Apostra where they
already work. This page is for the Slack admin who decides whether to install it
and for the people who use it. It covers what the app does, each permission it
asks for and why, and what happens to the messages it reads.

## Install

Open this link in a browser where you are signed in to Slack:

```text theme={null}
https://api.apostra.com/slack/install
```

If your Apostra account shows **Settings → Messaging apps** in the web app, an
account admin can also start there: choose **Continue in Slack** on the Slack
card. You do not need an Apostra account to install the app.

Slack shows the permissions Apostra asks for and the workspace to install into.
Anyone your Slack settings allow to install apps can approve it. If your
workspace requires an admin to approve new apps, Slack sends the request to one.

The app installs into one workspace at a time. Installing it across a whole
Slack Enterprise Grid organization is not supported. Install it into each
workspace that should have it.

If the install link shows a "Not Found" error, Slack installs are not open yet.
Email [support@apostra.com](mailto:support@apostra.com).

## What Apostra does in Slack

* **Direct messages.** Message Apostra directly to ask a question.
* **Mentions.** Mention @Apostra in a channel it has been added to, and it
  answers in the thread. A message that opens by mentioning someone else is
  for them, so Apostra stays quiet, except in a thread Apostra has already
  replied in: there, mentioning it always gets an answer.
* **Channels linked to your account.** In a channel linked to your Apostra
  account, Apostra also reads messages that don't mention it, including replies
  in threads. It may answer a general question without being mentioned. A
  request to Apostra that nobody answers is picked up by Apostra itself in
  channels where it is switched on: see
  [When nobody has answered you](https://docs.apostra.com/v3/slack-app.md#when-nobody-has-answered-you).
  Messages between people at your own company, and messages to another company
  in the channel, are left alone.
* **The `/apostra` command.** Type `/apostra` followed by your question in a
  channel it has been added to. `/murph` is the older name for the same command
  and still works.
* **Files.** Attach audio, images, PDFs or spreadsheets to a message addressed
  to Apostra and ask about them. Apostra reads only the files attached to a
  message addressed to it. It does not browse other files in the workspace.
* **Reports.** Ask Apostra to file a report, and it passes the report to the
  Apostra team to follow up.
* **Generated files.** When Apostra produces a file for you, such as an
  `adagents.json` file, it uploads the file into the same thread.
* **Pages and forms.** When Apostra opens a page or a form for you, Slack
  cannot show it. Apostra instead shows a card with the key details for a few
  pages, such as account records, a campaign or your requests, or an **Open in
  Apostra** button. The button opens your account in the web app, or the
  advertiser's Campaigns or Creative Library page when the reply is about one,
  and you finish the task there.
* **Access requests.** In a channel linked to an account, a person Apostra
  cannot link to a login can choose **Request access from admin**. Apostra then
  files an access request for the email address on their Slack profile with that
  account's admins.

Apostra answers general questions about how the product works for anyone in the
workspace. It answers questions about your own account only after it links you to
your Apostra login, as described next.

### When nobody has answered you

This is planned and not yet available in any channel. Apostra turns this on one
channel at a time, so it applies only to channels where Apostra has switched it
on. Until then, Apostra does not reply to a message that does not mention it, so
do not wait for a reply to one. If you would like it for your channel, ask
[Apostra support](https://docs.apostra.com/v3/support.md).

In a channel where it is switched on, you will not need to mention Apostra to get
an answer. If you ask Apostra something and nobody from Apostra has replied in
the thread after about 15 working minutes, Apostra will reply in the thread.
Working hours are Monday to Friday, 08:00 to 20:00 UTC.

Apostra decides whether your message is meant for Apostra. A message to
another company in the channel, a message between people at your own company,
and thanks or an update get no reply.

When the message is meant for Apostra, one of two things happens:

* **Apostra can answer.** It replies from the public documentation, your
  account's own data, or an error it can read, and ends with "cc" and the
  Apostra person who looks after your account, so that person sees it in
  context. An answer about your account follows the same rules as any other
  answer in the channel: it needs the channel to be cleared for account data,
  and it uses the permissions of the person who asked. In a channel that is not
  cleared, Apostra answers with general information only.
* **Apostra cannot answer.** This covers anything about price or terms, a
  promise about what Apostra will do or when, a change Apostra cannot make for
  you, and anything it does not know. Apostra tells you who is looking at it
  and tags that person in the thread with your question. It does not guess and
  it does not promise an outcome or a time.

If nobody from Apostra has replied in the thread after about two working hours,
Apostra sends a direct message to another person at Apostra, so the request is
not missed. Apostra keeps a record of the replies and messages it sends. Apostra
reads the text of your message only in this case, not files attached to it.

### Add Apostra to a channel

Apostra works in a channel only after someone adds it. Apostra does not ask Slack
for permission to join channels on its own, so a person adds it to each public
channel. To use it in a private channel, invite it the way you would invite a
person. Apostra cannot add itself to a private channel.

When Apostra joins a channel in your workspace it posts a short message saying
that it answers when someone mentions it or uses `/apostra`, which channel
messages it keeps as account activity, and that editing or deleting a message in
Slack updates or clears the saved copy.
[What Apostra does with messages](https://docs.apostra.com/v3/slack-app.md#what-apostra-does-with-messages) explains
which messages are saved.

In the support channel Apostra creates for your account, the Apostra assistant
posts a welcome instead. It says what it can help with for your kind of account
(Buyer, Seller or Agents), and that it replies when you tag @Apostra or type
`/apostra` followed by your question. Tag it again when you follow up in its
thread. A question about your account that it does not answer is passed to the
Apostra team.

### How Apostra links you to your Apostra account

Apostra reads your Slack email address and looks for an Apostra login with the
same address. Apostra answers questions about an account only if the match is
unique and the login is active. A match grants nothing by itself: Apostra answers
with the role that person already has in Apostra, so Slack gives no one access to
an account that their Apostra login does not already have.

In a channel, answers about an account also depend on the channel being linked to
that account, and on the channel's members being cleared for the account's data.
Apostra links the support channel it creates for an account
(**Settings → Connect support**). To link another channel, ask
[Apostra support](https://docs.apostra.com/v3/support.md). [Clear a channel for account data](https://docs.apostra.com/v3/slack-app.md#clear-a-channel-for-account-data)
explains the second condition.

A channel linked to an account can also read, read-only, the certification of agents held by other accounts in the same organization: their certification results, their validation runs, and the diagnostics of a run, which show what Apostra sent the agent and what it returned. Nothing else about those agents, such as their webhook deliveries, is readable, and a channel whose account data is withheld pending review reads none of it.

In a Slack Connect channel or any other channel shared with another organization,
Apostra narrows what it will say.

## Clear a channel for account data

Everyone in a channel reads every answer. So in a channel linked to an account,
Apostra answers questions about that account only when it knows every person in
the channel. Until then the account's data is withheld pending a review of the
channel, and Apostra answers with general Apostra information.

The first time someone asks a question in a withheld channel, Apostra opens one
case for Apostra staff to review the channel and says so once, in a note that
begins:

> This channel is withheld from this account's data until Apostra reviews who is
> in it, so for now I'm answering with general Apostra information only. I've
> asked the team to clear this channel so I can see your account.

Later answers in the channel carry no note while the review is pending. If the
channel is still withheld a week later, Apostra asks again. You do not need to
email anyone to start the review.

Setting the channel up comes before anything else. Apostra's first reply says
that the channel has to be set up before it can see your account. If you asked
how to get started selling, Apostra then asks the questions in
[Tell Apostra how you sell](https://docs.apostra.com/v3/seller-how-you-sell.md) instead of giving generic
steps, and you can answer while the channel is being set up.

The case lists the people in the channel who are not Apostra staff or apps, by
the name Slack shows and the domain of their Slack email, and the domains your
account has proved. It never lists an email address. If Apostra cannot look up
every member of the channel, the case says so and asks Apostra staff to check the
channel's members directly before they clear it.

### A channel that is not connected to an account

In a Slack Connect channel that is not connected to any account yet, Apostra
cannot see an account at all. It says so in its first reply and answers with
general Apostra information only. The first question opens one case for Apostra
staff to connect the channel, and Apostra says so once in a note that begins:

> This channel isn't connected to an Apostra account yet, so for now I'm
> answering with general Apostra information only. I've asked the team to
> connect it so I can see your account.

The case lists the people in the channel by name and email domain, and suggests
accounts that have claimed one of those domains. The suggestion is only a
starting point: Apostra staff confirm which account the channel belongs to
before they connect it. If Apostra does not recognize your Slack login, link it
to your Apostra login with the email you use in Slack, as described above.

A newly linked channel starts this way until its first check, which runs straight
away.

### What Apostra checks

Apostra reads the channel's member list from Slack. For each member it has not
yet linked to an Apostra login, it looks up their Slack email and matches it to an
active login. A member also gets linked when they write in the channel, use
Apostra's command or buttons, or open its Home tab. A member is cleared when
they:

* have an active login on the account, or on another account in the same
  organization, and Apostra has linked them to it. A member of another
  company's Slack workspace is linked only after they confirm once by signing
  in, unless an administrator of the organization has already confirmed from
  that workspace (see
  [Confirm your Slack account](https://docs.apostra.com/v3/slack-app.md#confirm-your-slack-account)); or
* are Apostra staff whose Slack account belongs to Apostra's own workspace.
  They are cleared without a decision and are not listed for review. A staff
  email address on a member of any other workspace is never linked to a staff
  login, because each workspace sets its own members' emails.

Apps are checked too. An app installed in Apostra's own Slack workspace, such as
one of Apostra's internal integrations, does not count against the channel. Any
other app does, including an app installed in your own workspace.

Everyone else is not cleared: a person whose email Slack does not share, which is
common for guests from another company; someone whose email matches no active
Apostra login; or an app from any other workspace. A member Apostra could not look
up in time is not cleared until the next check. A channel with more than fifty
members Apostra has not linked is not looked up at all. One member who is not
cleared keeps the whole channel on general answers.

Apostra checks again:

* Right after someone joins the channel. The channel goes back to general answers
  the moment they join, and Apostra restores account answers once the check shows
  everyone is cleared.
* Right after an account admin reviews a person.
* About every six hours. A person who has left the channel stops counting at the
  next check.

### Confirm your Slack account

Every Slack workspace sets its own members' email addresses, so a member of
another company's workspace can carry any address, yours included. Apostra
therefore links such a member to your login only after you confirm it once:

1. When that Slack member next asks Apostra something, Apostra tells them it
   needs a confirmation and sends them a link. Until then Apostra answers them
   with general information only.
2. Whoever owns the login opens the link, signs in to Apostra in their own
   browser, and chooses **Confirm**. The link names the Slack member, who sets
   that name themselves, and says they are in another company's workspace.
   Confirm only if you just asked Apostra a question in Slack yourself. If you
   did not, choose **Not me** and tell your account admin; the link expires on
   its own.
3. After you confirm, Apostra answers that Slack member as you, with your
   account access, from their next message.

When an administrator of your organization confirms from a Slack workspace,
Apostra trusts that workspace for your organization, and only for it. The
confirmation page tells the administrator this, naming the organization, before
they choose **Confirm**. After
that, a colleague in the same workspace is linked without a link of their own
when all of these hold:

* their Slack email is on a domain your organization has verified. The domain
  must match exactly: a subdomain, a look-alike or a free-mail domain never
  does;
* their Apostra login belongs to your organization or to one of its accounts;
  and
* the administrator who confirmed is still an administrator of your
  organization, and the domain is still verified.

Everyone else still confirms: a member of any other workspace, an email on a
domain your organization has not verified, and a login outside your
organization. A person confirming who is not an administrator does not trust
the workspace. Apostra staff are never linked this way. If the administrator
stops being one, or the domain stops being verified, no one new is linked this
way; people already linked stay linked.

The link works for 24 hours and only for the login it was made for. If it has
expired, ask Apostra in Slack again for a new one. Apostra sends each link
once; asking again within the 24 hours does not send another message.

You do not need to confirm when the Slack member belongs to Apostra's own
workspace, or to a workspace where one of your accounts has a linked channel.
Members Apostra had already linked before confirmation existed stay linked
until they next use Apostra in Slack, and then confirm once.

### A channel with another customer's members

Apostra does not answer with an account's data in a channel that includes a
member of a different Apostra customer, unless that person also has a login on
the account or Apostra staff have reviewed and approved the channel. Marking that
person a guest or an external company does not change this.

### Review the people in a channel as an account admin

Only an Admin of the account can review a channel's people. In the web app:

1. Open **Settings → Connect support**.
2. Under **Channels**, find **Apostra support channel**. **Channel participants**
   lists the people Apostra found in the channel. A person who is not cleared
   shows **Needs review**. Apostra staff show **Cleared: Apostra staff** and need
   no decision; choose **Change decision** to mark one as a channel guest or an
   external company instead. The list appears once the account has a support
   channel with people in it.
3. For each person, choose one:

| Choice | What happens |
| - | - |
| **Add to account** | Sends the person an invitation to the account, with the account role you pick: **Member**, **Operator** or **Admin**. It uses the email on their Slack profile. If Slack does not share it, the button is off; invite them from **Settings → Account members** instead. Once they accept, the next check links their Slack email to their login and counts them as cleared. |
| **Keep as channel guest** | The person stays in the channel with no account access. Apostra answers with general information for as long as they are in it. |
| **Mark as external company** | The same as a guest, with the company name you enter recorded against them. |
| **Disconnect channel** | Unlinks the channel from the account. Apostra answers with general information there. Nobody's account membership changes. |

The web app takes one decision for each person. Ask
[Apostra support](https://docs.apostra.com/v3/support.md) if one needs changing. When every person in the
channel is cleared, Apostra answers with account data again.

### Apostra staff clear a channel

Apostra staff can also review a channel and clear it. A question asked in a
withheld channel opens that review as a case, so you do not need to ask for it.
Staff can approve a channel that holds another customer's members after
reviewing who is in it.

## What Apostra answers in a channel shared with another company

Some channels are shared between two companies, for example a buyer and a seller
working on a buy together. Everyone in the channel reads every answer, so
Apostra answers only what both companies may see, and nothing more. This applies
once the channel is cleared for account data and Apostra staff have recorded
the other company as a participant of the channel.

Apostra answers these:

* **The buy between the two companies, and its delivery.** Apostra shows the
  buy's flight dates, its name and status where the channel's account sees
  them, and the buy's delivery figures. It never shows the buy's budget: the
  buyer's budget includes the buyer's own fees, which the seller does not see.
  It shows only a buy that sits between the two companies in the channel. A buy
  either company has with a third company is not shown, and neither is any other
  detail of either account. If three or more companies share the channel, Apostra
  shows no buy at all, because a buy has two parties and the others would read
  it too.
* **What an account owner disclosed in this channel.** The owner of a campaign
  can ask Apostra to share it in the channel, and Apostra asks them to confirm.
  From then on Apostra shows the campaign's name, status, flight dates and
  budget in that channel only, until the owner stops sharing it. A campaign
  shared in one channel is not shared in another channel with the same company.
* **Public information.** Apostra's published documentation and the AdCP
  specifications.
* **Supply tracking for the other company.** A request to track inventory is
  limited to the other company's own domains. You can also file a request for
  the Apostra team from the channel.

Everything else needs a private channel or a direct message with Apostra. That
includes an account's other buys, advertisers, spend, settings and connections.
When you ask for something in this group, Apostra says it is not available in
this channel because it is shared with the other company, and suggests a private
channel or a direct message.

## Permissions Apostra asks for

Slack calls these permissions scopes. They are all bot scopes, which means they
belong to the Apostra app in your workspace and not to any one person. Apostra
does not request permissions that act as an individual user.

| Scope | Why Apostra asks for it |
| - | - |
| `app_mentions:read` | Apostra replies when someone mentions @Apostra in a channel it has been added to. |
| `assistant:write` | Runs Apostra as a Slack agent: it sets the "thinking" status and suggested prompts in the agent pane. |
| `channels:history` | Apostra reads messages in public channels it has been added to, so it can answer in the thread with the conversation's context. In channels linked to a customer account, or from a person whose company Apostra knows, it also stores the messages as account activity for Apostra's account team. When Apostra joins a channel it posts a message telling members this. |
| `groups:history` | The same as `channels:history`, for private channels a member has invited Apostra to. Apostra cannot add itself to a private channel. |
| `im:history` | Reads direct messages people send to Apostra, so it can answer them. Direct messages are not stored as account activity. |
| `mpim:history` | Reads group direct messages that include Apostra, so it can answer them. Group direct messages are not stored as account activity. |
| `channels:read`, `groups:read`, `im:read`, `mpim:read` | Before answering, Apostra looks up the conversation's type and whether it is shared with another organization, and narrows what it will say in shared or external conversations. |
| `chat:write` | Posts Apostra's replies, progress updates and its notice that it has joined a channel. |
| `commands` | Handles the `/apostra` command and the older `/murph` command. |
| `reactions:write` | Adds an emoji reaction to acknowledge a message that needs no written reply, or to show Apostra is working on it. |
| `files:read` | Reads only the files a user attaches to a message addressed to Apostra, such as audio, images, PDFs and spreadsheets, so it can answer questions about them. It does not browse other files in the workspace. |
| `files:write` | Uploads files Apostra generates for the user, such as an `adagents.json` file, into the same thread. |
| `users:read` | Identifies the Slack member who asked, so Apostra answers in the right account and can address them by name. |
| `users:read.email` | Matches the asking member to their Apostra account by email. Email alone never grants access: the account must be active and the match unique. In any channel, the email's company domain attributes a message to the right organization. |

### Why Apostra needs email addresses

`users:read.email` is the permission that lets Apostra see a Slack member's email
address. Apostra uses it for two things:

* to match a person to their Apostra login, so it can answer questions about
  their own account; and
* in any channel Apostra has been added to, to read the company domain of a
  message's author, so the message is attributed to the right organization.

Apostra does not use a Slack email address to contact anyone on its own. The one
case where an address leaves Slack is a person choosing **Request access from
admin**, described above.

Apostra does not ask for permission to read canvases, change do-not-disturb
settings, read links shared in messages, use Slack's MCP server, start direct
messages, or read reactions.

## What Apostra does with messages

**Apostra reads messages in the channels it has been added to**, and direct
messages and group direct messages sent to it. What it keeps depends on where
the message is.

**Channel messages are kept as account activity in two cases.** Apostra's account
team can see this activity next to the customer's other work.

* The channel is linked to a customer account.
* The author's work email belongs to a company Apostra already knows. Messages
  from bots, from people with a personal email address, and from Apostra staff
  are not kept on this basis.

A channel message that meets neither condition is not kept as account activity. In
a channel that is not linked to an account, Apostra does not pass a message to the
assistant unless it mentions Apostra or uses `/apostra`. In a channel that is
linked to an account, Apostra can pick up a message that does not mention it and
decide whether to answer, react or stay silent.

If someone edits a saved message in Slack, the saved copy is updated. If someone
deletes it, the saved text is cleared.

**Direct messages and group direct messages are never kept as account activity.**
Apostra reads them to answer the person who wrote to it.

**Your conversations with Apostra are saved as conversation history in Apostra.**
Apostra sends the text of a message addressed to it, and any file attached to it,
to the AI providers listed in [AI providers](https://docs.apostra.com/v3/ai-providers.md) to produce the
answer.

For the terms that apply to this data, see the
[Apostra Privacy Policy](https://apostra.com/agreements/privacy-policy).

## Uninstall

A Slack admin removes Apostra from Slack's **Manage apps** page: open the Apostra
app and remove it from the workspace.

When the app is removed:

* Slack revokes Apostra's access to the workspace, and Apostra stops answering
  there.
* Apostra deletes its records of which Slack member is which Apostra login, and
  the links between Slack threads and Apostra conversations. If you install again,
  Apostra links people to their logins again from their email addresses.
* Conversations that belong to an Apostra account stay part of that account's
  history. Uninstalling does not delete them.
* Links between channels and Apostra accounts that an organization saved remain on
  record as disabled settings. They cannot send or answer anything without an
  active installation.

## Questions

Email [support@apostra.com](mailto:support@apostra.com), or see
[Get support](https://docs.apostra.com/v3/support.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.