NAV Navbar

Wickr IO

This document will walk you through the installation, configuration, and use of the Wickr IO Integration Gateway. Wickr IO allows users to use existing and custom software modules to interact with the Wickr platform. Throughout this document the term "integrations" will be used to reference these software modules. Integrations can be applications (aka Bots) or interfaces to applications, and can be coded to communicate with Wickr users, groups, or other Wickr IO integrations on the platform. The beauty of Wickr IO is that you can create your own integrations easily and quickly. Example integrations are available and will be referenced later in the document.

Integrations interact with the platform through the Wickr IO client application, which exists in the form of a Docker container and distributed via the Docker hub. Access to the Wickr IO Docker distribution is public. Creation of Wickr IO clients is currently supported only in Wickr Pro and Wickr Enterprise and requires admin access to the Wickr admin console. Wickr IO clients are essentially Wickr users on the platform, or technically speaking, client applications of users on the platform.

Assumptions

This document is intended for systems administrators and developers that have a working knowledge of Linux server administration, Docker, package installation, API usage, and scripting knowledge.

Wickr IO Components

The components of the Wickr IO integration gateway are:

You'll have to supply an appropriate host machine to run the Docker container and any Node.js software you use or develop. The Docker container includes several Node.js modules and sample solutions that use the Wickr IO Node.js addon. You'll also have the option of using your own or other Wickr IO integration modules published to the NPM registry.

An optional REST API is provided to support non-Node.js integrations as well as integrations with remote systems. This REST API is documented here.

Host Machine and Requirements

The Wickr IO Docker container should run on any Docker capable host machine, or virtual machine, however the majority of our development and testing is done on an AWS virtual host running Linux CentOS 7 or Linux Ubuntu 16.04. The Docker image uses the Ubuntu Linux operating system. The Wickr IO client software will require access to the file system running on the host machine so that persistent data can be stored. Depending on use case you may have to start the Docker container in a way to allow access to specific network ports as well.

The host machine used to run the Wickr IO Docker container needs to be setup to be running the appropriate Docker software. Please refer to the Docker website for instructions on how to install Docker on your system and to create a Docker login. You'll need a Docker login to pull down the images.

The Wickr IO Docker image will also require access to the host file system in order to save persistent data. This is necessary so that you can stop or upgrade the image without losing the state of your Wickr IO clients. You'll need to specify this location to the Docker image when you run it, details will be described later in this document.

The host machine must have enough disk space to support the clients running within the Wickr IO Docker container, as well as any space requirements of your integrations.

The host machine should be appropriately hardened to protect against unauthorized access.

Wickr IO Docker Container

The Wickr IO Docker container contains the Wickr IO client(s) and the client service and configuration software. Wickr IO clients provide a software interface to their capabilities, instead of via a graphical user interface (GUI). This software interface can be leveraged either through the native Node.js addon APIs or an optional REST service API to provide the ability to send and receive messages, as well as create secure rooms and group conversations.

Wickr IO Integration Software

There are two components to the Wickr IO integration software: the Wickr IO Node.js addon and the Wickr IO integration module(s).

The Wickr IO Node.js addon is a public module that's located in the NPM registry. Native JavaScript integrations use this addon to communicate with Wickr IO clients and will reference it by including it in the "dependencies" section of the package.json file of the integration. Details on how to use this addon will be described later in this document.

The sample Wickr IO integrations are JavaScript programs implemented using the Node.js addon APIs to communicate with a Wickr IO client. The Wickr IO Docker container includes several integrations that you can use as an example to build your own. Here is a sample of some of the integrations that are included with the container:

There are additional integration modules located in the NPM registry.

Quick Start

The following steps will create a Bot that will automatically respond when getting any message from a user.

  1. Create a Bot user by entering a display name, username, and password.
  2. Make a directory for your docker volume: mkdir /opt/WickrIO
  3. Download the Docker image: docker pull wickr/bot-cloud:latest
  4. Start the docker image in the foreground: docker run -v /opt/WickrIO:/opt/WickrIO -ti wickr/bot-cloud:latest
  5. Agree to the license agreement.
  6. Enter add at the prompt, filling in the username and password you created in step one.
  7. Enable autologin and choose the wickrio-hello-world-bot integration.
  8. Start the client by entering start and then y.
  9. Send a message to your new bot with Wickr Pro user in that network!

If you've followed along so far you now have the Hello World Bot running on your network! This Bot will automatically reply to incoming messages from users in rooms and conversations.

Installation

The Wickr IO Docker container is located at the following Docker repository:

https://hub.docker.com/r/wickr/bot-cloud/

The Docker container can be pulled down to the host machine using the following command:

docker pull wickr/bot-cloud:latest

The Docker container includes all the necessary software to run the Wickr IO client(s). The Wickr IO integrations can be found on the NPM registry. The installation of the integrations will be described in the configuration section of this document.

Configuration

Once the software has been installed there are several things that need to be configured, including the creation of the Wickr IO client.

Wickr IO Client Creation

Wickr IO clients belong to special “Bot” users on the platform, which need to be provisioned in the Wickr admin console. All integrations, therefore appear as these “Bot” users to other Wickr users and apps. Before you can create a Wickr IO client to run an integration, your Wickr network administrator will need to provision a “Bot” user for you using the Active Bots screen of the Wickr Admin Console, seen below:

Active Bots

When adding a ”Bot” to a network you'll input the display name (the name of the user as displayed to other Wickr users), as well as the actual user name and the password. The display name and user name fields must end with the "bot" string, which is not case sensitive. You'll need this username and password to configure the client that will be run on the Wickr IO Docker container.

Starting the Wickr IO Docker Image

There are many ways to run a docker image with many options. This document will show several options, which ones you use are dependent on what type of integration you'll be using and what type of host operating system as well.

Shared Filesystem Option

As mentioned earlier, Wickr IO clients will need to save persistent data to a location on the host machine. If you don't allow the Wickr IO software to store this information on the host machine, then the persistent information will be lost whenever the Docker container is restarted. Inside the Docker container, the Wickr IO software is storing this information in the /opt/WickrIO directory. The location on the host machine does not have to have the same path. When running the Docker container, you'll identify where this is located on the host machine, for example:

docker run -v /opt/WickrIO:/opt/WickrIO -ti wickr/bot-cloud:latest

In this example the host has a directory named /opt/WickrIO that's where the Wickr IO client(s) running in the Docker container will store persistent data. Configuration Information associated with the clients that are configured will be located in this directory as well.

It may be necessary to give the Docker container more capabilities, depending on what OS the host machine is running on. In some cases, you may need to use the --privileged=true option when running the Docker image.

Restart Docker Container Option

Normally you'll be running the Wickr IO Docker image on a Linux server and the docker image should be run so that it's always running and that it will restart if it's stopped or the server itself restarts. The following is a way to run the Docker image so that it restarts:

nohup docker run -v /opt/WickrIO:/opt/WickrIO -d --restart=always -ti wickr/bot-cloud:latest &

Running with the nohup and & will run the Docker image in the background. Output from the docker command will be placed in the nohup.out file. The -restart=always option will make sure that the image gets restarted whenever the system crashes or the docker image itself crashes.

Expose Network Ports Option

If you're using the Wickr IO web interface integration you'll have to identify a port or ports that need to be exposed to the Docker software. The following examples shows how port 4001 is exposed from the host machine to the software running on the docker image:

