-
Notifications
You must be signed in to change notification settings - Fork 1
/
quickstart.Rmd
178 lines (124 loc) · 6.28 KB
/
quickstart.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
---
title: "Getting Started with sendeR"
date: 2019-11-14
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{quickstart}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
library(sendeR)
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")
```
## Introduction
This document contains a description for every service implemented in the `sendeR` package on how to start sending messages with it. Each chapter contains information about acquiring either an API webhook, a token or some other form of credentials required for sending messages via the API.
Other than the API access acquisition usage of each client is very straightforward. With the acquired form of authorization we create a client for the service. Once the service client is created the `send_message` has three basic parameters:
* `client` - the created client,
* `message` - a text message to be sent,
* `destination` - a chat id.
Additionally, a client specific arguments can be passed through the ellipsis. Those arguments are also covered below.
## Gmail
### Credentials acquisition
First visit Google API web interface: https://console.developers.google.com/apis/credentials
Click Select a project, then NEW PROJECT, and enter a name for the project, and optionally, edit the provided project ID. Click Create.
On the Credentials page, select Create credentials, then OAuth client ID.
You may be prompted to set a product name on the Consent screen; if so, click Configure consent screen, supply the requested information, and click Save to return to the Credentials screen.
Select Other for the Application type, and enter any additional information required.
Click Create.
On the page that appears, copy the client ID and client secret to your clipboard, as you will need them when you configure your client library.
### Destination argument details
Destination for `client_gmail` simply is a recipient's email. It does not have
be your own email!
### Additional `send_message` arguments
`send_message.client_gmail` has one additional argument:
* `subject` - a subject of the email message to be sent.
## Slack
### Credentials acquisition
Create a Slack app here: https://api.slack.com/apps?new_app=1
Enable Incoming Webhooks from the settings page.
After the settings page refreshes, click Add New Webhook to Workspace.
Pick a channel that the app will post to, then click Authorize.
Use your Incoming Webhook URL to post a message to Slack.
### Destination argument details
For `client_slack` this argument is not used because the created webhook is tied to a specific channel what renders `destination` parameter redundant. However the argument has to be present for implementing the main `send_message` method.
### Additional `send_message` arguments
`send_message.client_slack` has no additional parameters as of now.
## Telegram
### Credentials acquisition
Creating a Telegram bot is really simply (simpler than guessing your chat id I would say!). To create the bow simply find the `@BotFather` - chat with it should look similarly to this:
Once the chat is started BotFather will send a message with available commands. The one which interests us is `/newbot`. After sending the command we will be prompted to enter our bot display name.
Once the display name is provided we will be asked for bot username, that is, the name which we can @tag the bot or search for it in the Telegram.
Once that is done BotFather will send the message with our bot API token. This token is passed to the `client_telegram` function of `sendeR` package.
### Destination argument details
For Telegram client the `destination` argument is a chat_id where the message is supposed to be sent. Before sending messages we have to determine what is the chat id we want to use.
#### One on one chats
If we want to send messages to the one on one chat with bot. To do that open the chat with bot and initialize the chat by pressing `/start` as shown below.
{width=45%} {width=45%}
Now we will use the bot to read our chat id. In order to do so head to `https://api.telegram.org/bot<your-bot-token>/getupdates`. Page should display a JSON response with no updates received by the bot:
```{r, eval = FALSE}
{
"ok": true,
"result": []
}
```
Sending an example message "Hello!" to the bot and refreshing the page should result in response containing information similar to the one below (among other parameters).
```{r, eval = FALSE}
{
"ok": true,
"result": [
{
"update_id": 164384282,
"message": {
"message_id": 2,
"from": {
"id": your_user_id
},
"chat": {
"id": your_chat_id
},
"date": 1573660088,
"text": "Hello!"
}
}
]
}
```
Here is the chat id (the `destination` parameter) we were looking for.
Note that the chat id and the user id are the same that is due to the user id being used as chat id for one on one chats.
#### Group chats
Similarly to the one on one chats we have to retrieve the information from `https://api.telegram.org/bot<your-bot-token>/getupdates` page.
To get group's chat id we need to add our bot to the group. Once the bot is added to the group an update containing following information should appear if we refresh the above page:
```{r, eval = FALSE}
{
"ok": true,
"result": [
{
"update_id": 164384283,
"message": {
"message_id": 3,
"from": {
"id": your_user_id,
},
"chat": {
"id": your_group_id,
"type": "group"
},
"date": 1573661039,
"group_chat_created": true
}
}
]
}
```
From the response we can extract the group id (note: group ids are negative numbers).
### Additional `send_message` arguments
`send_message.client_telegram` has no additional parameters as of now.