Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update Slack bot integration docs for frontend event handling #9

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Binary file modified images/slack-event-subscriptions.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified images/slack-ngrok-url.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added images/slack-url-verified.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
48 changes: 34 additions & 14 deletions integrations/slack-bot.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,13 +21,17 @@ For self-hosted version, you first need to setup a Slack App manually to get a b
2. **Select Slack Bot**
- Click on the "Slack Bot" option.

<img src="/images/gurubase-integrations-1.png" alt="Gurubase integrations page" className="mt-4" />
<Frame>
<img src="/images/gurubase-integrations-1.png" alt="Gurubase integrations page"/>
</Frame>

3. **Connect to Slack**
- Click the "Connect" button.
- Authorize Gurubase to access your Slack workspace.

<img src="/images/gurubase-slack-integrations-2.png" alt="Gurubase slack integration page" className="mt-4" />
<Frame>
<img src="/images/gurubase-slack-integrations-2.png" alt="Gurubase slack integration page" />
</Frame>


4. **Select Channels**
Expand All @@ -38,13 +42,17 @@ For self-hosted version, you first need to setup a Slack App manually to get a b
To subscribe to a private channel and send test messages to it, you need to invite the bot to the channel. You can do so from the Slack app using the "Add apps to this channel" command. This is not needed for public channels.
</Note>

<img src="/images/gurubase-slack-integrations-3.png" alt="Gurubase slack integration page" className="mt-4" />
<Frame>
<img src="/images/gurubase-slack-integrations-3.png" alt="Gurubase slack integration page" />
</Frame>


5. **Test the Connection**
- Use the "Send Test Message" button to ensure the integration is working.

<img src="/images/gurubase-slack-integrations-4.png" alt="Gurubase slack integration page" className="mt-4" />
<Frame>
<img src="/images/gurubase-slack-integrations-4.png" alt="Gurubase slack integration page" />
</Frame>

## Permissions

Expand All @@ -64,26 +72,34 @@ For self-hosted version, you need to create your own Slack app to create a bot t

1. Go to https://api.slack.com/apps and click "Create New App".
2. Select "From scratch", give it a name and pick your workspace.
3. Slack will send events to `/slack/events/` endpoint of your Gurubase backend instance. If the backend URL is not public, you need to open it to public. You can use [ngrok](https://ngrok.com/) to do this:
- If you haven't changed the default ports of Gurubase, port 8029 is for the frontend UI, and port 8028 is for the backend. You need to use the backend URL to make it accessible to the public.
- Make backend URL public with `ngrok http http://localhost:8028`
3. Slack will send events to `/api/slack/events/` endpoint of your Gurubase instance. If the Gurubase instance URL is not public, you need to open it to public. You can use [ngrok](https://ngrok.com/) to do this:
- If you haven't changed, the default port of Gurubase instance is 8029. You need to use this to make it publicly accessible.
- Make Gurubase instance URL public with `ngrok http http://localhost:8029`
- Copy the public URL from the ngrok terminal as shown below:

<img src="/images/slack-ngrok-url.png" width="500"/>
<Frame>
<img src="/images/slack-ngrok-url.png"/>
</Frame>

4. Go to "Event Subscriptions" page on your Slack app and enable it.
5. Set your public url along with the path `/slack/events/` as "Request URL", this is the url that Slack will send the events to. Be careful with the trailing slash at the end of the url.
- `${your_public_backend_url}/slack/events/`
5. Set your public url along with the path `/api/slack/events/` as "Request URL", this is the url that Slack will send the events to. Be careful with the trailing slash at the end of the url. You should see the "Verified" green text if the url is correct.
- `${your_public_gurubase_url}/api/slack/events/`

<Frame>
<img src="/images/slack-url-verified.png"/>
</Frame>

<Note type="warning">
If you change the backend URL, you need to update the "Request URL" with the new URL.
If you change the Gurubase instance URL, you need to update the "Request URL" with the new URL.
</Note>

6. Expand the "Subscribe to bot events" section on "Event Subscriptions" page and add the following events:
- `message.channels`
- `message.groups`

<img src="/images/slack-event-subscriptions.png" width="500"/>
<Frame>
<img src="/images/slack-event-subscriptions.png" width="500"/>
</Frame>

7. Save changes.
8. Go to "OAuth & Permissions" page on Slack app. Scroll to "Bot Token Scopes" under "Scopes" section and add the following permissions:
Expand All @@ -94,15 +110,19 @@ If you change the backend URL, you need to update the "Request URL" with the new
- `channels:history`
- `groups:history`

<img src="/images/slack-bot-permissions.png" width="500"/>
<Frame>
<img src="/images/slack-bot-permissions.png" width="500"/>
</Frame>

9. Go to "Install App" page. Then click "Install to [your_workspace_name]".
10. Go through the OAuth flow.
11. After installation, you will be redirected to the same page.
12. Copy "Bot User OAuth Token".
13. Go to your guru's Slack integration page in the Gurubase UI and paste the bot token you copied and click "Connect".

<img src="/images/slack-bot-token-input.png" className="mt-4"/>
<Frame>
<img src="/images/slack-bot-token-input.png"/>
</Frame>

14. You can now follow the [Steps to Integrate](/integrations/slack-bot#steps-to-integrate).

Expand Down
16 changes: 9 additions & 7 deletions integrations/website-widget.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -37,16 +37,18 @@ Before adding the widget, make sure you have:
<img src="/images/gurubase-create-widget.jpg" alt="Create Widget ID" className="mt-4" />
</Frame>

<Note>
Each Widget ID is restricted to work only on the specific domain it was created for. For example:

- A Widget ID created for `https://www.example.com` will only work on that exact domain
- It won't work on subdomains like `https://docs.example.com`
- It won't work on different domains like `https://example.org`
- For local development, you'll need to create a separate Widget ID using your development URL (e.g. `http://localhost:3000`)
- If a Widget ID created for `https://www.example.com` will only work on that exact domain.
- It won't work on subdomains like `https://docs.example.com`
- It won't work on different domains like `https://example.org`
- For local development, you need to create a separate Widget ID using your development URL (e.g., `http://localhost:3000`)
- Domain input supports wildcard (`*`) expression:
- `*.example.com` will match any subdomain of `example.com`
- `http://localhost:*` will match any port of `localhost`
- `*` will match any domain, so be careful with this option! Anyone who knows your Widget ID can send requests to your Guru.

Make sure to create Widget IDs for each domain where you want to use the widget.
</Note>

## Basic Installation

Expand Down Expand Up @@ -77,7 +79,7 @@ For more examples like Astro - Starlight, Docusaurus, Mintlify, MKDocs, Next.js,
## Self-hosted Installation

<Note type="warning">
If you're using self-hosted Gurubase, you must set the backend URL using the `data-baseUrl` attribute. The default backend URL of Self-hosted Gurubase is `http://localhost:8029/api/`.
If you're using self-hosted Gurubase, you must set the Gurubase instance URL using the `data-baseUrl` attribute. The default URL of Self-hosted Gurubase instance is `http://localhost:8029/api/`.

```html
<script async src="https://widget.gurubase.io/widget.latest.min.js"
Expand Down