nohup docker run -v /opt/WickrIO:/opt/WickrIO -p 5001:4001 -d --restart=always -ti wickr/bot-cloud:latest &

In this example, the Wickr IO software running within the Docker container will be expecting network traffic on port 4001. The Host machine will be receiving the traffic on port 5001 and presenting it to the Docker container on the 4001 port.

Background and Foreground Option

Since you're running the Docker image in the background you'll need to bring it to the foreground so that you can access the Wickr IO Console. The Wickr IO Console is necessary to setup, configure and maintain the Wickr IO clients running within the Docker container. To do this you'll have to get the Docker container ID associated with the Docker instance currently running and then do a Docker attach to that container. The following is an example of this:

$ docker container ls
CONTAINER ID   IMAGE                   COMMAND       CREATED     STATUS     PORTS        NAMES
11d5626f74b9   wickr/bot-cloud:latest  "./start.sh"  2 days ago  Up 2 days               nervous_leavitt

$ docker attach 11d5626f74b9
Enter command:

From the example, you'll see the container ID 11d5626f74b9 is currently running. The docker attach to that container ID will bring that container to the foreground. When you type the enter key the “Enter command:” response will be shown.

You'll also need to know how to put the Docker container into the background. There's a simple control sequence to do that:

<Ctrl>P <Ctrl>Q

Which is basically a CONTROL-P followed by a CONTROL-Q key sequence. You'll be returned to the command line of your host operating system, and the Docker container will continue to run in the background.

Wickr IO Configuration Steps

All the configuration steps for Wickr IO are performed from the command interface that's presented when you run the Wickr IO Docker container. The previous section described several ways to start the Docker container.

When you run the Docker container for the first time there will be no clients configured, you'll see the following output:

There are no clients currently configured!
Enter command:

When you enter the Wickr IO Docker container, after having configured one or more clients, the list of currently configured clients will be displayed.

After the list of clients is displayed, you'll then be prompted to enter a command. You'll have the choice of entering the following commands:

You can type ? at almost any time to get a description of possible commands.

Adding a Wickr IO Client

To configure a new Wickr IO client run the “add” command. Initially, you'll be prompted for two fields, the Wickr username and password. The username is the bot user name you set on the Wickr Admin console, and the password is the password entered on the Wickr Admin console. The “add” command will then provision this client and create the appropriate data structures.

After the Wickr IO client is provisioned and registered with the server, there will be several options presented to you. The first is whether you want to use the autologin capability. If you don't do this, you'll have to enter the password for this client every time it's restarted. If you do use this feature, then the password will be used during the first login to generate a login key that's unique to this system. The password is never saved anywhere on disk.

Next you'll have to select a form of integration to use. The list of possible integrations will be displayed, the following is a possible list, but more may be available as they are published in the NPM registry:

The first two are example Wickr IO custom ”bot” integrations, the third is an integration for Hubot, and the web interface is an integration that supports the Wickr IO REST API.

When you select one of these integrations you'll be prompted to enter configuration information that's specific to that integration.

Starting Your Integration

At this point your new Wickr IO client will be fully configured, you can now start the client by running the “start” command. If you have more than one client configured, then you'll need to identify which one to start by entering the index number. You can get the index number from running the “list” command. The “list” command will also display the current status of each client. Wickr IO clients can be in one of three states: RUNNING, DOWN, PAUSED and NOT RUNNING.

After you run the start command for a client you may be prompted to enter the password for the client, if this is the first time starting the client or the autologin is not on for the client. After that the client will be started, running the “list” command should show the client in the RUNNING state.

Next Steps

Now you should have a running Wickr IO client and integration, you can use one of the existing integrations or you can create your own. You can modify the JavaScript associated with one of the integrations you installed as well.

Troubleshooting

Troubleshooting Wickr IO Components

This section will describe some possible issues you may run into while using the Wickr IO client and the associated services.

Wickr IO Client does not start

First you need to determine if the client is running or not. To do so you can run the ps command to see that the client process is running. The following should return an entry for each Wickr IO client that's running:

ps -aef | grep wickrio_bot

The console of the Wickr IO Docker provides commands that you can use to help diagnose the client issue.

Wickr Support is always happy to help with any issue not covered here!

Wickr Files are not received or transmitted

The system Wickr uses to transfer encrypted files needs the host date and time to be accurate. Make sure the host machine date and time is accurate, typically by installing and running an NTP service.

Log and Output Files

The Wickr IO client and the background service will generate log and output files that can be used to determine possible issues. These files should be sent to Wickr Support to allow them to diagnose any issues that can't be easily fixed. Output and log files will only be allowed to reach a certain file size. Once that size is reached a new file will be created. The maximum number of files saved to disk should only be 5.

The Wickr IO client log and output files are located in the following location, depending on how you setup the shared files:

/opt/WickrIO/clients/<client name>/logs

There are several files found in that directory. The file with the “.output” extension contains the most information and is useful in diagnosing issues with the Wickr IO client.

The background service will write log and output files to the following location:

/opt/WickrIO/logs

The name of the background service files will start with WickrIOSvr. These files will also be limited in size and number of saved files. The background service output file can be used to diagnose any possible issues with starting a Wickr IO client.

Node.js Addon API

This document will describe the Wickr IO Node.js addon and how to use it with several examples below.

The Wickr IO Node.js addon is published to the default NPM registry. The name of the published module is wickrio_addon. It supports a specific set of functions consistent with our REST API described in detail below.

API Types

Interaction with the Node.js is as follows:

  1. Initialize the Wickr IO Node.js addon interface. This is done by calling the clientInit() function, and supplying the user name of the Wickr IO client that is going to be used.
  2. Interact with the Wickr IO client by calling the appropriate API functions.
  3. When your program is complete then call the closeClient() function to gracefully stop processing.

Startup and Shutdown APIs

The Wickr IO Node.js Addon APIs need to be initialized before you can use them, and they should be gracefully shutdown when you are done using them. Initialization is necessary to setup the APIs and it will identify which Wickr IO client is to be used.

clientInit(string clientName)

Before accessing any of the Wickr IO Node.js addon APIs you will need to run the “clientInit(clientName)”. The only argument is the user name associated with the Wickr IO client.

closeClient()

This function will close the currently open client object(s). This should be called when done interacting with the client set in the “clientInit()” function.

Statistics APIs

APIs are provided to retrieve messaging statistics that are maintained by the Wickr IO client. You can get and clear the retrieved statistics.

cmdGetStatistics

{
    "statistics": {
        "message_count": 5,
        "pending_messages": 0,
        "sent": 7,
        "received": 3,
        "sent_errors": 1,
        "recv_errors": 1
    }
}

The following table has a description of each of the statistics returned by this API:

Statistics Description
message_count The number of incoming messages that are currently on the Wickr IO client.
pending_messages The number of messages that are to be sent from the specific Wickr IO client.
sent The number of messages that have been sent by the Wickr IO client.
received The number of messages that the Wickr IO client has received.
sent_errors The number of errors that have occurred while trying to send messages.
recv_errors The number of errors that occurred while receiving messages.
pending_callback_messages The number of messages on the callback message queue. These are messages received by the Wickr IO client, that are waiting to be send to a callback process.
outbox_sync The number of outbox sync messages received. These are messages that were sent by another device for this Wickr IO client.

cmdClearStatistics()

This API will clear the current statistics that are saved in the client.

Secure Room & Conversation APIs

