How to manage Queue Agents via REST APIPosted on: 2018-10-14 | Categories: VoIP Services VoIP Technology
In this post we will show how to use VoIPstudio REST API to make all Agents join or leave selected Queue. Normally Agents can join or leave the queue by dialling service code
#424* respectively or using Softphone settings panel. However in some situations it might be beneficial to automate this process by running scheduled task. How to create a scheduled task is beyond the scope of this article, however there is plenty of documentation and tutorials available on this topic.
Note: if you already have NodeJS installed on your computer, you can skip this section and move on to “Get the API client code” below.
Once we have NodeJS installed lets make sure it works correctly. Open terminal window (on Windows open Start menu and run “Command Prompt”) and execute:
this should produce output as below (version number may vary):
Get the API client code
git to clone the code, or simply download latest release as
.zip file and decompress on your computer. Once we have obtained the code, lets try to run it. In the terminal window execute:
cd queue-api node queue.js
this should produce output similar to below:
Error: VoIPstudio API credentials file [api.credentials] not found
This is expected error message, as before we can start using the API Client code, we need to obtain and API credentials and save them to `api.credentials` file.
Obtain API credentials
We need to save API credentials to a text file in the same folder where
queue.js file is. Open any text editor (such as Notepad on Windows), so we can copy/paste data we will obtain when following instructions in this section. To get API credentials login into your VoIPstudio account – note: it has to be one of the Administrators – and follow steps below:
1. Switch to Administration dashboard.
2. Open Users panel.
3. Click “Edit” icon next to one of the Administrator accounts.
4. Switch to Advanced tab.
5. Copy into clipboard “API User ID” and next paste it into text editor. Follow the User Id with “:”, so the content of text editor looks like:
10001: (your API User ID will be of course a different number).
6. Enter name of your API key. This can be anything – we will use “Queue Task”.
7. Select “30 days” as a Timeout. For security reasons if your API Key is not used within 30 days, it will be automatically invalidated.
8. Click “Add” to generate API Key.
9. Find API Key we just added on the list and click “Wrench” icon and select “Show Details” from the context menu.
10. Copy API Key into clipboard and paste it into text editor. The content of text editor should now look like below:
Note: API User ID number and the API Key will be different for you. The above is just an example text which is not a valid API Key.
Now save this text file as
api.credentials file in the same folder where
queue.js file is.
Run the code
We should be now ready to run the code. In the example below we will use “EST Support” as a Queue name, but of course you will use name of the Queue which exists on your VoIPstudio account. Lets open the terminal window and execute:
cd queue-api node queue.js
The above should produce output:
This script allows to make all Agents in selected Queue join or leave Usage: queue.js '<Queue Name>' <join|leave>
The message above indicates the script has correctly recognised
api.credentials file we created in previous step. However the script requires two parameters:
* “Queue Name” which is our example wil be “EST Support”
* join or leave depending which operation we want to perform.
So lets try to make all Agents of “EST Support” join the queue:
node queue.js 'EST Support' join
This time the output is:
2 Agents has joined queue "EST Support"
and in a similar way we can make all Agents leave “EST Support” queue by running:
node queue.js 'EST Support' leave
2 Agents has left queue "EST Support"
Now to automate the operation of joining and leaving queue by our Agents we just need to setup scheduled task which will execute
node queue.js 'EST Support' leave or
node queue.js 'EST Support' join at certain time of the day and days of the week.