Skip to content

Commit 384a126

Browse files
Niloth-pNiloth-p
committed
integration-docs: Update the Google Calendar integration doc.
1 parent 929e71e commit 384a126

File tree

1 file changed

+150
-50
lines changed
  • zulip/integrations/google

1 file changed

+150
-50
lines changed

‎zulip/integrations/google/doc.md

Lines changed: 150 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -1,72 +1,172 @@
1-
Get Google Calendar reminders in Zulip! This is a great way to see
2-
your reminders directly in your Zulip feed.
1+
# Zulip Google Calendar integration
2+
3+
Get Zulip notifications for your Google Calendar events!
4+
5+
### Create Zulip bot for Google Calendar notifications
6+
7+
{start_tabs}
8+
9+
1. {!create-a-generic-bot.md!}
310

411
1. {!download-python-bindings.md!}
512

6-
This bot should be set up on a trusted machine, because your API
7-
key is visible to local users through the command line or config
8-
file.
13+
1. [Download your bot's `zuliprc` file][download-zuliprc], and save it as
14+
`.zuliprc` in your `~/` directory.
15+
16+
[download-zuliprc]: /api/configuring-python-bindings#download-a-zuliprc-file
17+
18+
1. Optionally, to configure the bot, add a **google-calendar** section to
19+
the `.zuliprc` file, like below:
20+
21+
```
22+
[google-calendar]
23+
calendar=primary
24+
interval=3600
25+
tokens_path=/home/username/zulip/integrations/google-oauth-tokens.json
26+
client_secret_path=/home/username/zulip/integrations/client-secret-credentials.json
27+
channel=core-team
28+
topic=scheduled events
29+
noauth_local_webserver=
30+
format_message=The event [{title}]({calendar_link}), at {location}, is from {start} to {end}.\n> {description}\n\n[Join call]({google_meet_link}).
31+
```
32+
33+
See [configuration options](#configuration-options) for the list of
34+
available options.
35+
36+
{end_tabs}
37+
38+
### Setup Google OAuth Client ID
39+
40+
{start_tabs}
41+
42+
!!! tip ""
43+
44+
A free Google account is sufficient for this integration, a Google
45+
service account is not required.
46+
47+
1. In the Google Cloud console, go to
48+
**Menu > Google Auth platform > [Clients][clients-menu]**. Click
49+
**Create Client**.
50+
51+
[clients-menu]: https://console.cloud.google.com/auth/clients
52+
53+
1. Select **Application type > Desktop app**. Set **Name** to a name of
54+
your choice, such as `Zulip`, and click **Create**. Save the downloaded
55+
JSON file as `client_secret.json` in your `~/` directory.
56+
57+
1. From your Google Cloud dashboard, go to **APIs & Services** and select
58+
**OAuth consent screen**. Under **Test users**, click **+ Add Users**.
59+
Enter the email address corresponding to your Google Calendar, and click
60+
**Save**.
61+
62+
{end_tabs}
63+
64+
### Run the integration script
65+
66+
{start_tabs}
67+
68+
1. Install the requirements for the integration script with:
69+
70+
`python {{ integration_path }} --provision`
71+
72+
1. Run the integration script with:
73+
74+
`python {{ integration_path }}`
75+
76+
Authorize access in the browser window that opens, to allow the Zulip
77+
bot to view your Calendar. If you've turned on the
78+
`noauth_local_webserver` option, follow the terminal prompts instead,
79+
and paste the resulting authorization code.
80+
81+
1. Optionally, pass [commandline arguments](#configuration-options) to
82+
configure the integration. The commandline arguments override the
83+
corresponding settings in the `.zuliprc` file.
84+
85+
```
86+
python {{ integration_path }} \
87+
--calendar primary \
88+
--interval 3600 \
89+
--client-secret-file /home/username/zulip/integrations/client-secret-credentials.json \
90+
--tokens-file /home/username/zulip/integrations/google-oauth-tokens.json \
91+
--channel core-team \
92+
--topic scheduled-events \
93+
--format-message "The event [{title}]({calendar_link}), at {location}, is from {start} to {end}.\n> {description}\n\n[Join call]({google_meet_link})."
94+
```
95+
96+
See [configuration options](#configuration-options) for the list of
97+
available options.
98+
99+
1. You will get reminders as long as the terminal session with the bot
100+
remains open. Consider using `screen` to run the bot in the background.
101+
102+
!!! tip ""
103+
104+
Newly added calendar events may take up to 10 minutes to generate
105+
notifications.
106+
107+
{end_tabs}
9108
10-
1. Next, follow the instructions for **Step 1** at
11-
[this link](https://developers.google.com/google-apps/calendar/quickstart/python)
12-
to get a `client_secret` file. Save this file as `client_secret.json`
13-
to your `~/` directory.
109+
### Configure the integration
14110
15-
1. Next, install the latest Google API Client for Python by following the
16-
instructions on the
17-
[Google website](https://developers.google.com/api-client-library/python/start/installation).
111+
The integration can be configured by:
18112
19-
1. In Zulip, go to your click on the cog in the top right corner, and
20-
then clicking on **Personal settings**.
113+
* Passing command line arguments to the integration script.
114+
* Editing the `google-calendar` section of the `zuliprc` file.
21115
22-
1. Click on the tab that’s labeled **Account & privacy** and click on
23-
**Manage your API key**. Enter your password if prompted, and
24-
download the `zuliprc` file. Save this file as `.zuliprc` to your `~/`
25-
directory.
116+
The configuration settings in `zuliprc` will be overridden by the
117+
corresponding command line options, if both are used.
26118
27-
![Download zuliprc file](/static/images/integrations/google/calendar/001.png)
119+
### Configuration options
28120
29-
1. Run the `get-google-credentials` with this command:
121+
The integration script accepts the following configuration options:
30122
31-
python /usr/local/share/zulip/integrations/google/get-google-credentials
123+
* `calendar`: The `calendar ID` of the Google calendar to get events from.
124+
By default, the `primary` calendar is used.
32125
33-
1. It should open up a browser and ask you for certain permissions. Give
34-
Zulip access, and move on to the next step. If it doesn’t open a
35-
browser, follow the instructions in the terminal window.
126+
* `interval`: How many minutes in advance you want reminders delivered.
127+
The default value is 30 minutes.
36128
37-
1. Now, all that’s left to do is to run the `gcal-bot` script, in the
38-
same directory as the `get-google-credentials` script, with the
39-
necessary parameters:
129+
* `channel`: The name of the Zulip channel you want to receive
130+
notifications in. By default, messages are sent to the DMs of the bot
131+
owner.
40132
41-
python /usr/local/share/zulip/integrations/google/gcal-bot --user [email protected]
133+
* `topic`: The name of the Zulip topic you want to receive notifications
134+
in. This option is ignored if the `channel` option is unspecified. If the
135+
`channel` option is specified but the `topic` option is not, notifications
136+
are sent to a topic named "calendar-reminders" in the channel.
42137
43-
The `--user` flag specifies the user to send the reminder to.
138+
* `client-secret-file`: The path to the file containing the client secret.
139+
By default, the client secret file is assumed to be at
140+
`~/client_secret.json`.
44141
45-
1. Don’t close the terminal window with the bot running (you can use
46-
`screen` if needed). You will only get reminders if the bot is still
47-
running.
142+
* `tokens-file`: The path to the file where the OAuth tokens are stored. By
143+
default, the tokens file is generated at `~/google-tokens.json` after the
144+
first run.
48145
49-
{!congrats.md!}
146+
* `noauth-local-webserver`: This option stops the integration script from
147+
starting a local webserver for receiving OAuth tokens. The default
148+
authorization process runs a local web server, which requires a browser on
149+
the same machine. For non-interactive environments and machines without
150+
browser access, e.g., remote servers, this option allows manual
151+
authorization. The authorization URL is printed, which the user can copy
152+
into a browser, copy the resulting authorization code, and paste back into
153+
the command line.
50154
51-
![Calendar demo](/static/images/integrations/google/calendar/003.png)
155+
* `format-message`: The template for the message that is sent to Zulip. This
156+
Python f-string supports Markdown, and can use the following variables:
157+
`start`, `end`, `title`, `description`, `calendar_link`, `location`,
158+
`google_meet_link`.
52159
53-
## Supported parameters
160+
!!! warn ""
54161
55-
There are two optional flags that you can specify when running this
56-
script:
162+
**Note:** The `title`, `description`, `location`, and
163+
`google_meet_link` variables are optional for Google Calendar
164+
events, and hence may be empty. Empty fields are displayed as
165+
"{No title}", "{No description}", "{No location}", and "{No link}"
166+
in the message template.
57167
58-
* `--calendar`: This flag specifies the calendar to watch from the
59-
user’s Google account. By default, this flag is set to a user’s
60-
primary or default calendar. To specify a calendar, you need the
61-
calendar ID which can be obtained by going to Google Calendar and
62-
clicking on the wedge next to the calendar’s name. Click on settings
63-
in **Calendar settings** in the drop down, and look for the **Calendar
64-
Address** section. Copy the **Calendar ID** from the right side of the
65-
page and use that as the value for this flag.
168+
### Related documentation
66169
67-
![Specify a calendar](/static/images/integrations/google/calendar/002.png)
170+
* [Google's documentation on setting up OAuth Client IDs][client-secret]
68171
69-
* `--interval`: This flag specifies the interval of time - in
70-
minutes - between receiving the reminder, and the actual event. For
71-
example, an interval of 30 minutes would mean that you would receive a
72-
reminder for an event 30 minutes before it is scheduled to occur.
172+
[client-secret]: https://developers.google.com/workspace/calendar/api/quickstart/python#authorize_credentials_for_a_desktop_application

0 commit comments

Comments
 (0)