Updated documentation to be more understandable

Author: GuiLeme

_posts/2.5/2021-06-09-new.md

@@ -67,7 +67,39 @@ Private guest lobby message, display position in waiting line
 
 A new API endpoint was added: `/insertDocument`. Now, it is possible to send a batch of documents with all the common presentation parameters such as `current`, `downloadable` and `removable`. 
 
-All the presentations are sent via payload (the body of the request), whether by a link to download the file or by `base64` encoded file.
+All the presentations are sent via payload (the body of the request) such as when preuploading documents in `/create` endpoint, whether by a link to download the file or by `base64` encoded file.
+
+You can send the request via greenlight or bash, as displayed below:
+
+``` bash
+curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '<modules>
+   <module name="presentation">
+        <document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
+        <document removable="false" name="sample.pdf">
+        JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
+        </document>
+   </module>
+</modules>'
+```
+
+More explicitly, in xml we have:
+
+``` xml
+<modules>
+   <module name="presentation">
+        <document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
+        <document removable="false" name="sample.pdf">
+          JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
+        </document>
+   </module>
+</modules>
+```
+
+Now just the request:
+
+``` bash
+curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '{xml}'
+```
 
 ## Engagement
 

_posts/dev/2015-04-05-api.md

@@ -19,6 +19,7 @@ For developers, this API enables you to
 - create meetings
 - join meetings
 - end meetings
+- insert documents
 - get recordings for past meetings (and delete them)
 - upload closed caption files for meetings
 
@@ -79,6 +80,11 @@ Updated in 2.5:
 
 - **create** - **Added:** `meetingCameraCap`, `groups`, `disabledFeatures`, `meetingExpireIfNoUserJoinedInMinutes`, `meetingExpireWhenLastUserLeftInMinutes`; **Deprecated:** `learningDashboardEnabled`, `breakoutRoomsEnabled`, `virtualBackgroundsDisabled`.
 
+- **insertDocument** 
+    - New endpoint created;
+    - It is responsible to insert a presentation in a meeting that already exists;
+    - It works the same way as preuploading documents in `/create` endpoint: the requests are sent with a payload expliciting the presentations in a xml string. As an example refer to the [notes in "new" route.](#insertdocument)
+
 # API Data Types
 
 There are three types in the API.
@@ -324,6 +330,7 @@ The following section describes the administration calls
 | create              | Creates a new meeting.                                                                         |
 | join                | Join a new user to an existing meeting.                                                        |
 | end                 | Ends meeting.                                                                                  |
+| insertDocument      | Insert a batch of documents via API call                                                       | 
 
 ## Monitoring
 
@@ -529,6 +536,54 @@ There is only an XML response for this call if the `redirect` parameter is set t
 </response>
 ```
 
+## insertDocument
+
+This endpoint insert one or more documents into a running meeting via API call
+
+**Resource URL:**
+
+http&#58;//yourserver.com/bigbluebutton/api/insertDocument?[parameters]&checksum=[checksum]
+
+**Parameters:**
+
+{% include api_table.html endpoint="insertDocument" %}
+
+**Example Requests:**
+
+You can do the request either via greenlight or `curl`, which I am going to demonstrate in the following paragraph.
+
+First, it is necessary to have the xml string with the batch of the wanted presentations in hand. As an example, see the xml down below:
+
+``` xml
+<modules>
+   <module name="presentation">
+        <document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
+        <document removable="false" name="sample.pdf">
+          JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
+        </document>
+   </module>
+</modules>
+```
+
+Now you need to write the `curl` command which will be:
+
+``` bash
+curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '{xml}'
+```
+
+Combining both together, we get:
+
+``` bash
+curl -s -X POST "https://{your-host}/bigbluebutton/api/insertDocument?meetingID=Test&checksum=6b76e90b9a20481806a7ef513bc81ef0299609ed" --header "Content-Type: application/xml" --data '<modules>
+   <module name="presentation">
+        <document current="true" downloadable="true" url="{link to download the presentation}" filename="sample.pdf"/>
+        <document removable="false" name="sample.pdf">
+        JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoT3RoZXJfc2FtcGxlKQovUHJvZHVjZXIgKFNraWEvUERGIG0xMDAgR29vZ2xlIERvY3MgUmVuZGVyZXIpPj4KZW5... {base64 encoded document}
+        </document>
+   </module>
+</modules>'
+```
+
 ## isMeetingRunning
 
 This call enables you to simply check on whether or not a meeting is running by looking it up with your meeting ID.