There are several APIs that deal explicitly with the Wickr secure rooms. In cases where you are dealing with a specific secure room, you will need to have the VGroupID that is associated with that room.

cmdGetRooms()

// cmdGetRooms
{
        "rooms": [
                {
                        "description": "Room description",
                        "masters": [
                                { "name" : "username001" }
                        ],
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "title": "Room Title",
                        "ttl": "7776000",
                        "bor": "0",
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
     ]
}

This API will return a list of rooms that are known by the Wickr IO client. The Wickr IO client will respond with a JSON array of the secure rooms, so please be sure your application can handle and parse that JSON response.

cmdGetRoom(string vgroupid)

// cmdGetRoom
{
        "rooms": [
                {
                        "description": "Room description",
                        "masters": [
                                { "name" : "username001" }
                        ],
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "title": "Room Title",
                        "ttl": "-1",
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
        ]
}

This API will return details of a specific secure room conversation. The Wickr IO client will respond with a JSON structure containing information for the specified conversation.

cmdAddRoom(string members[], string moderators[], string title, string desc, string ttl, string bor)

// cmdAddRoom
{
        "vgroupid": "S0b503ae14cc896aad758ce48f63ac5fae0adccd78ef18cde82563c63b2c7761"
}

This API creates a new room. The arguments of this request will contain the information associated with the room. The members and moderators arguments are arrays of strings that Identify the members and moderators of the room. The ttl and bor values are optional, but if the bor value is included then the ttl value must also be included.

The response will either be an error with a description of that error or a successful response with the vGroupId of the newly created room.

cmdModifyRoom(string vgroupid, string members[], string moderators[], string title, string description, string ttl, string bor)

This API is used to modify some of the settings associated with a room. The following room attributes can be modified using this API:

cmdLeaveRoom(string vgroupid)

In order to leave a secure room, you will need to have the vGroupID associated with that room. You can use the get rooms API to get the list of rooms known by the Wickr IO client, then determine which room to leave. Also, saving the vGroupID returned from the create room API can be used as well.

The user associated with the Wickr IO client will leave the room associated with the specified vGroupID.

cmdDeleteRoom(string vgroupid)

In order to delete a secure room, you will need to have the vGroupID associated with that room. You can use the get rooms API to get the list of rooms known by the Wickr IO client, then determine which room to delete. Also, saving the vGroupID returned from the create room API can be used as well.

Group Conversation APIs

This section describes the APIs associated with group conversations. Using these APIs, you can create, get or delete group conversations that the client is a part of.

cmdAddGroupConvo(string members[], string ttl, string bor)

// cmdAddGroupConvo
{
        "vgroupid": "S0b503ae14cc896aad758ce48f63ac5fae0adccd78ef18cde82563c63b2c7761"
}

This API will create a new group conversation.  The members argument is required, and the ttl and bor values are optional. The response will either be an error with a description of that error or a successful response with the vGroupID of the newly created group conversation.

cmdGetGroupConvos()

// cmdGetGroupConvos
{
        "groupconvos": [
                {
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "ttl": "7776000",
                        "bor": "0",
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
        ]
}

This API will return a list of group conversations that are known by the Wickr IO client. The Wickr IO client will respond with a JSON array of the group conversations.

cmdGetGroupConvo(string vgroupid)

// cmdGetGroupConvo
{
        "rooms”: [
                {
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
        ]
}

This API will return details of a specific group conversation. The Wickr IO will respond with a JSON structure containing information for the specified conversation.

cmdDeleteGroupConvo(string vgroupid)

In order to delete a group conversation, you will need to have the vGroupID associated with that conversation. You can use the get group conversations API to get the list of conversations known by the Wickr IO client, then determine which conversation to delete. Also, saving the vGroupID returned from the create group conversation API can be used as well. The group conversation with the same vGroupID will be deleted.

Messaging APIs

These are APIs that get and send messages, plain and simple. There are several ways to retrieve messages:

The Wickr IO APIs will only support one method at a time.

Received Message Format

// One-to-one message
{
        "id":"3960e020ca4211e799802f2894564caa",
        "message":"This is a typical 1:1 message",
        "msg_ts":"1510777143.738976",
        "msgtype":1000,
        "receiver":"user001",
        "sender":"user003",
        "time":"11/15/17 3:19 PM",
        "vgroupid":"fb6e21630c05fde50ae39113c3626018712cf2c374b4a80eba4d28ced9419c07"
}
// Room and Group Conversation messages
{
        "id":"76775de0ca4211e7bddcafd7007db1d1",
        "message": "Typical message in a secure room",
        "msg_ts":"1510777246.227505",
        "msgtype":1000,
        "sender":"user003",
        "time":"11/15/17 3:20 PM",
        "vgroupid":"S3042f1bd04491c6f3732a871e27ab516a8d1534cc1e2d25c4e4869ce72e8541"
}
// File Transfer Messages
{
        "file": {
                "filename": "picture.jpeg",
                "guid": "AD20D048-9B60-4F32-A691-2D4BE4152E58",
                "localfilename": "/opt/WickrIO/clients/compliancebot01/attachments/attachment_20171116111610865_picture.jpeg"
        },
        "id": "91a189c0cae911e79ec4eb19a763225b",
        "msg_ts": "1510849017.756174",
        "msgtype": 6000,
        "sender": "user003",
        "time": "11/16/17 11:16 AM",
        "vgroupid": "S3042f1bd04491c6f3732a871e27ab516a8d1534cc1e2d25c4e4869ce72e8541"
}

There are different types of messages that will be delivered to the configured message destination, URL or email callbacks. This section will describe each of these. All formats use JSON.

One-to-one messages

The following shows a normal one-to-one message format. All text-based messages will have the msgtype of 1000.

Room and Group Conversation messages

This shows a normal group and room conversation message format. The Wickr IO client does not currently track the list of clients associated with group conversations, so the list of destination clients will not be included.

File Transfer Messages

The following shows the format of a file transfer message. The msgtype for files is 6000.

As of version 4.35, files sent for screen shots will be identified by a “isscreenshot” key value pair, in the “file” object. This is a Boolean value, where true identifies the file as a screenshot. If the “isscreenshot” key is not found, then the file is not a screen shot.

Wickr Control Messages

Wickr control messages used to setup and configure the conversations will also be sent to the callback destination. These messages are useful to reproduce the conversations, specifically which clients are associated with the specific conversation. Details of these message types will be included later.

cmdGetReceivedMessage()

This API will retrieve the next message waiting to be read. Each call to this API will return just one message if any are waiting to be read. After the message is retrieved it will be removed from the Wickr IO bot client database.

cmdStartAsyncRecvMessages(function callback(string))

This API will initiate the asynchronous reception of received messages. The input callback argument will be called when a message is received by the associated client.

Any implementation that uses this API must make sure events can be handled so that the callback may be called.

cmdStopAsyncRecvMessages()

This API will stop the asynchronous reception of received messages.

cmdSetMsgCallback(string url)

Use this API to set a URL that will be used by the client to send received messages to. Any messages received after this API is performed will be sent to the defined URL.

cmdGetMsgCallback()

// cmdGetMsgCallback
{
        "callback": "https://localhost:4008"
}

Use this API to get the currently set message callback URL. If there is a URL callback defined the following is the format of the body.

cmdDeleteMsgCallback()

If the URL callback is no longer needed or you need to switch to receive messages asynchronously then delete the existing message URL callback. This API will delete the current message callback.

cmdSend1to1Message(string users[], string message, string ttl, string bor)

This API is used to send a message to one or more Wickr clients. The "users" field may contain an array of 1 or more users to send the message to.  The message will be sent to each user on a separate 1-to-1 conversation. So, if the POST message contains 5 users then 5 messages will be sent, using the text from the "message" field. When sending a message, you can also set the specific TTL or BOR value for the message.

cmdSendRoomMessage(string vgroupid, string message, string ttl, string bor)

This API is used to send a message to a secure room or group conversation. If you want to send a message to a secure room or a group conversation you will need to get the vGroupID associated with that conversation. To do that the vGroupID will be returned when you create the room/conversation using the appropriate API. Also, the get rooms API will return a list of known rooms that you can send to, the vGroupID is contained in the response.

cmdSend1to1Attachment(string users[], string filename, string displayname, string ttl, string bor)

This API is used to send a file to one or more users. The file will be sent to each of the users in the input users list, via individual 1-to-1 conversations. The filename identifies a file that is located on the client system, this file must be located in a location on the client that is accessible by the client software. The displayname field will be sent in the file transfer message. The TTL and BOR values are optional.

cmdSendRoomAttachment(string vgroupid, string filename, string displayname, string ttl, string bor)

This API is used to send a file to a secure room or group conversation. The file will be sent to conversation associated with the input vgroupid. The filename identifies a file that is located on the client system, this file must be located in a location on the client that is accessible by the client software. The displayname field will be sent in the file transfer message. The TTL and BOR values are optional.

Key-Value APIs

These APIs provide the ability to save and retrieve values to/from a persistent storage location. The values will be stored in an encrypted database, that is associated with the Wickr IO client. Currently, only string values can be saved using these APIs.

cmdAddKeyValue(string key, string value)

This API is used to save, or update the value associated with the input key.

cmdGetKeyValue(string key)

This API will return the string value associated with the input key.

cmdDeleteKeyValue(string key)

This API will delete the key-value information associated with the input key.

cmdClearAllKeyValues()

This API will clear (delete) all key-value pairs from the persistent storage.

Web Interface REST API

REST API Overview

This describes the REST APIs that are supported by the 2.x version of the WickrIO Web_Interface integration. The following table identifies each of the actions the API supports, the type of HTTP request and the URL used.

API HTTP URL
Send Message POST https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Messages
Set Message URL Callback POST https://<host>:<port>/WickrIO/V1/Apps/<API Key>/MsgRecvCallback?callbackurl=<url>
Get Message URL Callback GET https://<host>:<port>/WickrIO/V1/Apps/<API Key>/MsgRecvCallback
Delete Message URL Callback DELETE https://<host>:<port>/WickrIO/V1/Apps/<API Key>/MsgRecvCallback
Get Received Messages GET https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Messages?start=<index>&count=<number>
Get Statistics GET https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Statistics
Clear Statistics DELETE https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Statistics
Create Secure Room POST https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms
Get Room GET https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms/<vGroupID>
Get Rooms GET https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms
Delete Room DELETE https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms/<vGroupID>
Leave Room DELETE https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms/<vGroupID>&reason=leave
Modify Room POST https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms/<vGroupID>
Create Group Conversation POST https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo
Get Group Conversations GET https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo
Get Group Conversation GET https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo /<vGroupID>
Delete Group Conversation DELETE https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo/<vGroupID>

REST API Configuration

After installing the Web API Interface software module, you will need to configure several properties that are needed to access the URL endpoints. The WickrIO console will walk you through entering the following values:

openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout my.key -out my.cert

For HTTPS and SSL support, you need an OpenSSL certificate file and a key file. Both can be created with the following command:

Authentication

This version of the Web_Interface supports basic authentication. The authentication will use the "Authorization" HTTP header to send the necessary authentication information to the WickrIO server. If the proper authentication information is not presented to the WickrIO server then an HTTP 401 response will be sent.

When using basic authentication, a base64 encoded string will be sent to the WickrIO server.  The following steps should be performed for basic authentication:

  1. When the associated WickrIO bot client is configured and associated with the Web_Interface integration, the associated authentication string will be setup. This string is used to generate the base64 encoded string.
  2. Base64 encode the string mentioned above.
  3. Supply an "Authorization" header with content "Basic " followed by the encoded string.  For example, the string "The big red fox" encodes to "VGhlIGJpZyByZWQgZm94" in base 64, so you would send the string "Basic VGhlIGJpZyByZWQgZm94" in the "Authorization" HTTP header.

Send Message API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Messages

This API is used to send a message to one or more Wickr clients. To have a specific WickrIO client send a message, send an HTTP POST message to the following URI:

The body of the POST request is JSON and the contents of that JSON will determine the type of Wickr message and the destination(s) of the message. You can send a message to one or more 1-to-1 recipients, a secure room or a group conversation. To send to a secure room or a group conversation, the room will have to been created before sending any messages.  You will also need the vGroupID associated with the secure room or group conversation.

The send message API also supports sending files.

There are several JSON fields used by this API, and depending on the type of message or file being sent. The following table lists all of the JSON fields that are supported by the Send Message API.

KEY Description
message String value that is the message to be sent, when sending a Wickr message. Not used when sending a file.
users This is an array of users. These are the users to be sent to. Not used when sending to a secure room or group conversation. These are the wickr ID values associated with the user to send to.
bor The burn-on-read value to use when sending the message
ttl The time-to-live value to use when sending the message (referred to as Expiration Time in clients)
vgroupid The vgroupid to use when sending to a secure room or group conversation.
runtime Used to specify when the message(s) are to be sent. The format of this value is ISO 8601 extended format: either yyyy-MM-dd for dates or yyyy-MM-ddTHH:mm:ss (e.g. 2017-07-24T15:46:29), or with a time-zone suffix (Z for UTC otherwise an offset as [+
attachment This is a JSON object that identifies a file to be sent. The message value will be disregarded if the attachment field is used.
attachments Identifies files to be sent. Currently only supports one file. Future implementation will support sending multiple files.

When sending files, the location of the files either needs to be located on the WickrIO system or addressable and downloadable using a specific URL.

Sending a single message to multiple recipients

{
        "message": "Welcome to Wickr! This message will self-destruct in 5 seconds.",
        "users" [
                { "name" : "username001" },
                { "name" : "username002" }
        ]
}

To send a message to one or more recipients, the HTTP POST message should contain a JSON body with the following format:

The "users" field may contain an array of 1 or more users to send the message to.  The message will be sent to each user on a separate 1-to-1 conversation. So, if the POST message contains 5 users then 5 messages will be sent, using the text from the "message" field.

Sending a message with Burn-on-Read

{
        "message": "Welcome to Wickr! This message will self-destruct in 5 seconds.",
        "users" [ { "name": "username002" } ],
        "bor": 10
}

When sending a message, you can also set the specific burn on read (BOR) value for the message.  The following format shows how to set the BOR value to 10 seconds:

Sending a message to a Secure Room

{
        "message": "Welcome to Wickr! This message will self-destruct in 5 seconds.",
        "vgroupid": "S8a97892379289bca979293709822718928392837492837492834"
}

If you want to send a message to a secure room or a group conversation you will need to get the vGroupID associated with the room. The vGroupID will be returned when you create the room/conversation using the appropriate API. Also, the get rooms API will return a list of known rooms that you can send to, the vGroupID is contained in the response. To send to a secure room or group ID the following is an example:

Sending a File

{
        "users" [ { "name" : "username001" } ],
        "attachment": {
                "filename" : "/home/ubuntu/pictures/picturesent.jpg"
                "displayname" : "PictureSent.jpg"
        }
}

The client also supports the ability to send files. Files must be located at a URL that can be downloaded by the client or on the actual WickrIO system where the WickrIO client can access the file. The following is an example of sending a file to a single user, where the file is located on the WickrIO system:

In this example, the file to be sent is already on the WickrIO client. The filename identifies the full path to the file. The Send Message API will respond with a 202 (Accepted) response, unless there is an error.

{
        "users" [ { "name" : "username001" } ],
        "attachment": {
                "url" : "https://example.com/pictures/picturesent.jpg"
                "displayname" : "PictureSent.jpg"
        }
}

Files can also be sent from the WickrIO client using a URL reference to the file. The WickrIO client will download the file first and then send the message. The following is an example of sending a file to a single user, where the file is located at an external URL example.com.

You can also send files to secure rooms and group conversations using the vgroupid instead of listing the users to send to.

Received Message

The WickrIO client has the capability to receive messages and then forward these messages to a third-party application or to a specific email.

Message callbacks are used to identify where the WickrIO client should send incoming Wickr messages. Currently there are two types of message callbacks supported, URL and Email. Only one can be setup at a time. If you want to change to a different type of callback then you will need to delete the current callback setup, and then create the new one. To change the settings of the same type you can just send a POST command for the associated type. Messages received by the WIckrIO client will be sent to the configured URL or Email callback in a JSON format. The format of the received messages and meta data will be described later.

URL Callbacks

http://localhost:4100

This type of callback will define a URL that the client will connect to when a message is received, the received message will be sent to the URL. It is assumed that there is an application consuming messages that are pushed to this URL. For example, if you run a process on the same machine as the WickrIO client you can use a URL like the following:

Wickr can supply a sample program that accepts messages on a specific port and posts to syslog.

Set URL Callback API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/MsgRecvCallback?callbackurl=<url>

You will need to configure the specific URL that the WickrIO client will send incoming messages to. To set the URL callback value, send an HTTP POST request using the following URI:

The client will respond back with a success or failure response.  Any messages received after this call is performed will be sent to the defined URL.

Get URL Callback API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/MsgRecvCallback

To get the currently set URL callback send an HTTP GET request using the following URI:

{
    "callbackurl": "https://localhost:4008"
}

The client will respond with either a success (200) or failure response. If there is a URL callback defined the following is the format of the body:

Delete URL Callback

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/MsgRecvCallback

If a URL callback is no longer needed or you need to switch to an email callback then the delete URL callback API should be used. To delete a URL callback, send an HTTP DELETE request using the following URI:

The client will respond with a success or failure response.

Callback Message Format

There are different types of messages that will be delivered to the configured message destination, URL or email callbacks. This section will describe each of these formats. All of the formats use JSON.

One-to-one messages

{
        "id":"3960e020ca4211e799802f2894564caa",
        "message":"This is a typical 1:1 message",
        "msg_ts":"1510777143.738976",
        "msgtype":1000,
        "receiver":"user001",
        "sender":"user003",
        "time":"11/15/17 3:19 PM",
        "vgroupid":"fb6e21630c05fde50ae39113c3626018712cf2c374b4a80eba4d28ced9419c07"
}

The following shows a normal one-to-one message format. All text-based messages will have the msgtype of 1000.

Group and Room Conversation messages

{
        "id":"76775de0ca4211e7bddcafd7007db1d1",
        "message": "Typical message in a secure room",
        "msg_ts":"1510777246.227505",
        "msgtype":1000,
        "sender":"user003",
        "time":"11/15/17 3:20 PM",
        "vgroupid":"S3042f1bd04491c6f3732a871e27ab516a8d1534cc1e2d25c4e4869ce72e8541"
}

The following shows a normal group and secure room conversation message format. The WickrIO client does not currently track the list of clients associated with group conversations, so the list of destination clients will not be included.

File Transfer messages

{
        "file": {
                "filename": "picture.jpeg",
                "guid": "AD20D048-9B60-4F32-A691-2D4BE4152E58",
                "localfilename": "/opt/WickrIO/clients/compliancebot01/attachments/attachment_20171116111610865_picture.jpeg"
        },
        "id": "91a189c0cae911e79ec4eb19a763225b",
        "msg_ts": "1510849017.756174",
        "msgtype": 6000,
        "sender": "user003",
        "time": "11/16/17 11:16 AM",
        "vgroupid": "S3042f1bd04491c6f3732a871e27ab516a8d1534cc1e2d25c4e4869ce72e8541"
}

The following shows the format of a file transfer message. The msgtype for files is 6000. Files received by the WickrIO client will be decrypted and remain on the WickrIO client until removed by your software.

As of version 4.35, files sent for screen shots will be identified by a “isscreenshot” key value pair, in the “file” object. This is a Boolean value, where true identifies the file as a screenshot. If the “isscreenshot” key is not found then the file is not a screen shot.

Wickr Control messages

Wickr control messages used to setup and configure the conversations will also be sent to the callback destination. These messages are useful to reproduce the conversations, specifically which clients are associated with the specific conversation. Details of these message types will be included later.

Statistics API

Each WickrIO client maintains statistics associated with the number of messages sent and received. The statistics will also include information about send and receive errors as well as the number of pending messages. This section describes the APIs associated with statistics.

Get Statistics API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Statistics

This API will retrieve statistics that are saved on the client.  These are a little different than the statistics that can be retrieved via the main console interface. Here is the HTTP GET used to get client statistics:

{
        "statistics": {
                "message_count": 5,
                "pending_messages": 0,
                "sent": 7,
                "received": 3,
                "sent_errors": 1,
                "recv_errors": 1
        }
}

The following is the type of output received in the response. Some of these statistics may be missing if they have not been changed.

The following table has a description of each of the statistics returned by this API:

Statistics Description
message_count The number of incoming messages that are currently on the WickrIO client.
pending_messages The number of messages that are to be sent from the specific WickrIO client.
sent The number of messages that have been sent by the WickrIO client.
received The number of messages that the WickrIO client has received.
sent_errors The number of errors that have occurred while trying to send messages.
recv_errors The number of errors that occurred while receiving messages.
pending_callback_messages The number of messages on the callback message queue. These are messages received by the WickrIO client, that are waiting to be send to a callback process.
outbox_sync The number of outbox sync messages received. These are messages that were sent by another device for this WickrIO client.

Clear Statistics API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Statistics

This API will clear the current statistics that are saved on the client.  Use HTTP DELETE with the following URI to clear the statistics on the specific WickrIO client:

Secure Room APIs

This section describes the APIs associated with secure rooms. Using these APIs you can create, modify, get, delete and leave secure rooms that the client is a part of.

Create Secure Room API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms

This API will create a new secure room.  To create a secure room, send an HTTP POST command using the following URI:

{
        "room": {
                "title" : "Room Title",
                "description" : "Description of the room",
                "ttl" : 3600,
                "bor" : 60,
                "members" : [
                        { "name" : "username001@wickr.com" },
                        { "name" : "username002@wickr.com" }
                ],
                "masters" : [
                        { "name" : "username001@wickr.com" },
                ]
        }
}

The body of this request will contain the information associated with the room. The following is the format of the JSON data for the body of the request:

{
        "vgroupid": "S0b503ae14cc896aad758ce48f63ac5fae0adccd78ef18cde82563c63b2c7761"
}

The response will either be an error with a description of that error or a successful response with the vGroupId of the newly created secure room. The following is an example of a successful response:

Get Rooms API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms

This API will return a list of rooms that are known by the WickrIO client. To get a list of rooms send an HTTP GET to the following URI:

{
        "rooms": [
                {
                        "description": "Room description",
                        "masters": [
                                { "name" : "username001" }
                        ],
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "title": "Room Title",
                        "ttl": "7776000",
                        "bor": "0",
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
        ]
}

The WickrIO client will respond with a JSON array of secure rooms. The format of the response will look like the following:

Get Secure Room API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms/<vGroupID>

This API will return details of a specific secure room or group conversation. Send an HTTP GET using the following URI:

{
        "rooms": [
                {
                        "description": "Room description",
                        "masters": [
                                { "name" : "username001" }
                        ],
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "title": "Room Title",
                        "ttl": "-1",
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
        ]
}

The WickrIO will respond with a JSON structure containing information for the specified conversation. The format of the response will look like the following:

Delete Room API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/Rooms/<vGroupID>?reason=delete

In order to delete a secure room, you will need to have the vGroupID associated with that room. You can use the get rooms API to get the list of rooms known by the WickrIO client, then determine which room to delete. Also, saving the vGroupID returned from the create room API can be used as well.

To delete a secure room, send an HTTP DELETE command using the following URI:

The secure room with the same vGroupID will be deleted. The reason argument does not need to be present, since the delete action is the default action, or if can specify the delete action.

Leave Room API

In order to leave a secure room, you will need to have the vGroupID associated with that room. You can use the get rooms API to get the list of rooms known by the WickrIO client, then determine which room to leave. Also, saving the vGroupID returned from the create room API can be used as well.

https://<host>:<port>/WickrIO/V1/Apps/<App ID>/Rooms/<vGroupID>?reason=leave

Modify Room API

This API is used to modify some of the settings associated with a secure room. The following secure room attributes can be modified using this API:

https://<host>:<port>/WickrIO/V1/Apps/<App ID>/Rooms/<vGroupID>

To modify any of these values for a secure room send an HTTP POST command using the following URI:

{
        "ttl": 66000,
        "bor": 300
}

The body of the request will identify the values to change and the new values to assign. The following JSON is an example of a body for the modify room API which will set the BOR and TTL values:

Group Conversation API

This section describes the APIs associated with group conversations. Using these APIs you can create, get or delete group conversations that the client is a part of.

Create Group Conversation API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo

This API will create a new group conversation.  To create a group conversation, send an HTTP POST command using the following URI:

{
        "groupconvo": {
                "members" : [
                        { "name" : "username001@wickr.com" },
                        { "name" : "username002@wickr.com" }
                ]
        }
}

The body of this request will contain the information associated with the group conversation. The following is the format of the JSON data for the body of the request.

{
        "vgroupid": "S0b503ae14cc896aad758ce48f63ac5fae0adccd78ef18cde82563c63b2c7761"
}

The response will either be an error with a description of that error or a successful response with the vGroupID of the newly created group conversation. The following is an example of a successful response:

Get Group Conversations API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo

This API will return a list of group conversations that are known by the WickrIO client. To get a list of group conversations send an HTTP GET to the following URI:

{
        "groupconvos": [
                {
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "ttl": "7776000",
                        "bor": "0",
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
        ]
}

The WickrIO client will respond with a JSON array of the group conversations. The format of the response will look like the following:

Get Group Conversation API

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo /<vGroupID>

{
        "rooms": [
                {
                        "members": [
                                { "name" : "username001" },
                                { "name" : "username002" }
                        ],
                        "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
                }
        ]
}

The WickrIO will respond with a JSON structure containing information for the specified conversation. The format of the response will look like the following:

Delete Group Conversation API

In order to delete a group conversation, you will need to have the vGroupID associated with that conversation. You can use the get group conversations API to get the list of conversations known by the WickrIO client, then determine which conversation to delete. Also, saving the vGroupID returned from the create group conversation API can be used as well.

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/GroupConvo/<vGroupID>

To delete a group conversation, send an HTTP DELETE command using the following URI:

The group conversation with the same vGroupID will be deleted.

Writing Integrations

This section describes how you can create your own Node.js integration and install it on a running Wickr IO Integration Gateway. An optional REST API is provided to support non-Node.js integrations as well as integrations with remote systems.

Integration software will interact with the Wickr IO client in several ways. The main interaction is the runtime interaction where the integration communicates with a client through the Node.js addon API. This is the basic run time interaction, and this is where we will start to describe the basic implementation of an integration. Later in this document we will define the other requirements that an integration must support in order for it to operate successfully on the Wickr IO Integration Gateway.

Integration Runtime

{
  "name": "my-wickrio-integration",
  "version": "1.0.0",
  "description": "Sample Wickr IO integration",
  "main": "my_wickrio_integration.js",
  "private": true,
  "dependencies": {
    "pm2": "^3.2.2",
    "prompt": "^1.0.0",
    "wickrio_addon": "^4.64.2"
  },
  "scripts": {
    "start": "pm2 start my_wickrio_integration.js",
    "stop": "pm2 delete my_wickrio_integration.js"
  }
}

Currently, all integrations are based on using the Wickr IO Node.js addon API and will have to include the addon as a dependency in their “package.json” file. For example, the following “package.json” file for the “my-wickrio-integration” package contains the appropriate entry in the “dependencies” list:

With this statement you will now have access to the Wickr IO Node.js addon API, which is fully documented here.

Your JavaScript must contain a require() statement that references the "wickrio_addon". The following is what you should add at the beginning of your JavaScript file:

var addon = require('wickrio_addon');

API Initialization

var client = fs.readFileSync(client_bot_username.txt, utf-8);
client = client.trim();
try{
var response = await addon.clientInit(client);
} catch(err){
//Handle error here
console.log(err);
}

Before the Wickr IO Node.js Addon API can be used you will need to initialize it in your JavaScript code. This initialization is done by calling the calling the “clientInit()” API function and passing the client name associated with the Wickr IO client. For example:

After the call to the “clientInit()” function the API will be fully initialized. At this point you can start using the API to communicate with the Wickr IO client.

API Usage

// Sending message to a room

var msg = "Sorry, I'm not allowed to delete all the files in the directory.";
try{
var sMessage = await addon.cmdSendRoomMessage(vGroupID, msg);
console.log(sMessage); //if successful should print "Sending message"
} catch(err){
//Handle error here
console.log(err);
}
// Creating a room and sending an attachment

var members = [{ "name" : "username001" }, { "name" : "username002" }];
var moderators = [{ "name" : "username001" }, { "name" : "username002" }];
var bor = "600";  //OPTIONAL
var ttl = "1000"; //OPTIONAL
var title = "Example Room";
var description = "The Good Room";
var message = "Testing time!"
var attachmentURL = "https://www.alsop-louie.com/wp-content/uploads/2017/03/wickr-logo-2-crop.png"
var displayname = "Logo.png";
try {
var vGroupID = addon.cmdAddRoom(members, moderators, title, description, ttl, bor);
//if successful should print a json with vgroupid of the newly created room
console.log(vGroupID);
//Notice: in this example the ttl and bor arguments are omitted and command will still work
var cmd = addon.cmdSendRoomAttachment(vGroupID, attachmentURL, displayname);
//if successful should print "Sending message"
console.log(cmd);
console.log(addon.closeClient());
} catch(err){
//Handle errors here
console.log(err);
}
// Receive Asynchronous Messages

addon.cmdStartAsyncRecvMessages(listen);

async function listen(rMessage) {
    console.log(rMessage)
    rMessage = JSON.parse(rMessage);
    var sender = rMessage.sender;
    var vGroupID = rMessage.vgroupid;
    var userArr = [];
    userArr.push(sender);
    if (rMessage.message) {
      var request = rMessage.message;
      var command = '',
        argument = '';
      var parsedData = request.match(/(\/[a-zA-Z]+)(@[a-zA-Z0-9_-]+)?(\s+)?(.*)$/);
      if (parsedData !== null) {
        command = parsedData[1];
        if (parsedData[4] !== '') {
          argument = parsedData[4];
        }
      }
      if (command === '/help') {
        var help = "/help - List all available commands\n" +
          "/list - Lists all available files\n" +
          "/get FILE_NAME - Retrieve the specified file\n" +
          "/delete FILE_NAME - Deletes the specified file\n";
    try{
        var sMessage = addon.cmdSendRoomMessage(vGroupID, help);
    } catch(err){
    //Handle error here
    console.log(err);
    }
      }
}

There are two types of APIs supported by the Wickr IO Node.js addon: synchronous API calls, where a request is made to the Wickr IO client and a response is received, and the asynchronous messaging API. Here are sample synchronous API calls:

All synchronous APIs will wait for the response to return before proceeding.

The asynchronous messaging APIs will turn on or off the asynchronous reception of messages received by the Wickr IO client. After calling the “cmdStartAsyncRecvMessages(callback)” API, messages received will be sent to the callback function identified in that API. To turn off the asynchronous reception of messages use the “cmdStopAsyncRecvMessages()” API. The following is sample JavaScript code associated with the reception of asynchronous messages:

Using the asynchronous messaging does require your program handles the background events associated with the reception of these messages. This can be tricky based on the single threaded nature of JavaScript.

API Shutdown

When you are done using the API you will need to shut it down. This is done by calling the “closeClient()” API. Before calling this function, you should make sure that the asynchronous message has been stopped first.

Integration Setup and Configuration

Before you can get to the run time operation of a Wickr IO integration the integration will need to be installed and configured. Unless you want to manually setup and configure an integration you will need to make sure it adheres to the integration specifications described herein. All of the integrations supplied by Wickr will adhere to these specifications.

But of course, the goal is to empower you to create your own integrations, specific to how you want to interact with the Wickr clients and system. We encourage you to share your integrations with others, and this very simply done by making it public on the NPM registry.

Integration Interactions

Aside from the interaction with the Wickr IO Node.js addon, the integration software will have to support the following interactions with the Wickr IO control software:

Each of these interactions will require the integration module to contain specific scripts or other capabilities. The following sections will describe each one of these.

Integration Software Download

npm install my-wickrio-integration

{
  "name": "my-wickrio-integration",
  "version": "1.0.0",
  "description": "Sample Wickr IO integration",
  "main": "my_wickrio_integration.js",
  "private": true,
  "dependencies": {
    "nodemon": "^1.18.4",
    "prompt": "^1.0.0",
    "wickrio_addon": "^4.54.23"
  },
  "scripts": {
    "start": "node my_wickrio_integration.js",
    "stop": "pkill --signal SIGINT fileBot"
  }
}

Aside from Wickr supplied integrations (which are part of the Wickr IO installation), other Wickr IO integration software will be published to the NPM registry. During the installation of a Wickr IO client you will be given a choice of what integrations to install, as well as the choice to search for possible integrations on the NPM registry. When an integration is selected from the NPM registry, the associated integration software will be installed using the npm install command. For example, a module with the name “my-wickrio-integration” would be installed with the following command:

This will download and install all of the required dependencies into the system. Files specific to the “my-wickrio-integration” will be moved to the root of that installation.

Like any node.js module, your integration must include a “package.json” file. This file will contain the items which are required for the integration to operate. Here is a sample “package.json” file:

For the software download requirement, the “wickrio_addon” must be in the “dependencies” list.

Integration Installation

After a Wickr IO integration has been downloaded there may be some other installation steps necessary. If so, the integration should contain an “install.sh” executable script. The system will run this script if it exists.

Integration Configuration

After the “install.sh” script is run the configuration process will begin. Configuration is the process of getting any specific values from the user that are required to run the integration. If you need configure any values that are needed by your integration, before starting the integration software, you will need to create a configure.sh file that will be used to prompt for these values. The Wickr IO Integration console will run the configure.sh during the configuration phase of installing a client. Any output from the configure.sh file will be shown to the user. Any output that starts with the “prompt:” string will be echoed to the user as a input prompt. Anything the user types, followed by the enter key, will be returned to the configure.sh script. It is up to the configure.sh script to save these values somewhere that can be used by the integration software when it is started. Here is an example of a configure.sh script that is prompting for a username value:

if [ -z "$CLIENT_NAME" ]; then
  echo "prompt: Please enter your client username:"
  while [ -z "$input" ]
  do
    read  input
    if [ ! -z "$input" ]
    then
      echo ${input} >client_bot_username.txt
    else
      echo "Cannot leave client username empty! Please enter a value:"
    fi
  done
  else
    echo $CLIENT_NAME >client_ username.txt
fi

The Wickr IO Node.js addon has APIs to save and retrieve type value pairs, but this API is only available when the client is running. The configure.sh script will not be able to access the APIs, so these values need to be stored locally until the client is running, if you want to make use of those APIs.

Integration Start

When starting a Wickr IO client, the system needs to be able to start the associated integration software. The typical way to do this is to run the “npm start” script. This is the default way to start an integration. Your “package.json” file must include the “start” entry in the “scripts” section. If you need to start your integration differently then include an executable “start.sh” script file. If that file exists, the system will execute it to start the integration, otherwise the “npm start” script will be run.

Integration Stop

When stopping a Wickr IO client, the system needs to be able to stop the associated integration software. The typical way to do this is to run the “npm stop” script. This is the default way to stop an integration. Your “package.json” file must include the “stop” entry in the “scripts” section. If you need to stop your integration differently then include an executable “stop.sh” script file. If that file exists, the system will execute it to start the integration, otherwise the “npm stop” script will be run.

Integration Upgrade

This script is used to upgrade the custom integration software. The goal of this script is to perform any operations that need to be done when upgrading the custom integration software, such as saving any configuration information from the current installation. The script is passed two arguments: the first is the directory location of the existing installation, the second is the directory of the new software installation. If there is an upgrade.sh script supplied, it is up to the script to make the appropriate changes, with the result being that the existing installation directory will have been updated and ready to move on to the next step.

NOTE: when upgrading custom integration software from a exported bundle, the upgrade.sh script in the NEW software.tar.gz will be run, not the upgrade.sh from the previous version.

This is an optional script. If the upgrade.sh is NOT part of the imported software.tar.gz then the default operation will be to remove the old software installation associated with a particular Wickr IO client and replace it with the new version of the software.

After the upgrade.sh script has run or the default operation of replacing the software has completed, then the install.sh and then the configure.sh scripts will be called.

Console Integration Commands

The Wickr IO Integration Gateway console has several commands which are useful when creating your own integrations. These are:

Creating an Integration

This section will describe the steps you can take to create your own Wickr IO integration. You can use a current Wickr IO integration as the basis for creating your integration. The console commands described in the previous section will be used to create the custom integration.

When you are adding a new Wickr IO client to the Wickr IO Integration Gateway you will have to associate integration software with that client. The wickrio-hello-world-bot is a good example of an integration and should be easy to modify to create your own integration. When you modify the integration code associated with a client, that code will only be associated with that client. If you want to use that code on another gateway or another client running on the same gateway you will need to export the integration software and files. Once exported you can copy it to another gateway machine, where you can import it and then use it with as many clients as you need. You can also rename the integration to have a name that is more meaningful for your integration.

Assuming this, the following steps can be performed to create your own integration:

  1. Using the Wickr admin console create a Wickr bot account
  2. On the Wickr IO Integration Gateway use the “add” command to add the client created in step 1. When prompted for the integration to use, select the “wickrio-hello-world-bot”. Make note of the location of the integration so that you can modify the appropriate code.
  3. You should start the bot to make sure the integration works. Basically, the hello world integration will receive a message from a Wickr user and response with a canned response. Once you verify that you should pause that client.
  4. Modify the code in the integration directory, which you saved in step 2. You can start and pause the client to verify things are working.
  5. Once you are happy with your integration software you should export it. The export command will walk you through the process of creating a set of files that can be used with other Wickr IO clients. You will be prompted to select which files and directories to include in the exported integration.

Since you will be exporting from an operating integration there are files that are generated during the install and operation of the integration that should not be included in an export.

After the integration is exported the location of the 'tar.gz' file will be displayed. You can copy that file to another gateway or use it on the local gateway.

Here is some sample output of the exporting of the integration software associated with a Wickr IO client:

Enter command:rename 1
Enter the new name:my-hello-world-bot
Confirm that you want to change the integration name
From wickrio-hello-world-bot to my-hello-world-bot
Do you want change the integration name? (default: yes):yes
Enter command:
Enter command:list
Current list of clients:
 client[0] desktop_bot, State=Paused, Integration=new_welcome_bot
 client[1] npm_test_bot, State=Paused, Integration=my-hello-world-bot
Enter command:
Enter command:export 1
Are you sure you want to export this integration? (default: yes):yes
Export integration files from WickrIO client npm_test_bot
You will be prompted for each file and directory to verify it is to be export.
PLEASE be careful to only select the files and directories needed.
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/client_bot_username.txt? (default: yes):no
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/configure.sh? (default: yes):
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/hello_world_bot.js? (default: yes):
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/install.sh? (default: yes):
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/package-lock.json? (default: yes):no
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/package.json? (default: yes):
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/README.md? (default: yes):
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/start.sh? (default: yes):
Include file /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/stop.sh? (default: yes):
Include directory /opt/WickrIODebug/clients/npm_test_bot/integration/my-hello-world-bot/node_modules? (default: yes):no
./
./configure.sh
./hello_world_bot.js
./install.sh
./package.json
./README.md
./start.sh
./stop.sh

**************************************************
Your integration software has been exported to:
/opt/WickrIODebug/integrations/export/my-hello-world-bot
**************************************************

If you want to use this integration with other clients on this system
you will have to import it.
Would you like to import this integration now? (default: yes):no

Wickr IO Hubot Integration

The Wickr IO Integration Gateway includes built-in support for Github's Hubot. If you are more comfortable creating integrations in that environment, you can choose ‘hubot’ from the list of integrations and either use one of the Hubot scripts we've provided or write your own.

Hubot Configuration

After the Hubot integration is configured, you will be able to start the associated Wickr IO client which will also start the Hubot integration and associated scripts.

Hubot Scripting

To create a Hubot Wickr IO integration script follow the official Hubot scripting guide:

https://hubot.github.com/docs/scripting/

or the JavaScript version:

https://github.com/ronmshv/HubotJS/blob/master/docs/scripting.md

Wickr IO Hubot Commands

When the Wickr IO Hubot integration is running you will be able to access the Hubot commands using Wickr. At any time, you can send the client a ‘/help’ command, to get a list of the available Hubot commands.

Slack Integration

To use the Wickr IO Hubot Slack script you will need to setup your Slack account. Initial Setup for a Wickr IO Hubot Integration in Slack done by the admin:

  1. Go on https://api.slack.com/apps --> login to your teams account
  2. Go to "Your Apps" on the upper right corner of the page and choose "Create New App"
  3. Inside the App choose "Add features and functionality" -> "Permissions"
  4. "Add a new Redirect URL": put in the bot's public server address and port + '/authorize' -> Click 'Save URLs'
  5. Scroll down to "Scopes" and select the following Permission Scopes:
    • OTHER
    • Add a bot user with the username @APPNAME (bot)
    • Add commands to Wickr (commands)
    • CHAT
    • Send messages as user (chat:write:user)
    • TEAM
    • Access information about your workspace (team:read)
    • USERS.PROFILE
    • Access user’s profile and workspace profile fields (users.profile:read)
    • USERS
    • Access your workspace’s profile information (users:read)
    • View email addresses of people on this workspace (users:read.email)
    • Click 'Save Changes'
  6. Go back to "Basic Information" under the "Settings" menu on the left
  7. Go to "Add features and functionality" -> "Slash Commands"
  8. Create two new Commands:
    • I.
    • Command: /wickr
    • Request URL: put in the bot's public server address and port + '/slack'
    • Example: 'https://ubuntu.server.com:8090/slack'
    • Short Description: Send a message to a Wickr user
    • Usage Hint: WICKR_ID message ACTUAL_MESSAGE
    • II.
    • Command: /createroom
    • Request URL: put in the bot's public server address and port + '/createroom'
    • Example: 'https://ubuntu.server.com:8090/createroom'
    • Short Description: Create a secure Wickr room. NOTE: to make a user a room moderator put a * next to their name, otherwise all room members will become moderators. Creator of the room will always become a moderator by default.
    • Usage Hint: ROOM_NAME with YOUR_WICKR_ID, WICKR_USER2, WICKR_USER3 etc.
    • III.
    • Command: /createconvo
    • Request URL: put in the bot's public server address and port + '/creategroupconvo'
    • Example: 'https://ubuntu.server.com:8090/groupconvo'
    • Short Description: Creates a secure Wickr Group Convo
    • Usage Hint: with WICKR_USER1, WICKR_USER2, WICKR_USER3 etc.
  9. Now Go back to "Basic Information" under the "Settings" menu on the left
  10. Go to "Add features and functionality" -> "Bots"
  11. Click "Add a Bot User" and Enter the required information, then save by clicking "Add Bot User"
  12. Go to "Interactive components" under the "Features" menu on the left and click "Enable Interactive components"
  13. Under "Request URL" put in the bot's public server address and port + '/slack/actions' and finally click "Enable Interactive components"
    • Example: 'https://ubuntu.server.com:8090/slack/actions'
  14. Finally, choose "Install App" under the "Settings" menu on the left and click "Install App to Workspace"

Note: Slack_Client_ID and Slack_Client_SECRET, which are required to be set as environment variables during the Installation/configuration of the bot, are located on the "Basic Information" page under "App Credentials".

Feedback Welcomed

Here's where we say we hope this helped, have fun, and be safe! Please let us know if there's anything we can do to improve these docs or the integration engine in general.