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
|
# Bots and Webhooks
Base endpoint is: `/ocs/v2.php/apps/spreed/api/v1`: (requires the `bots-v1` capability - available since Nextcloud 27.1)
Webhook based bots are available with the Nextcloud 27.1 compatible Nextcloud Talk 17.1 release as a first version
!!! note
For security reasons bots can only be added via the
command line. `./occ talk:bot:install --help` gives you
a short overview of the required arguments, but they are
also explained in the [OCC documentation](occ.md#talkbotinstall).
---
## Receiving chat messages
Messages are signed using the shared secret that is specified when installing a bot on the server.
Create a HMAC with SHA256 over the `RANDOM` header and the request body using the shared secret.
Only when the `SIGNATURE` matches the request should be accepted and handled.
**Sample PHP code:**
```php
$digest = hash_hmac('sha256', $_SERVER['HTTP_X_NEXTCLOUD_TALK_RANDOM'] . file_get_contents('php://input'), $secret);
if (!hash_equals($digest, strtolower($_SERVER['HTTP_X_NEXTCLOUD_TALK_SIGNATURE']))) {
exit;
}
```
### Headers
| Header | Content type | Description |
|-----------------------------------|---------------------|------------------------------------------------------|
| `HTTP_X_NEXTCLOUD_TALK_SIGNATURE` | `[a-f0-9]{64}` | SHA265 signature of the body |
| `HTTP_X_NEXTCLOUD_TALK_RANDOM` | `[A-Za-z0-9+\]{64}` | Random string used when signing the body |
| `HTTP_X_NEXTCLOUD_TALK_BACKEND` | URI | Base URL of the Nextcloud server sending the message |
### Content
The content format follows the [Activity Streams 2.0 Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/).
#### Sample chat message
```json
{
"type": "Create",
"actor": {
"type": "Person",
"id": "users/ada-lovelace",
"name": "Ada Lovelace"
},
"object": {
"type": "Note",
"id": "1567",
"name": "message",
"content": "{\"message\":\"hi {mention-call1} !\",\"parameters\":{\"mention-call1\":{\"type\":\"call\",\"id\":\"n3xtc10ud\",\"name\":\"world\",\"call-type\":\"group\",\"icon-url\":\"https:\\/\\/nextcloud.local\\/ocs\\/v2.php\\/apps\\/spreed\\/api\\/v1\\/room\\/n3xtc10ud\\/avatar\"}}}",
"mediaType": "text/markdown"
},
"target": {
"type": "Collection",
"id": "n3xtc10ud",
"name": "world"
}
}
```
#### Explanation
| Path | Description |
|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| actor.id | One of the known [attendee types](constants.md#attendee-types) followed by the `/` slash character and a unique identifier within the given type. For users it is the Nextcloud user ID, for guests a sha1 value. |
| actor.name | The display name of the attendee sending the message. |
| object.id | The message ID of the given message on the origin server. It can be used to react or reply to the given message. |
| object.name | For normal written messages `message`, otherwise one of the known [system message identifiers](chat.md#system-messages). |
| object.content | A JSON encoded dictionary with a `message` and `parameters` key. The message can include placeholders and the [Rich Object parameters](https://github.com/nextcloud/server/blob/master/lib/public/RichObjectStrings/Definitions.php) are rendered into it in the chat view. |
| object.mediaType | `text/markdown` when the message should be interpreted as Markdown. Otherwise `text/plain`. |
| target.id | The token of the conversation in which the message was posted. It can be used to react or reply to the given message. |
| target.name | The name of the conversation in which the message was posted. |
## Sending a chat message
Bots can also send message. On the sending process the same signature/verification method is applied.
* Required capability: `bots-v1`
* Method: `POST`
* Endpoint: `/bot/{token}/message`
* Header:
| Name | Description |
|----------------------------------|-----------------------------------------------------------------|
| `X-Nextcloud-Talk-Bot-Random` | The random value used when signing the request |
| `X-Nextcloud-Talk-Bot-Signature` | The signature to validate the request comes from an enabled bot |
| `OCS-APIRequest` | Needs to be set to `true` to access the ocs/vX.php endpoint |
* Data:
| field | type | Description |
|--------------------|--------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `message` | string | The message the user wants to say |
| `replyTo` | int | The message ID this message is a reply to (only allowed for messages from the same conversation and when the message type is not `system` or `command`) |
| `referenceId` | string | A reference string to be able to identify the message again in a "get messages" request, should be a random sha256 |
| `silent` | bool | If sent silent the message will not create chat notifications even for users |
* Response:
- Status code:
+ `201 Created` When the message was posted successfully
+ `400 Bad Request` When the provided replyTo parameter is invalid or the message is empty
+ `401 Unauthenticated` When the bot could not be verified for the conversation
+ `404 Not Found` When the conversation could not be found
+ `413 Payload Too Large` When the message was longer than the allowed limit of 32000 characters (or 1000 until Nextcloud 16.0.1, check the `spreed => config => chat => max-length` capability for the limit)
+ `429 Too Many Requests` When `401 Unauthenticated` was triggered too often
## Reacting to a chat message
Bots can also react to a message. The same signature/verification method is applied.
* Required capability: `bots-v1`
* Method: `POST`
* Endpoint: `/bot/{token}/reaction/{messageId}`
* Header:
| Name | Description |
|----------------------------------|-----------------------------------------------------------------|
| `X-Nextcloud-Talk-Bot-Random` | The random value used when signing the request |
| `X-Nextcloud-Talk-Bot-Signature` | The signature to validate the request comes from an enabled bot |
| `OCS-APIRequest` | Needs to be set to `true` to access the ocs/vX.php endpoint |
* Data:
| field | type | Description |
|------------|--------|----------------|
| `reaction` | string | A single emoji |
* Response:
- Status code:
+ `201 Created` When the reaction was created successfully
+ `400 Bad Request` When the provided emoji was invalid
+ `401 Unauthenticated` When the bot could not be verified for the conversation
+ `404 Not Found` When the conversation or message could not be found
+ `429 Too Many Requests` When `401 Unauthenticated` was triggered too often
## Delete a reaction
Bots can also remove their previous reaction from amessage. The same signature/verification method is applied.
* Required capability: `bots-v1`
* Method: `DELETE`
* Endpoint: `/bot/{token}/reaction/{messageId}`
* Header:
| Name | Description |
|----------------------------------|-----------------------------------------------------------------|
| `X-Nextcloud-Talk-Bot-Random` | The random value used when signing the request |
| `X-Nextcloud-Talk-Bot-Signature` | The signature to validate the request comes from an enabled bot |
| `OCS-APIRequest` | Needs to be set to `true` to access the ocs/vX.php endpoint |
* Data:
| field | type | Description |
|------------|--------|----------------|
| `reaction` | string | A single emoji |
* Response:
- Status code:
+ `200 OK` When the reaction was deleted successfully
+ `400 Bad Request` When the provided emoji was invalid
+ `401 Unauthenticated` When the bot could not be verified for the conversation
+ `404 Not Found` When the conversation or message could not be found
+ `429 Too Many Requests` When `401 Unauthenticated` was triggered too often
|
