NAV

Wickr IO

This site contains details about using the Wickr IO Integration Gateway, existing Wickr IO integrations, and how to develop Wickr IO integrations. You will also find information at the end that will help you troubleshoot issues you may run into while using the Wickr IO Integration Gateway as well as developing Wickr IO integrations.

Wickr IO integrations interact with the Wickr client network through the Wickr IO client application. All of the Wickr IO software is distributed using Docker images 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, or bots, are essentially applications that appear as Wickr bots to the Wickr clients.

The first section of this site 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 Wickr platform. The beauty of Wickr IO is that you can create your own integrations easily and quickly.

The second section of this site will describe existing Wickr IO integrations that you have access to. You can install these integrations on your Wickr IO Integration Gateway with your Wickr IO clients in your network. The types of integrations allow you to integrate with other applications like Google Calendar, ZenDesk, Slack, Uber and more. Other integrations available allow you to create a bot that will support sharing files with other people on your Wickr network.

The third section of this site contains details of how to develop your own Wickr IO integrations. All the Wickr IO integration software is maintained in public Github repositories. You can use the software from these integrations as a base to create your own Wickr IO integrations. This area of the site will provide details on the use of Wickr IO APIs that give your integration software access to the Wickr messaging capabilities.

Getting Started

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. You should have some knowledge of using Docker and you will need a Docker login to download the Wickr IO Docker images. Here are some Docker links that may be helpful:

The following sections will be of interest to all users:

People that are going to install and maintain the Wickr IO Integration Gateways, which will include administrators and developers, should be interested in the following sections:

Developers have access to several levels of APIs when developing Wickr IO integration software. Familiarity with all aspects of the Wickr IO system will be helpful when developing Wickr IO integrations. The following sections give details on the available APIs and any other integration components you will need to deal with:

If you are planning on developing Wickr IO integrations, you should read this entire document. Administrators can probably skip the development sections.

Wickr IO Components

The Wickr IO Integrate Gateway is distributed as a Docker container. There are different Docker containers depending on the type of Wickr network you are using, Wickr Professional or Wickr Enterprise. Each Wickr IO Docker container has the following components:

You will have to supply an appropriate host machine to run the Wickr IO 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 will also have the option of using your own or other Wickr IO integration modules published to the NPM registry.

Wickr has published a Wickr IO integration that provides a REST API interface, which can be used to support non-Node.js integrations as well as integrations with remote systems. The REST API associated with the Web Interface integration 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 18.04. The Docker image uses the Ubuntu Linux operating system.

The Wickr IO client and integration software will need access to resources that are external to the Docker image, for example network services or local disk storage. 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 your use case you may have to start the Docker container in a way to allow access to specific network ports or network proxy settings as well. For example, the Wickr Web Interface integration requires a TCP port to expose the REST API to.

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 will 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 will 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.

Security Recommendations

We recommend following best practices and if applicable, your organization’s security policies to secure your Bot deployment. This can include, but isn’t restricted to, firewall rules, host system access auditing, regular host system OS updates, and monitoring. We designed Bots to be both powerful and flexible for custom use cases and while they inherit many security protections from our standard Wickr clients, it falls on you to secure the host system appropriately to protect it (and your Bot) from unauthorized access.

Our Bot container is moderately hardened to remove unnecessary services, etc., but its threat model assumes that it is deployed on an internal network segment (not a DMZ) and configured as a client system. Our Bots run as clients on the Wickr network and remote management access aside does not require inbound network access unless a particular type of integration is configured (E.g., a web interface integration). Don’t forget to augment your security controls as you expand your use cases. The bottom line is if you lose control of your Bot host, you will likely lose control of your Bot and all the data therein, so log only what you need to log, encrypt what you need to encrypt, and use strong access controls.

Wickr IO Docker Container

The Wickr IO Docker container contains the Wickr IO client software and the client service and configuration software. The Wickr IO client, as opposed to the Wickr client, provides a software interface (API) to the Wickr 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 API (using the Web Interface integration) to provide the ability to send and receive messages, as well as create secure rooms and group conversations.

Wickr IO Integration Software

The main component of a Wickr IO integration software (could also be referred to as an app or bot) is the Wickr IO Node.js addon.

The Wickr IO Node.js addon is a public module that is 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 existing public 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:

All of the existing Wickr IO integrations will be described in the Existing Integrations section.

Installation

Once you have a host machine setup and Docker installed, the installation of Wickr IO software is as simple as pulling the appropriate Wickr IO Docker container. If you are not familiar with using Docker then you may want to read through the get started with Docker site. Once you have Docker installed you can pull down the Wickr IO Docker container which is located at the following Docker repository:

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

docker pull public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest
docker pull public.ecr.aws/x3s2s6k3/wickrio/bot-cloud-govcloud:latest
docker pull public.ecr.aws/x3s2s6k3/wickrio/bot-enterprise:latest

The docker images are still maintained in the hub.docker.com repositories:

The Docker container can be pulled down, from the hub.docker.com repositories, to the host machine using the following command:

docker pull wickr/bot-cloud:latest
docker pull wickr/bot-enterprise: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 or on Wickr's GitHub page. The installation of the integrations will be described in the configuration section of this document.

Quick Start

In this section we will demonstrate how to create a sample Wickr IO bot. The following steps will create a Bot that will automatically respond when it receives a message from a user. We will be using the hello world Wickr IO integration. This assumes that you have already installed Docker on the host machine.

  1. Create a Bot user with the Wickr admin console by entering a display name, username, and password. If you do not have access to the Wickr admin console, then you will need your Wickr network administrator to create the bot user for you.

  2. On your host machine make a directory for your docker volume. In this example the directory to create is "/opt/WickrIO". You may need to do this as the root user (i.e. sudo mkdir):

    a. mkdir /opt

    b. cd /opt

    c. mkdir WickrIO

    d. If not added already, add '/opt/WickrIO' to shared paths from Docker -> Preferences -> File Sharing. See https://docs.docker.com/docker-for-mac/osxfs/#namespaces for more info.

  3. Download the Docker image: docker pull public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest (or docker pull wickr/bot-cloud:latest)

  4. Start the docker image in the foreground: docker run -v /opt/WickrIO:/opt/WickrIO -ti public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest Please note this is a sample installation, you may have different Docker arguments with a more permanent installation. Specific Docker options will be described later.

  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 Wickr IO client by entering start and then y and then the bot's password.

  9. Using a Wickr client, that is on the same Wickr network as the Wickr Bot, create a conversation with the Wickr IO bot you created (in step 1) and send a message to your new bot. The Hello World Bot should send you a response.

If you have 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.

Configuration

Once the Wickr Docker software has been installed on your host machine there are several things that need to be configured, including the creation of the Wickr IO client. Some of these configuration steps were used during the quick start sample above, this section will go into the details.

Wickr IO Client Creation

Wickr IO clients are a special type of Wickr account shown as “Bot” users on the Wickr admin console and Wickr clients. Wickr IO client accounts need to be provisioned using 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

Starting the Wickr IO Docker Image

There are many ways to run a docker image with many options. This section will show several options, which ones you use are dependent on what type of integration you will 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 be the same path. When running the Docker container, you will identify where this is located on the host machine, for example:

docker run -v /opt/WickrIOOnHost:/opt/WickrIO -ti public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest

NOTE: If you are on Wickr GovCloud, please remember to modify the above command to replace docker image link with GovCloud image i.e public.ecr.aws/x3s2s6k3/wickrio/bot-cloud-govcloud:latest

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

Please note the shared filesystem is also necessary for cases where you need to give the Wickr IO software running within the Docker container access to files on your host machine. There will be cases during setup or sending files using the Wickr IO APIs when files will need to be accessed by the Wickr IO software. These files will have to be located in the shared filesystem.

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 will 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:

docker run -v /opt/WickrIO:/opt/WickrIO -d --restart=always -ti public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest

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 will have to identify a port or ports that need to be exposed to the software running on the Docker image. The following example shows how port 4001 is exposed from the host machine to the software running on the docker image:

docker run -v /opt/WickrIO:/opt/WickrIO -p 5001:4001 -d --restart=always -ti public.ecr.aws/x3s2s6k3/wickrio/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.

Detached and Attached Operation

In most cases you will be running the Wickr IO Docker image in a detached state. You will need to attach to the Docker container so that you can access the Wickr IO command line interface. The Wickr IO command line interface is necessary to setup, configure and maintain the Wickr IO clients running within the Docker container. To do this you will have to get the Docker container ID or name 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   public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest    "./start.sh"  2 days ago  Up 2 days               MyWickrIODockerImage

$ docker attach 11d5626f74b9
Enter command:

From the example, you will see the container ID 11d5626f74b9 is currently running. Running the docker attach command to that container ID will bring that container to the foreground and allow you to interact with the Wickr IO command line interface. When you type the enter key the “Enter command:” response will be shown.

You can also run the docker attach command using the name you assigned to the Wickr IO docker image when you started it. To assign a name to the image use the --name option when using the docker run command, for example:

docker run -v /opt/WickrIO:/opt/WickrIO -d --restart=always --name="WickrIOCloudProdWelcomeBot" -ti public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest

When you are not using the Wickr IO command line interface you should detach from the Wickr IO docker image. There's a simple control sequence you can enter that will detach from the active Docker image, to do that enter the following control sequence:

<Ctrl>p<Ctrl>q

Which is basically a CONTROL-p followed by a CONTROL-q key sequence. You will 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 is presented when you attach to the Wickr IO Docker container. The previous section described several ways to start and attach to the Docker container.

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

There are no clients currently configured!
Enter command:

You will also see this when you enter the list command on the command interface. When you enter the Wickr IO Docker container, after having configured one or more clients, the list of currently configured clients will be displayed.

Current list of clients:
#  Name                Status   Integration              Version  Events  Misc
===============================================================================
0  file_10_bot         Paused   wickrio-file-bot         5.38.15  0       
1  example_10_bot      Running  wickrio-example-app      5.38.17  5       
2  web_10_bot          Paused   wickrio_web_interface    5.38.17  0       
3  hello_world_10_bot  Running  wickrio-hello-world-bot  5.38.18  4
Enter command:

After the list of clients is displayed, you will then be prompted to enter a command. The following section will describe all of the Wickr IO command line interface commands.

Wickr IO Command Line Interface

The Wickr IO command line interface commands are used to perform operations on the Wickr IO clients and the integrations you associate with them. The commands are broken up into three categories: general commands, client commands and integration commands. General commands are described as follows:

Command Description
help [command] Display the list of commands or help for the specified command.
version Displays the current version number of the running Wickr IO Gateway.
welcome [on|off] Displays the welcome message or changes whether the welcome message is shown at startup. Without the on or off value the welcome message will be shown.

The commands associated with the Wickr IO clients are used to control the Wickr bot clients that you associate with the Wickr IO Gateway system. If you have more than one Wickr IO client running on your Wickr IO Gateway, there are some commands that require you to specify which client to perform the operation on. In that case, you will enter a number which is associated with the client. The number is shown when you run the list command. The example below shows the client number in the first column, under the '#' character:

Enter command:list
Current list of clients:
#  Name                Status   Integration              Version  Events  Misc
===============================================================================
0  file_10_bot         Paused   wickrio-file-bot         5.38.15  0       
1  example_10_bot      Running  wickrio-example-app      5.38.17  5       
2  web_10_bot          Paused   wickrio_web_interface    5.38.17  0       
3  hello_world_10_bot  Running  wickrio-hello-world-bot  5.38.18  4
Enter command:

If there is only one client currently defined, then the number is not required when entering client commands. The following table defines the Wickr IO command line interface client commands:

Command Description
add Adds a Wickr bot client to the Wickr IO Gateway. The Wickr bot client must have been created in the Wickr Admin console. The user will be prompted for information necessary to create the Wickr bot client and any associated integration.
avatar [<#>] This command will change the avatar associated with a Wickr IO Client. You will be prompted to enter the full path to an image file that will replace the current avatar. This file must be accessible to the software running on the Wickr IO docker image.
config [<#>] Re-runs the configuration of the specified Wickr IO Client. Can only be done on paused clients.
delete [<#>] Deletes an existing client from the Wickr IO Gateway. The Wickr bot client will still exist in the Wickr system but will not be associated with the Wickr IO Gateway system after the delete is completed.
events [<#>] Displays the list of events associated with the specified client. Events can identify problems that a bot client is having, as well as indications of when the client was started or stopped.
list [integration] Display a list of Wickr clients that have been added to the Wickr IO Gateway. The client number, name, state and integration name are displayed as well. If an upgrade is available for the associated integration, then it will be indicated as well. The optional 'integration' option will display a list of available integrations, described in the integration's commands below.
modify [<#>] Modify the settings of a client. You will be prompted for the settings associated with the client. You can change the type of integration associated with the client, and/or change the settings.
pause [<#>] Pause a running Wickr IO client.
restart [<#>] Performs a stop and start of the Wickr IO client.
start [<#>] Starts a Wickr IO client. If this is the first time the client has been started, or auto login is false, you will be prompted to enter the password for the Wickr IO client.

The commands associated with integrations are used for two purposes: to upgrade the software associated with an integration or to assist in the development of new custom integrations. The description of creating custom integrations will be described later in this and other documents. The following are the integration commands:

Command Description
export [<#>] Export the integration software associated with the specified Wickr IO client. The integration software will be exported and then can be used with other Wickr IO clients.
import Import custom integration software. The integration software has to adhere to specific requirements, which are described later.
list [integration] The list command with the 'integration' option will display a list of available integrations. The list will include the name of the integration, the type of the integration and the version number if known. The possible types are installed, custom or NPM. Installed integrations are distributed with the Wickr IO Docker image. Custom integrations were created by local developers. NPM integrations are from the public NPM registry. WARNING: As of the 5.47 release the "list integration" command will communicate with the NPM registry to identify the list of integrations that are supported by the current Wickr IO Docker image, based on the appropriate node version. This interaction may take up to a minute to complete.
rename [<#>] Rename the integration of the specified Wickr IO client. This is typically one step in the development of a new custom integration, when using an existing integration as the base for the new integration.
upgrade [<#>] Update integration software for a Wickr IO client. This command will copy the latest integration software for the client and prompt for the configuration settings.

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

Adding a Wickr IO Client

To configure a new Wickr IO client run the add command. Initially, you will be prompted for two fields, the Wickr bot user's username and password. The username is the bot username 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 will have to enter the password for this client every time it's restarted. If you do use this feature, then the password will need to be entered one time during the first login to generate a login key that is unique to this system. The password is never saved anywhere on disk.

Next you will 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 a Wickr IO integration using Wickr's Hubot integration, and the web interface is an integration that supports the Wickr IO REST API.

When you select one of these integrations you will be prompted to enter configuration information that is specific to that integration. Details of these configuration items will be provided in the Existing Integrations section.

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 will 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.

Modifying Wickr IO Client Avatar

As of version 5.90, the Wickr IO CLI was modified to include a command that will allow you to modify the avatar associated with the Wickr IO client. The "avatar" command can be used to modify the avatar for a specific WickrIO client or all of the WickrIO clients that are setup on the appropriate docker image. The following are samples of the "avatar" command usage:

avatar 1
avatar all

With the first example, the value of 1 is the number associated with the bot client you want to set the avatar. You get that number when you run the list command.

The second example shows how to modify the avatar for all of the Wickr IO clients.

When you use the "avatar" command it will prompt you for the full path of where the image is located. This path of course must be visible to the software running on the docker image. You will need to either place the image somewhere in the persistent data area visible to the docker image software or use "docker cp" to copy the file to the docker image (be aware if the docker image restarts that file will be gone).

The new avatar will NOT take effect until you restart the bot client. The avatar command will output a message to that effect. Also, it takes some time for clients to refresh the client properties and then show the new avatar image. If there are errors with your image that will not be shown in the CLI, it will be logged though.

Automatic Configuration

As of the 5.116 release you can use AWS services to define the bot credentials, token values and other configuration information. You can use Wickr published docker images (i.e. bot-enterprise and bot-cloud) to start the bots. If you do use this method to automatically configure your bots you will not need to use the CLI to add the bots to your running docker image. All the credentials for the bots configured using this method will be secure in the AWS secrets manager service.

To use this method to configure your bots you will need to use the AWS_SECRET_NAME environment variable to identify the AWS secret that contains the configuration information.

Secrets Manager Value

The AWS_SECRET_NAME environment variable will identify an ARN that is used to access the specific secret which contains the configuration information needed to start the bots. The following is an example:

AWS_SECRET_NAME='arn:aws:secretsmanager:us-east-1:999999999999:secret:wickenterprise/beta/my-test-bot-zZzZzz'

This secret contains the "wickr_config" key with the value being the configuration information needed to configure and start the bots on the docker image. The configuration information is stored in the secret as an escaped JSON string, for example the following is the plaintext secret value:

{"wickr_config":"{  \"clients\":[  {  \"integration\":\"wickrio-file-bot\",  \"name\":\"user-file-bot\",  \"password\":\"password\",  \"configS3File\": {    \"key\" : \"configs_9-3-21/conf.wickr\",    \"bucket\" : \"bots-for-enterprise\",    \"region\" : \"us-west-2\"  },  \"configPassword\":\"password\",  \"tokens\":[  {  \"name\":\"CLIENT_NAME\",  \"value\":\"user-file-bot\"  },  {  \"name\":\"WICKRIO_BOT_NAME\",  \"value\":\"user-file-bot\"  },  {  \"name\":\"DATABASE_ENCRYPTION_CHOICE\",  \"value\":\"no\"  }  ]  }  ] }"}

The following is the un-escaped value for the “wickr_config” key, in the specified secret.

{
  "clients":[
    {
      "name":"user-file-bot",
      "password":"password",
      "integration":"wickrio-file-bot",
      "configS3File":{
        "key":"configs_9-3-21/conf.wickr",
        "bucket":"bots-for-enterprise",
        "region":"us-west-2"
      },
      "configPassword":"password",
      "tokens":[
        {
          "name":"CLIENT_NAME",
          "value":"user-file-bot"
        },
        {
          "name":"WICKRIO_BOT_NAME",
          "value":"user-file-bot"
        },
        {
          "name":"DATABASE_ENCRYPTION_CHOICE",
          "value":"no"
        }
      ]
    }
  ]
}

This is an example of an enterprise version, it contains the “configS3File and ”configPassword“ key/values which are needed to identify the conf.wickr file. The "key" value for the "configS3File" identifies the folder and filename for the config.wickr file. The "configPassword" identifies the password necessary to descrypt the config.wickr file. These values are not needed for bots running on the bot-cloud Docker images.

Using Custom Integrations

You can also use AWS S3 to load your own custom integrations. You will store them in an AWS S3 bucket, which can then be used by a Wickr IO docker image. The following environment variables will identify the S3 bucket and folder where these custom integrations will be located.

AWS_S3_INTEGRATIONS_REGION='us-east-1'
AWS_S3_INTEGRATIONS_FOLDER='test'
AWS_S3_INTEGRATIONS_BUCKET='wickrio-integrations'

The contents of the AWS S3 bucket/folder will contain one or more folders, one folder for each integration you want to be used by the Wickr IO bot. The name of the folder is used as the name of the integration that you will use to work with your bots. For example, see the image below, there are two folders in the bucket/folder. They are “user-app-bot” and “user-file-bot”, which are the names of those two integrations. If the “integration” value in the "client" entry (see above) has the value "user-app-bot" or "user-file-bot" it will use the integration code from that folder.

Automatic Config S3 Integrations

The contents of each of the integration folders will be the software.tar.gz file that contains all of the integration files (see the section on developing your own custom bots).

Existing Integrations

This section describes existing integrations. Each of the existing Wickr IO integrations has a section that contains the following information:

BroadcastBot Integration

The Wickr IO BroadcastBot allows you to broadcast messages to all of the members of your network or specific security groups. The messages will be sent to each individual within the network or security group using Wickr 1on1 conversations. You can broadcast either messages, files or voice memos. Users that receive a broadcast from the BroadcastBot can also acknowledge receiving messages (using the /ack command).

The BroadcastBot will maintain the status for each message sent on a per user basis. You can retrieve a detailed or summary report of the status for the broadcasts that you have sent.

You can interact with the BroadcastBot using any one of the following types of applications:

The Wickr interface supports a set of commands that allow you to send broadcast messages and retrieve status information associated with the broadcast messages you send. You will interact with the BroadcastBot on a Wickr 1on1 conversation. Details of the supported commands are described in the BroadcastBot Wickr Interface section below.

The web interface is a web-based application that allows you to interact with the BroadcastBot. The web interface is initiated by a command you enter in the BroadcastBot's Wickr 1on1 conversation. Details of the commands and interaction with the BroadcastBot via the web interface are described in the BroadcastBot Web Interface section below.

The REST API interface is provided to allow you to easily integrate the BroadcastBot features into your own applications. The REST API provides the same commands to interact with the BroadcastBot as the other methods of interacting with the BroadcastBot. Details of the REST APIs are described in the BroadcastBot REST API section below.

The Wickr IO BroadcastBot is a public integration. See the Wickr Pro or Wickr Enterprise sections below for details on installation and configuration of the specific Wickr Docker images.

BroadcastBot Wickr Interface

You can interact with the BroadcastBot using commands sent to the BroadcastBot over a 1to1 Wickr conversation. When administrators are being used only those approved Wickr users will have access to all of the BroadcastBot commands, without that setting all users will have full access to the functionality of the BroadcastBot. There are a small set of commands that all Wickr users can use regardless of whether administrators are being used (like the /ack command). Approved users are initially identified when the BroadcastBot is installed and configured, which is described in the Configuration section below. Additional approved users can be added or removed by any approved user on a 1on1 conversation to the BroadcastBot, using /admin commands.

To use the BroadcastBot you will interact via a 1on1 conversation with the BroadcastBot Wickr client. The BroadcastBot will prompt you for any necessary information related to what you are going to broadcast. The following shows a sample dialog with the BroadcastBot to send a broadcast message:

drawing

The BroadcastBot will send the message, file or voice memo to the destination group(s) you select. The broadcast message will be sent on 1on1 conversations between the BroadcastBot and each member of the destination group. The broadcast message will include the identity of who the broadcast was initiated by, for example:

drawing

If you want the user to acknowledge the receipt of the broadcast message that will be mentioned in the broadcast message as well. If you broadcast a file or a voice memo an additional message will be sent to include the identity of the broadcast user as well as the acknowledgement request.

Usage:

To get a list of commands available with the BroadcastBot, the /help command will present the list of the commands and a description of what each one does. The following is a list of the commands supported by the BroadcastBot, the commands in bold can only be used by approved Wickr users if administrators are being used:

Command Description
/abort Stops sending any remaining broadcast messages. This command is useful if you are sending to a large network or security group and need to stop the broadcast. The /status and /report statistics will indicate how many messages were aborted.
/ack Acknowledges all messages you have received from the BroadcastBot.
/admin list Returns a list of the admin users.
/admin add <users> Add one or more admin users. A message will be sent to all admin users identifying the new admin user.
/admin remove <users> Remove one or more admin users. A message will be sent to all admin users identifying the removed admin user.
/broadcast <message> Send the text following the command to the Wickr network associated with the BroadcastBot. The BroadcastBot will prompt you to identify who to send the message to, if you want an acknowledgement, and if you want the message to be repeated.
/cancel This command can be entered when you are in the process of setting up a broadcast message. It will NOT cancel a message that is in process of being sent.
/delete This command can be used to delete a file that was previously made available for the /send command.
/files Returns a list of saved files that are available for the /send command. You can also select a file from the list and have a copy of that file sent to you.
/help Returns a list of commands and information on how to interact with the BroadcastBot
/map Displays a Google Maps link that shows a map that contains pins for the user locations for a specific broadcast message. Users must send their location to the broadcast bot in order for them to be included in the map.
/panel Displays the link and token to the web user interface. This command is available only if the web application was set up during the configuration process.
/report Retrieves a detailed report identifying the list of users a broadcast was to be sent to. The report identifies the state of the message for that user including if the user acknowledged it. Status values include: pending, sent, failed or acknowledged. If a message failed to be sent to a user there will be a message to indicate the failure.
/send <message> Send the text following the command to a predetermined list of users. The list of users will come from one of the files that has been uploaded to the bot and made available for this command during the file upload process.
/start Start a new broadcast
/status Return summary statistics associated with a broadcast.
<file> To broadcast a file, send a file to the BroadcastBot, answer the sequence of questions and the file will be broadcast to the designated users.
<voice memo> To broadcast a voice memo, send a voice memo to the BroadcastBot, answer the sequence of questions and the file will be broadcast to the designated users.
/version Returns the version of your Wickr integration.

When you broadcast a file or a voice memo, the BroadcastBot will then prompt you to identify the destinations of the broadcast (security groups or network).

When you broadcast a text-based message the BroadcastBot will ask you if you want to send the message multiple times and how many minutes between each iteration of sending the broadcast. Currently, you are allowed to wait 5, 10 or 15 minutes between each iteration of sending the broadcast.

Detailed reports are returned in a CSV format, which can be imported into programs such as Excel or Pages. The following image shows a sample summary of a broadcast message, as well as the types of status information maintained by the BroadcastBot:

drawing

NOTE: The current broadcast bot does not support commands via a room or group conversation.

/start Command

The start command is used to initiate a broadcast. When a broadcast is initiated the user will be asked recipients of the broadcast. This can be configured using a User File (a .txt file of Wickr usernames), or by stating the Security Group(s) to which this broadcast will go out.

drawing

If the user selects User File, they can choose from a list of previously uploaded user files or upload a new one by hitting the ‘+’ sign on the navigation bar:

drawing

If the user selects Network or All, they have the option to broadcast the message to the whole network or to one or more security groups:

drawing

The sender can configure the broadcast to request that recipients acknowledge the message, acknowledge with their location or acknowledge with a Response.

drawing

If there are other broadcasts in the queue before the user, they will get a message with an estimated wait time:

drawing

Once the user's broadcast is sent, they will receive a confirmation of this send and a status message to indicate the status of the broadcast. At any point the user can see the status of their broadcast using the /status command or the user can generate a report by running the /report command:

drawing

/send Command

The send command is used to send a message to a predetermined list of users in your Wickr Network. These users will recieve the message in a 1 on 1 conversation with the broadcast bot. In order to use this command you must first upload a file of Wickr user ID's and make that file available for the bot and the /send command.

The file format is simple. Just write the Wickr user ID of each user you wish to send a message to on its own line in a text file (.txt). Commas or any other delimiters at the end of each line should not be included. An example is shown below:

drawing

Once you have a text file of users, you are ready to upload it and make it available to the broadcast bot and send command. To do this go to your direct message conversation with the broadcast bot and click on the plus sign in the bottom right hand corner. A menu will pop up. Click on the option that says "choose file."

You will then be asked what you want to do with the file. Respond by pressing the 'u' key and then pressing enter. If you've been following along then you have just uploaded your file to the bot and made it available for the send command.

drawing

Now you are ready to send a message. To begin the process type /send followed by the message you want to send. For example if you wanted to tell people there is cake in the break room you would type the following: "/send There is cake in the break room!" You will then be prompted to choose which file of users you want to send to. Next you will be prompted if you want an acknowledgement response. Once you make a selection the message will be sent to each user and you will recieve a status message(s) detailing the progress of the message.

drawing

/map Command

This command was added in the 5.60 release of the broadcast bot.

The /map command will display Google Maps link that will display a map that contains pins for all of the users associated with a specific broadcast message. Only the users that send their location to the broadcast bot will be shown on the map. The following image shows the Google Maps image where two users sent their location to the broadcast bot:

drawing

The /map command will only work if it has been configured properly with a Google Maps API key. The following shows the prompts for the config entries associated with the /map command setup.

 Do you want to map users locations when you send broadcasts [yes/no]: (no) :yes
 Please enter your google maps api key: (false) :AIzaSyCkPH2u5f5GAOXabcdef-aJEJFjeaisl

When a user receives a broadcast message they can reply with their location. If the user received multiple broadcast messages and wants to share their location, they can only respond to the most recent one and that location will be used for all of the proceeding broadcasts.

Let's look at an example where a broadcast is sent out to a group of users in the morning three days in a row. The users in this group do alot of travelling during these three days. User A is in Washington DC the first day, on day two he is in New York City and day three is in Boston. Each day when he receives the broadcast, he sends his location. User B is also travelling with user A to the same locations, but he does not send his location until he reaches Boston. At the end of the three days, when you retrieve the map associated with day one you will see User A in Washington DC and User B in Boston. The map associated with day two will show User A in New York City and User B in Boston. The map associated with day three will show both users in Boston.

BroadcastBot Web Interface

This section describes the web interface supported by the BroadcastBot. The web interface is a browser-based interface to interact with the BroadcastBot. Use the /panel command on the BroadcastBot's Wickr interface. The /panel command will return a link that you can use to bring up the web interface. WARNING: the link you receive is only good for a 30 minute period. In order to continue using the web interface you will have to get a new link using the /panel command.

NOTE: The BroadcastBot's web interface is initially supported as of version 5.56.

The screenshot below shows the main landing page for the BroadcastBot's web interface. On this page you can send a broadcast message and view the list of broadcast messages that you have already sent.

drawing

To begin you will want to select the recipients for the broadcast message. Using the drop down box that says "Select Security Groups" you can choose which security group will receive your broadcast message. You also have the option to broadcast to everyone in your network by selecting the "Whole Network" option.

Next write the content of your message in the text box. By clicking on the paperclip in the lower right hand corner of the text box you can attach a file to your broadcast message. You also have the option to ask each recipient for an acknowledgment of your broadcast message. To enable this feature simply check the box next to the words "Ask for acknowledgement". Once your message is ready, click on the "Send" button in the upper right hand corner to begin broadcasting your message.

The list of sent broadcast messages will show information about the broadcast including at least the following:

If you click on the message text of any of the sent messages the detailed list of the users associated with the broadcast will be displayed. You will see the same statistics that were shown on the main screen as well as details of the transmission to each user in the list of users the broadcast is associated with. You can also download a JSON report of the information displayed on this screen.

To update the statistics on your broadcasted/broadcasting messages click on the refresh button in the top right hand corner of the "Sent Messages" table. Messages can also be sorted by date by clicking on the arrow next to the word "Date" in the top left corner of the table. If the arrow is pointing up the messages will be sorted from earliest sent to latest sent. If the arrow is pointing down messages in the table will be sorted from latest sent to earliest sent.

BroadcastBot REST API

This section describes the REST APIs supported by the BroadcastBot. This capability is initially supported in version 5.56 of the BroadcastBot. The following table identifies each of the actions the API supports, the type of HTTP request and the URL used.

API HTTP URL
Get security groups GET https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/SecGroups
Broadcast a message or file POST https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Broadcast
Get list of messages sent GET https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Messages?page=<Page>&limit=<Limit>
Get broadcast summary GET https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Summary?messageID=<MessageID>
Get broadcast details GET https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Report?messageID=<MessageID>&page=<Page>&limit=<Limit>&filter=
Abort broadcast message POST https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Abort?messageID=<MessageID>
Set Event URL Callback POST https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/EventRecvCallback?callbackurl=<url>
Get Event URL Callback GET https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/EventRecvCallback
Delete Event URL Callback DELETE https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/EventRecvCallback

The <API Key> value is the value you entered during the configuration of the Wickr Web Interface integration.

For all of the BroadcastBot REST APIs, the "Authorization" HTTP header will have a value that is "Basic " followed by the base64 encoded value of the Authorization Token value created when the BroadcastBot is configured. For example, the Authorization Token value of "The big red fox" encodes to "VGhlIGJpZyByZWQgZm94" in base64, so you would send the string "Basic VGhlIGJpZyByZWQgZm94" in the "Authorization" HTTP header.

Get Security Groups API

This API is used to get the list of security groups that can be used to broadcast to.

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/SecGroups

The get security groups REST API is an HTTP GET command.

The response will return a JSON array of security group information containing the ID and name of the security groups that you have access to. The following is an example of a response to the get security groups REST API:

[
    { "id": "2jOtbNpA", "name": "only bob" },
    { "id": "h-R3zBuV", "name": "Custom Security Group 5" },
    { "id": "hgQfaqbM", "name": "default" },
    { "id": "iNc4VjAx", "name": "Real Users" },
    { "id": "jBfxwk5u", "name": "Empty Security Group" }
]

NOTE: The ID value returned is the value that will be used in the broadcasting APIs. The name value is for display purposes only.

Broadcast a Message or File API

This API can be used to broadcast a message or a file. The destination for this broadcast can be either a security group, the entire network or a list of users. If you want to send to a security group, you will include the security group ID in the "security_group" value. To send to the entire network you will not send the "security_group" and "users" object in the request. To send to a list of users you will send the "users" object with the list of users. Samples are below.

This is the endpoint associated with the API:

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Broadcast

The broadcast message or file API is an HTTP POST command.

The body of the POST request is JSON and the contents of that JSON will determine the type of broadcast message to send as well as who the broadcast message is going to be sent to. There are several JSON fields used by this API and depending on the type of message 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 broadcast. This value is required.
security_group This is the security group ID to send to. Do not include this entry if sending to the entire network.
users This is a JSON list of users to send to. Do not include this entry if sending to the entire network or a security group. The object for each user can also include a "meta" object that will be associated with the user's entry for the broadcast message. See the examples below that show different uses of the "meta" object.
acknowledge Indicates if an acknowledgement request should be part of the broadcast message. If this is "true" then the acknowledgement request will be included in the broadcast message. This value is optional, if not included an acknowledgement is not requested.
repeat_num The number of times to repeat the broadcast message. This value is optional, if not included then the message will not be repeated.
freq_num The number of minutes to wait between repeating a broadcast message. This value is optional but is required if the "repeat_num" value is present.
bor The burn-on-read value to use when sending the message. This value is optional, will default to the current value set for the conversation.
ttl The time-to-live value to use when sending the message (referred to as Expiration Time in clients). This value is optional, will default to the current value set for the conversation.
user_meta This is a boolean value (true
Broadcasting Messages

To broadcast a message, the HTTP Header must include the Content-Type value of "application/json". The following is a sample JSON object to send a broadcast to the "only bob" security group from the get security group API description above. The security group ID for the "only bob" security group is included in the "security_group" JSON object:

{
    "security_group": "2jOtbNpA",
    "message": "Welcome to Wickr! This message will self-destruct in 5 seconds."
}

The following is a sample JSON object to broadcast a message to the entire network:

{ "message" : "This is a broadcast to a group of users",
}

The following is a sample JSON object to broadcast a message to a list of users:

{ "message" : "This is a broadcast to a group of users",
  "users" : [{"name" : "user1@company.com"},
             {"name" : "biguser44@company.com"},
             {"name" : "smalluser232@company.com"},
             {"name" : "myuser@company.com"},
             {"name" : "thelastuser@company.com"}]
}

The following is a sample JSON object to broadcast a message to a list of users and include meta data for each of the users:

{ "message" : "This is a broadcast to a group of users",
  "users" : [{"name" : "user1@company.com", "meta" : "this is data for User 1 AKA Bit User" },
             {"name" : "biguser44@company.com", "meta" : {"lang":"en", "id":1122324} },
             {"name" : "smalluser232@company.com", "meta" : {"lang":"en", "id":123243} },
             {"name" : "myuser@company.com"},
             {"name" : "thelastuser@company.com", "meta" : "Me" }],
  "user_meta" : true
}

The value of the "meta" object can be a JSON object or a string. When you perform a report command, the value of the "meta" object will be returned for each user in the response.

The response will be a normal HTTP 200 status if successful, or an HTTP error depending on the failure that occurred. The broadcast will go through several stages before the actual broadcast begins, specifically setting up the tables for the broadcast message status information as well as preparing the user information for the users to be broadcast to. Depending on the number of users being broadcast to this pre-broadcast process may take a few minutes (typical when sending to thousands of users).

If the broadcast is initiated successfully a JSON response will be sent containing information associated with the broadcast, including the message sent, the messageID associated with the message and the identity of the destination of the broadcast.

The following is a sample of the output for a broadcast to the entire network:

{
    "data": {
        "message": "This is a broadcast test",
        "message_id": "54",
        "securityGroups": []
    }
}

The following is a sample of the output for a broadcast to a list of users:

{
    "data":{
        "message":"This is a broadcast test and another test",
        "message_id":"56",
        "users":["user1@company.com"]
    }
}

You can use the "message_id" value returned for subsequent calls to get the broadcast message's status and report.

Broadcasting Files

To broadcast a file, the Content-Type HTTP header used for this REST API is different because it has a value of "multipart/form-data'. This is necessary so the file can be part of the request. The body will have two parts, one for the file to broadcast, and the other part to identify who to broadcast to and if there are other broadcast settings (similar to the Broadcast Message API).

The part that identifies the file to transmit has a key value of "attachment", and the value is the actual file to transmit.

The part that contains the broadcast information is a JSON string that is exactly the same as that defined above. The "message" object is used to send a message that is also broadcast with the file.

The response will be a normal HTTP 200 status if successful, or an HTTP error depending on the failure that occurred. The broadcast will go through several stages before the actual broadcast begins, specifically setting up the tables for the broadcast message status information as well as preparing the user information for the users to be broadcast to. Depending on the number of users being broadcast to this pre-broadcast process may take a few minutes (typical when sending to thousands of users).

Get List of Messages Sent API

This API is used to get a list of the broadcast messages that were sent via the REST application APIs.

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Messages?page=<Page>&limit=<Limit>

The get list of messages sent API is an HTTP GET command.

The number of broadcasts sent can grow over time so you will have to limit the size of the response by selecting an appropriate "Page" and "Limit" values. The "Page" value starts at 0. The "Limit" value identifies the number of message entries in each page. A page size of 1000 is likely to be okay. If you have more than 1000 broadcast messages, then you will have to make multiple calls to page through the messages. Each response will contain a "max_entries" value which indicates the total number of broadcast messages associated with the Wickr user.

The response to the get list of messages sent API will look like the following example:

{
    "list": [
        {
            "message": "Hello. This is a broadcast to a list of users",
            "message_id": "3",
            "sender": "user123@wickr.com",
            "target": "USERS",
            "when_sent": "2020-06-08T21:18:15.511Z"
        },
        {
            "message": "Hello this is a sample broadcast to a security group",
            "message_id": "4",
            "sender": "user123@wickr.com",
            "target": "hgQfa8TM",
            "when_sent": "2020-06-08T22:08:59.855Z"
        },
        {
            "message": "This was a broadcast to an entire network",
            "message_id": "5",
            "sender": "user123@wickr.com",
            "target": "NETWORK",
            "when_sent": "2020-06-08T22:16:20.463Z"
        },
        {
            "message": "This was a broadcast of a file",
            "message_id": "13",
            "sender": "user123@wickr.com",
            "target": "NETWORK",
            "when_sent": "2020-06-09T22:17:48.469Z"
        }
    ],
    "max_entries": 5,
    "source": "user123@wickr.com"
}

The "max_entries" value identifies how many broadcast entries are associated with the "source" user. This value can be used to help identify how many pages of messages you may have to download.

The "target" value in each of the "list" entries identifies if the broadcast was to a specific security group, the entire network ("NETWORK") or a list of users ("USERS").

Get Broadcast Summary API

This API is used to get the summary status of a specific broadcast message. The message is identified by the message ID value, use the Get List of Messages Sent API to get the appropriate message ID.

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Summary?messageID=<MessageID>

The get broadcast summary API is an HTTP GET command.

This API will return a JSON object with the following values:

KEY Description
aborted Number of users that were not sent to because the message was aborted. See the Abort REST API for details.
acked Number of users that acknowledged receiving this message using the /ack command.
failed Number of users that did not get the message due to a failure to send the message. See the detail report for details on failure types.
ignored Number of users that were not sent to because the account was a bot. Bots will not be broadcast to.
num2send Number of users that are associated with this message.
pending Number of users that have not been sent to yet.
read Number of users that have read the message sent to them. This will only be set if read receipts are supported by your Wickr servers.
sent Number of users that have been sent to for this broadcast.
status A status value that will be a value of "Preparing" if the broadcast is in the preparation state, pending the actual broadcast of messages.

The response to this API will include all of these values. The "status" value will only be included if the broadcast is preparing the broadcast data structures. For large broadcasts this may take some time. When in this state the other status values will have a value of 0.

Get Broadcast Details API

This API is used to get the detailed status of a specific broadcast message. The information returned is a list of entries, one for each user the broadcast was transmitted to. Use the Get List of Messages Sent API to get the appropriate message ID. Since it is possible the broadcast will be sent to thousands of users your request will have to identify the page and page size values. It is recommended to not make the page size too large. This API supports a filter option to select one or more status types to retrieve for the associated MessageID.

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Report?messageID=<MessageID>&page=<Page>&limit=<Limit>&filter=<Filter>

The get broadcast details API is an HTTP GET command.

The filter value is used to select which status entries to retrieve. the value is a comma separated list of the filters to retrieve. The status values that you can use to filter on are: "pending" "sent" "failed" "acked" "ignored" "aborted" "read". This filter is optional, if you do not want to filter then do not include the filter .

The response to this request will be a list of entries with the following fields:

KEY Description
user The Wickr ID of the user associated with this entry
status This is the status of the broadcast to this specific user. This value can be one of the values shown in the Get Broadcast Summary API section above.
statusMessage This is a message associated with the status value. If the status is "failed" this field will identify why the send failed. If the user acknowledges the message by sending their location, this field will have a URL that shows their location.
sentDate This is the date and time the message was sent. The date format is the following: 2020-06-14 17:27:27 UTC
readDate This is the date and time the message was read, if read receipts are supported by your Wickr server. The date format is the following: 2020-06-14 17:27:27 UTC

Abort Broadcast Message API

This API is used to abort a broadcast message that is currently being transmitted. This is typically only useful for broadcasts to large numbers of users. Broadcasts to small numbers of users will likely complete too quickly for this API to be useful. Use the Get List of Messages Sent API to get the appropriate message ID.

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/Abort?messageID=<MessageID>

The abort broadcast message API is an HTTP POST command.

The response will be a normal HTTP 200 status if successful, or an HTTP error depending on the failure that occurred. The response body will contain a JSON object with a "result" string and a "status" object that contains the summary status associated with the MessageID used to perform the abort operation. The following is a sample output from a successful abort command:

{
    "result": "Success",
    "status": "{
        "aborted": 1900,
        "acked": 0,
        "failed": 0,
        "ignored": 0,
        "num2send": 2000,
        "pending": 0,
        "read": 0,
        "sent": 100
    }
}

Abort commands that fail will return a string identifying the type of error. Typical errors invalid messageID values or trying to abort a messageID that is not associated with the bot user.

Event Callbacks

Event callbacks will define a URL that the bot client will connect to when a messaging event occurs. Information about the event will be sent to the defined URL. It is assumed that there is an application consuming, and acknowledging, events that are pushed to this URL. For example, if you run a process on the same machine as the Wickr IO client you can use a URL like the following:

http://localhost:4100

Events that are posted to the set URL will have the following sample format:

{
    "message_id" : "9",
    "reason" : "Failed verification",
    "user" : "user555@somewher.com"
}

Set Event Callback URL API

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

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/EventRecvCallback?callbackurl=<url>

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

Get Event Callback URL API

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

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/EventRecvCallback

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:

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

Delete Event Callback URL Callback

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

https://<host>:<port>/WickrIO/V2/Apps/Broadcast/<API Key>/EventRecvCallback

The client will respond with a success or failure response.

Broadcast Bot Message Send Failures

It is possible that when broadcasting to a group of users there may be a failure with the destination user's account. This section will describe some of the possible failures that may happen when sending a broadcast.

KEY Description
"Failed verification" This failure message indicates the account is not valid. Could be in a suspended state as well.
"Could not find user record" This failure message also indicates the account is not valid. Could be in a suspended state as well.
"Message failed to send, check user account" This failure usually indicates an issue with the user account being sent to. Something like no active devices associated with the account.
"msgSvcSend failed" This failure is due to an internal issue. Could be the process associated with transmitting messages was not fully initialized, this could be very rare. Retransmitting the message to the effected user(s) should work.
"sendFile failed" This failure can happen when broadcasting a file but is very rare as well. Retransmitting the message to the effected user(s) should work.
"No users on the 1to1" This failure is an internal error and is very rare. If this type of error does occur, retransmitting should work.

There are other failures possible and they are associated with network or system issues that may occur. If those errors do occur retransmitting the message to the effected user(s) should work.

Broadcast Bot Pro Installation

This section describes the requirements and configuration of the BroadcastBot for Wickr Pro networks.

Requirements:

Before you can install and configure the BroadcastBot, you will need to create a Wickr Bot user via the appropriate Wickr admin console. The Wickr IO Client Creation section describes how to create a Wickr IO client on the Wickr Admin console.

The following is a list of tokens that are required to start/configure a Wickr BroadcastBot integration:

Configuration:

You will need to have some familiarity with Docker in order to configure and start the Wickr BroadcastBot. The Starting the Wickr IO Docker Image section has some helpful information on working with Wickr Docker images.

The following are steps you can use to create a BroadcastBot integration:

  1. Start the docker image, which will download the docker image, if needed. Note: assign a unique name to this docker image which you can use for other docker commands, also note there are 2 ports opened (4002 and 8080) with the following docker run command:
    docker run -v /opt/WickrIOShare:/opt/WickrIO -p 4002:4002 -p 8080:8080 -d --restart=always --name="MyBCastBot" -ti public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest

NOTE: If you are on Wickr GovCloud, please remember to modify the above command to replace docker image link with GovCloud image i.e public.ecr.aws/x3s2s6k3/wickrio/bot-cloud-govcloud:latest

  1. Attach to the docker image, using the name from the previous step: docker attach MyBCastBot

  2. Agree to the license agreement, if you have not already done so.

  3. Enter the add command at the prompt, filling in the username and password you created in step one.

  4. Enable autologin.

  5. Enter the broadcast bot integration from the list, for example wickrio-broadcast-bot

  6. Respond to the configuration prompts with appropriate values, see the sample output below.

  7. The broadcast bot is configured now. Start the client by entering start and then y and then the password.

If you have followed along so far you now have the broadcast bot running on your network!

The following is sample output from adding a broadcast bot:

Enter command:add
Enter the user name:bcast_bot
Enter the password:********
Creating user:  "bcast_bot"

Begin registration with password.
Begin register new user context.

Begin register existing user context.

Successfully created user

Successfully logged in as new user!

Our work is done here, logging off!

Return code from provision is: 0

The autologin capability allows you to start a bot without having to enter the
password, after the initial login.
NOTE: The bot client's password is NOT saved to disk.

Do you want to use autologin? (default: yes):
Searching NPM registry
Searching NPM registry
Searching NPM registry

These integrations are local:
  - hubot

These integrations are from the NPM registry:
  - wickrio_web_interface
  - wickrio-file-bot
  - wickrio-hello-world-bot
  - wickrio-example-app
  - wickrio-broadcast-bot

Please enter one of:
  - The full integration name from the list above
  - The word "search" to search the NPM registry for an integration
  - The word "import" to import an integration
  - The word "quit" to cancel adding the bot

Enter the bot integration to use:wickrio-broadcast-bot
**********************************************************************
Begin setup of wickrio-broadcast-bot software for bcast_bot
Copying wickrio-broadcast-bot software

Installing wickrio-broadcast-bot software
Installing
Installing
Begin configuration of wickrio-broadcast-bot software for bcast_bot
Adding ADMINISTRATORS to the list of tokens
Adding VERIFY_USERS to the list of tokens
 Do you want to encrypt the configuration values [yes|no]: (no) :
 Do you want to setup the web interface (REST API or WEB Application) [yes/no]: (no) :yes
 Do you want to use the web application [yes/no]: (no) :yes
 Please enter the host name or ip address to reach the web application: (false) :54.1.2.3
 Please enter the host port to use to reach the web application: (false) :8080
 Do you want to use the REST application [yes/no]: (no) :yes
 Please enter your client bot's port: (false) :4002
 Please enter your client bot's API-Key: (false) :ABCDEF
 Please create an Web API Basic Authorization Token, we recommend an alphanumeric string with at least 24 characters: (false) :12345678901234567890ABCD
 Do you want to set up an HTTPS connection with the Web API Interface, highly recommended [yes/no]: (no) :
 Do you want to map users locations when you send broadcasts [yes/no]: (no) :
 Enter the list of administrators: (N/A) :auser01,auser02
 Enter the mode to verify users: (automatic) :
Finished Configuring!

Integration files written to:
/opt/WickrIO/clients/bcast_bot/integration/wickrio-broadcast-bot

End of setup of wickrio-broadcast-bot software for bcast_bot
**********************************************************************
Successfully added record to the database!
Enter command:start 1
Do you really want to start the client with the name bcast_bot:yes
Enter password for this client:************************
Enter command:

For assistance in starting and running the BroadcastBot Docker image please contact wickr-support@amazon.com.

Broadcast Bot Enterprise Installation

This section describes the requirements and configuration of the BroadcastBot for Wickr Enterprise networks.

Requirements:

Before you can install and configure the BroadcastBot, you will need to create a Wickr Bot user via the appropriate Wickr admin console, in a specific network. The associated Wickr username and password will be used when creating the BroadcastBot bot. The Wickr IO Client Creation section describes how to create a Wickr IO client on the Wickr Admin console.

When running a BroadcastBot in a Wickr enterprise network you will need to download the appropriate Wickr configuration file. This file will need to be copied to the system where the BroadcastBot docker image is running. The Configuration section below identifies the location this configuration file is to be placed.

The following is a list of tokens that are required to start/configure a Wickr Enterprise BroadcastBot integration:

Configuration:

You will need to have some familiarity with Docker in order to configure and start the Wickr BroadcastBot. The Starting the Wickr IO Docker Image section has some helpful information on working with Wickr Docker images.

When running in a Wickr enterprise environment you will need to get a Wickr configuration file and place it on the system where you will be running the BroadcastBot. The location must be visible to the software running on the WickrIO docker container, this is identified by the shared location option (-v) assigned by the "docker run" command. This configuration file must be present when you create the BroadcastBot. We recommend the location of where to place the Wickr configuration file is the following location, where "WickrIOShare" is the location used with the "docker run" command:

/opt/WickrIOShare/config/config.wickr

Where "/opt/WickrIOShare" is the location on the host machine that the Docker image is going to be running. This is a shared directory that will be identified to the Docker image when you perform the "docker run" command (see below). The name of the Wickr configuration has no specific requirements, but if you add multiple bots to the Docker image you may need to make it unique if there are bots from different networks.

The following are steps you can use to create a Wickr Enterprise BroadcastBot integration:

  1. Start the docker image, which will download the docker image, if needed. Note: assign a unique name to this docker image which you can use for other docker commands, also note there are 2 ports opened (4002 and 8080) with the following docker run command:

    docker run -v /opt/WickrIOShare:/opt/WickrIO -p 4002:4002 -p 8080:8080 -d --restart=always --name="MyBCastBot" -ti public.ecr.aws/x3s2s6k3/wickrio/bot-enterprise:latest

  2. Attach to the docker image, using the name from the previous step: docker attach MyBCastBot

  3. Agree to the license agreement, if you have not already done so.

  4. Enter the add command at the prompt, filling in the username and password you created in step one.

  5. Enter the location and full name of the Wickr configuration file, and then the password associated with the configuration file.

  6. A random password will be generated during registration. Ensure this password is saved as it will be needed for any restarts or migrations later.

  7. Enable autologin.

  8. Enter the broadcast bot integration from the list, for example wickrio-broadcast-bot

  9. Respond to the configuration prompts with appropriate values, see the sample output below.

  10. The broadcast bot is configured now. Start the client by entering start and then y and then the password.

If you have followed along so far you now have the broadcast bot running on your network!

The following is sample output from adding a broadcast bot:

Enter command:add
Enter the user name:bcast_bot
Enter the password:********
Creating user:  "bcast_bot"

********************************************************************
**** GENERATED PASSWORD
**** DO NOT LOSE THIS PASSWORD, YOU WILL NEED TO ENTER IT EVERY TIME
**** TO START THE BOT
****
 "xw8qatdNFYqbOZV3P9VnLgTg"
********************************************************************
Begin registration with password.
Successfully created user
********************************************************************
**** USER SIGNING KEY
**** You will need this to enter into the console for the Bot
****
 "00040191c55b3efb7a2ab5bbc53fc5a736d5e7ce8eead3c33d2807e0912e533030df1663a0fb12259b268cbadb0ed41b07ed9f6f3d0bb8ce949dc81f802218d29319e634000407610309ffa9fc13df5efb9b9f65b00b2539c45c1065b30584d5b440b5da3e97e098f6ab1b5e3fbd07932e7e51798a01b6b1e73c4cdc0feb1a9ea4e31b74d8ce"
********************************************************************

Successfully logged in as new user!
Our work is done here, logging off!
Return code from provision is: 0

The autologin capability allows you to start a bot without having to enter the
password, after the initial login.
NOTE: The bot client's password is NOT saved to disk.

Do you want to use autologin? (default: yes):
Searching NPM registry
Searching NPM registry
Searching NPM registry

These integrations are local:
  - hubot

These integrations are from the NPM registry:
  - wickrio_web_interface
  - wickrio-file-bot
  - wickrio-hello-world-bot
  - wickrio-example-app
  - wickrio-broadcast-bot

Please enter one of:
  - The full integration name from the list above
  - The word "search" to search the NPM registry for an integration
  - The word "import" to import an integration
  - The word "quit" to cancel adding the bot

Enter the bot integration to use:wickrio-broadcast-bot
**********************************************************************
Begin setup of wickrio-broadcast-bot software for bcast_bot
Copying wickrio-broadcast-bot software

Installing wickrio-broadcast-bot software
Installing
Installing
Begin configuration of wickrio-broadcast-bot software for bcast_bot
Adding ADMINISTRATORS to the list of tokens
Adding VERIFY_USERS to the list of tokens
 Do you want to encrypt the configuration values [yes|no]: (no) :
 Do you want to setup the web interface (REST API or WEB Application) [yes/no]: (no) :yes
 Do you want to use the web application [yes/no]: (no) :yes
 Please enter the host name or ip address to reach the web application: (false) :54.1.2.3
 Please enter the host port to use to reach the web application: (false) :8080
 Do you want to use the REST application [yes/no]: (no) :yes
 Please enter your client bot's port: (false) :4002
 Please enter your client bot's API-Key: (false) :ABCDEF
 Please create an Web API Basic Authorization Token, we recommend an alphanumeric string with at least 24 characters: (false) :12345678901234567890ABCD
 Do you want to set up an HTTPS connection with the Web API Interface, highly recommended [yes/no]: (no) :
 Do you want to map users locations when you send broadcasts [yes/no]: (no) :
 Enter the list of administrators: (N/A) :auser01,auser02
 Enter the mode to verify users: (automatic) :
Finished Configuring!

Integration files written to:
/opt/WickrIO/clients/bcast_bot/integration/wickrio-broadcast-bot

End of setup of wickrio-broadcast-bot software for bcast_bot
**********************************************************************
Successfully added record to the database!
Enter command:start 1
Do you really want to start the client with the name bcast_bot:yes
Enter password for this client:************************
Enter command:

For assistance in starting and running the BroadcastBot Docker image please contact wickr-support@amazon.com.

Hubot Integration

The Wickr IO Integration Gateway includes built-in support for Github's own 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, the existing open source hubot scripts or write your own. For more information on Hubot and what it's capable of doing visit: https://hubot.github.com/

Hubot Commands

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

Hubot Scripting

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

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

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. Once started, users in your network will now have the ability to interact with the Hubot integration via their Wickr clients. To get a list of commands available send the /help command to the Wickr bot account associated with the Wickr Hubot.

Hubot Slack Integration

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

The following is a list of the commands supported by the Hubot Slack integration:

Command Description
/wickr WICKR_ID message ACTUAL_MESSAGE Send a message to a Wickr user
/createroom ROOM_NAME with YOUR_WICKR_ID, WICKR_USER2, WICKR_USER3 etc. Create a secure Wickr room
/createconvo with with YOUR_WICKR_ID, WICKR_USER2, WICKR_USER3 etc. Create a secure Wickr Group Convo
  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", fill in the "App Name" and choose your "Development Slack Workspace".

  3. Inside the App choose "Add features and functionality" -> "Permissions"

    drawing

  4. "Add a new Redirect URL": put in the public address and port of the server you are running the bot container on + '/authorize' -> Click 'Save URLs'

    drawing

  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'

      drawing

      drawing

  6. Go back to "Basic Information" under the "Settings" menu on the left

  7. Go to "Add features and functionality" -> "Slash Commands"

    drawing

  8. Create three new Commands:

    • I.
      • Command: /wickr
      • Request URL: put in the bot's server address + '/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 server address + '/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 server address + '/creategroupconvo'
      • Example: 'https://ubuntu.server.com:8090/groupconvo'
      • Short Description: Create a secure Wickr Group Convo
      • Usage Hint: with WICKR_USER1, WICKR_USER2, WICKR_USER3 etc.

      drawing

  9. Now Go back to "Basic Information" under the "Settings" menu on the left

  10. Go to "Add features and functionality" -> "Bots"

    drawing

  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 turn on "Interactivity"

  13. Under "Request URL" put in the bot's server address + '/slack/actions' and click "Save Changes" on the bottom of the page

    • 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: 1. 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". 2. Bot's server address = public address and port of the server you are running the bot container on

Hubot Uber Integration

A Hubot script that allows users to order and get ride information from Uber using Wickr.

The following is a list of the commands supported by the Hubot Uber integration:

Command Description
/uber price <origin> to <destination> Cost and duration of a ride from the <origin> address to the <destination> address
/uber time Time an Uber car will take to get to your current location
/uber ride <origin> to <destination> Requests a ride from the <origin> address to the <destination> address
/uber current Current ride Information
/uber cancel Cancel current ride

Configuration:

First, you need to create an App on the Uber Developers dashboard.

  1. Go here and select the green box on the right side of the page labeled "+ new app"
  2. Fill in the name and description and click 'Create'
  3. It will then redirect you the Auth settings of your newly created Uber app

  4. Under 'Redirect URI' put in the public address and port of the server you are running the bot container on, this URL has to end with /authenticate, ex: https://hubotserver.com:8080/authenticate Then following tokens should be saved from under the App you created:

    drawing

  5. Scroll down to 'General Scopes' and select 'request', 'request_receipt' and 'all_trips'

    drawing

  6. Then scroll down to "GENERATE AN OAUTH ACCESS TOKEN FOR YOUR APPLICATION" and click the "AUTHORIZATION CODE" button and save the generated access token that shows up in the text box

    drawing

  7. Finally, go to the bottom of the page and hit the 'Save' button

  8. On the top of the page you can find the values for the following tokens:

Hubot Salesforce Chatter Integration

A Hubot script that allows users to send messages to Salesforce Chatter users from Wickr.

Commands:

Configuration:

First, you need to create an app on the Salesforce Chatter Developers dashboard:

https://na50.lightning.force.com/lightning/setup/NavigationMenus/home.

For a complete guide:

https://help.salesforce.com/articleView?id=connected_app_create.htm&type=5

Then following tokens should be saved from the App you created:

Google Calendar Integration

The Wickr IO Google Calendar Bot allows you to create, modify and list Google Calendar events in addition to setting Google Calendar in-app or email reminder notifications before events. It also allows setting in-Wickr app room or personal notifications.

The Wickr IO Google Calendar integration supports the following commands:

Command Description
/help List all available commands
/list List 5 most recent upcoming Google Calendar events
/list <number> List <number> of upcoming Google Calendar events
/create Create a Google Calendar event
/modify <event ID> Modify the specified Google Calendar event. Run '/list' first to get the list of events and their IDs.

Requirements:

If you are the admin and setting up this bot, you need to have the following information:

Required tokens:

Configuration:

  1. First create a Google Calendar API project at https://console.developers.google.com/
  2. After creating the project, Click 'Enable APIS and Services' and search for Google Calendar API and click 'Enable'
  3. On the left Menu Bar select "Credentials" -> "Create Credential"
  4. Choose "OAuth Client ID", then under "Application type" choose "Web Application"
  5. Enter your bot_client_server in the "Authorized JavaScript origins" and "Authorized redirect URIs" fields and click "Create"
  6. Finally download and save your OAuth Client credentials, which will contain the following tokens that will you will be prompted for during configuration:

Example App Integration

An easy to get started Wickr IO API Example integration template which shows the basic code needed to get started writing a Wickr IO API integration. Note: This is a good template to edit and create a custom integration for Wickr

The Wickr IO Example App Bot software is located here.

FileBot Integration

Wickr provides a sample integration that allows storing, removal and retrieval of files by a Wickr IO bot. Wickr users on the same network as the Wickr FileBot can interact with the bot to share files with each other.

You can create a Wickr bot using the Wickr FileBot integration software. The Wickr IO File Bot software is public and is located here.

The Wickr IO file bot supports the following commands:

Command Description
/help Return a list of all available commands
/list Return a list of all available files
/get <filename> Retrieves the specified file
/delete <filename> Deletes the specified file

Hello World Integration

This integration responds to users messages with canned responses, each response will be sent out in a well-defined sequence associated with the Wickr user sending to the Wickr IO client. The Wickr IO Hello World integration is a sample integration, which can be used as a base to create new custom integrations.

The Wickr IO Hello World Bot software is located here.

Web Interface Integration

The Web Interface integration allows remote software the ability to interact with the associated Wickr IO client via a REST API. The Wickr IO Web Interface integration supports the REST API via either an HTTP or HTTPS interface. This REST API supports the ability to create conversations, send and receive messages to other Wickr users, and perform other Wickr tasks.

The Wickr IO Web Interface integration software is located here.

REST API Configuration

During the installation of the Wickr IO Web Interface software module, you will need to configure several properties that are needed to access the URL endpoints. The Wickr IO command line interface will walk you through entering these values. The following table describes the values that you will have to enter during the configuration of the Wickr IO Web Interface:

Value Description
Port The TCP/IP port that the Wickr IO bot will listen on. NOTE: you will have to add the port to the docker run command that starts the Wickr IO Docker container so that port is made available to the Wickr IO integration software.
API-Key The API Key that is used in every endpoint call. This is the <API Key> value that is contained in every endpoint URL, as is shown in the table in the previous section.
Basic Authorization Token The authentication string used to generate the Base64 value to be sent in the authorization field of the HTTP Header (Recommended: 24-character alphanumeric string). You will need to generate a Base64 value of this token and the add it to the HTTP authorization header (i.e. Basic MDEyMzQ1Njc4OTAxMjM0NTY3ODkwMTIzNA==).
SSL Key Location Full path name of the .key file (only required if you are going to use HTTPS). The file must be located in the shared directory that the integration software running on the Docker image can access.
SSL Cert Location Full path name of the .cert file (only required if you are going to use HTTPS). The file must be located in the shared directory that the integration software running on the Docker image can access.

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

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

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 Wickr IO server. If the proper authentication information is not presented to the Wickr IO server then an HTTP 401 response will be sent.

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

  1. When the associated Wickr IO bot client is configured and associated with the Web Interface integration, the associated authentication string will be setup. You will use this string 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.

Web Interface Integration Installation

This section shows the steps to add a Wickr IO Web Interface integration. The following steps will create a Wickr IO Bot with the Web Interface integration. This integration will expose the HTTP/HTTPS interface to facilitate access to the associated Wickr IO client. When installing the Web Interface Integration on a host machine that has multiple network interfaces you can either bind the docker image that the Web Interface Integration resides on to all interfaces on the host machine OR you can bind to a specific interface by specifying the IP address.

  1. Using the admin console create the associated Wickr IO bot user by entering a display name, username, and password.
  2. Make a directory for your docker volume:
    • sudo mkdir /opt
    • cd /opt
    • sudo mkdir WickrIO
    • For Docker running on Mac, if not added already, add '/opt/WickrIO' to shared paths from Docker -> Preferences -> File Sharing. See https://docs.docker.com/docker-for-mac/osxfs/#namespaces for more info.

  3. If you are going to use HTTPS to communicate with the Wickr IO integration you will need to generate a cert and key file. For example, you can use the following command to do so:

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

    You will need to place the key and certificate files in a location the software running on the docker container can access, this is somewhere in the /opt/WickrIO directory (you created in the previous step).

  4. Start the docker image, which will download the docker image if needed. Note: the name you can assign to this docker image and use for other docker commands:

    docker run -v /opt/WickrIO:/opt/WickrIO -p 4001:4001 -d --restart=always --name="MyWickrIOImage" -ti public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest

    Please note the "-p 4001:4001" option which identifies which TCP port the web interface will listen on, you will have to enter that later.

    If your host machine has multiple network interfaces and you would like to specify the network interface the Web Interface Integration will run on you can add the IP address of that network interface to the docker run command like so:

    docker run -v /opt/WickrIO:/opt/WickrIO -p xx.xx.xx.xx:4001:4001 -d --restart=always --name="MyWickrIOImage" -ti public.ecr.aws/x3s2s6k3/wickrio/bot-cloud:latest

    Where xx.xx.xx.xx is the IP address of the network interface you would like to use.

    NOTE: If you are on Wickr GovCloud, please remember to modify the above command to replace docker image link with GovCloud image i.e public.ecr.aws/x3s2s6k3/wickrio/bot-cloud-govcloud:latest

  5. Attach to the docker image, using the name from the previous step: docker attach MyWickrIOImage

  6. Agree to the license agreement.

  7. Enter the add command at the prompt, filling in the username and password you created in step one.

  8. Enable autologin.

  9. Enter the web interface integration from the list, for example wickrio_web_interface

  10. Enter the port number you identified previously.

  11. Enter an API Key value. This is a string that will be part of every REST call you make to the web interface bot.

  12. Enter a Basic authorization token value. This is an alphanumeric value used as the basic authorization for the REST calls. It is recommended that you enter at least 24 characters.

  13. If you are using HTTPS enter the location and name of the key and certificate files. These files will have to be located in the /opt/WickrIO directory you created earlier, so that the Wickr IO integration software running on the Wickr IO Docker image have access to the files.

  14. The web interface bot is configured now. Start the client by entering start and then y and then the password.

If you have followed along so far you now have the Web Interface Bot running on your network! The REST API is fully described in the next section. To access the REST API you can use curl or a program like Postman to test that everything is working as expected.

The following is sample output from adding a web interface bot:

Enter command:add
Enter the user name:test_web_bot
Enter the password:********
Creating user:  "test_web_bot"

Begin registration with password.
Begin register new user context.

Begin register existing user context.

Successfully created user

Successfully logged in as new user!

Our work is done here, logging off!

Return code from provision is: 0

The autologin capability allows you to start a bot without having to enter the
password, after the initial login.
NOTE: The bot client's password is NOT saved to disk.

Do you want to use autologin? (default: yes):
Searching NPM registry
Searching NPM registry
Searching NPM registry

These integrations are local:
  - hubot

These integrations are from the NPM registry:
  - wickrio_web_interface
  - wickrio-file-bot
  - wickrio-hello-world-bot
  - wickrio-example-app

Please enter one of:
  - The full integration name from the list above
  - The word "search" to search the NPM registry for an integration
  - The word "import" to import an integration
  - The word "quit" to cancel adding the bot

Enter the bot integration to use:wickrio_web_interface
**********************************************************************
Begin setup of wickrio_web_interface software for test_web_bot
Copying wickrio_web_interface from the NPM registry
Installing wickrio_web_interface software for test_web_bot
Installing
Begin configuration of wickrio_web_interface software for test_web_bot
going to use /tmp/WickrIOSvr.WDmxyv
 Please enter your client bot's port::4001
 Please enter your client bot's API-Key::testAPIkey1234
 Please create an Web API Basic Authorization Token(we recommend an alphanumeric string with at least 24 characters)::123456789012345678901234
 Do you want to set up an HTTPS connection with the Web API Interface(Recommended)(y/n)::y
 Please enter the name and location of your SSL .key file::/opt/WickrIO/files/my.key
 Please enter the name and location of your SSL .crt file::/opt/WickrIO/files/my.cert

Integration files written to:
/opt/WickrIO/clients/test_web_bot/integration/wickrio_web_interface

End of setup of wickrio_web_interface software for test_web_bot
**********************************************************************
Successfully added record to the database!
Enter command

Web Interface REST API

This section describes the REST APIs that are supported by the 2.x version of the Wickr IO 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
Send File POST https://<host>:<port>/WickrIO/V1/Apps/<API Key>/File
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>

The <API Key> value is the value you entered during the configuration of the Wickr Web Interface integration.

Send Message APIs

The send message APIs are used to send a message to one or more Wickr clients. To have a specific Wickr IO client send a message, send an HTTP POST message to the following URI:

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

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 a list of Wickr user IDs to send a message to. Not used when sending to a secure room or group conversation, use the vgroupid value when sending to secure room or group conversations. A separate 1on1 message will be sent to each of the users in this list.
bor The burn-on-read value to use when sending the message. Optional, will default to the current value set for the conversation.
ttl The time-to-live value to use when sending the message (referred to as Expiration Time in clients). Optional, will default to the current value set for the conversation.
vgroupid The vgroupid to use when sending to a secure room or group conversation. Do NOT use this value when sending to 1on1 conversations.
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 Wickr IO system or addressable and downloadable using a specific URL. If the file is located on the Wickr IO system, it must be located where the Wickr IO client running on the Docker image can access it.

Sending a single message to multiple recipients

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

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

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

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:

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

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:

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

Send File APIs

The Wickr IO client supports three different ways to send files.

WARNING: please make sure to use the correct API endpoint, since the first two methods use a different endpoint than the third method.

Send Files Residing on the Wickr IO Client

To send files that are directly accessible by the Wickr IO client you will send an HTTP POST message to the following URI:

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

The body content of the request will be of "application/json" type, and will contain a list of users to send the file to, the file path name where the file is located and a display name for the file. The following is an example of sending a file to a single user, where the file is located on the Wickr IO system:

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

In this example, the file to be sent is already on the Wickr IO 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.

Send Files Referenced by a URL

To send files using a URL that are accessible by the Wickr IO client, you will send an HTTP POST message to the following URI:

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

The Wickr IO 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.

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

You can also send files to secure rooms and group conversations using the vgroupid instead of listing the users to send to. The following is an example of sending the file to a secure room.

{
    "vgroupid" : "Sd740e3077714bcc0020806bc5b318a4ca766f9fe4737e6952a81bf0d9a75407",
    "attachment": {
        "url" : "https://example.com/pictures/picturesent.jpg",
        "displayname" : "PictureSent.jpg"
    }
}
Send Files Passed in the REST API Request

This is a new endpoint for the Web Interface integration as of the v5.60 version.

The send file API is used to send a file to one or more Wickr clients, or a specific room conversation. The previously described send message APIs still work to send files as well. To have a specific Wickr IO client send a message, send an HTTP POST message to the following URI:

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

You can send a file 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 body of this POST request will use the following Key/Value pairs:

KEY Description
attachment This is the actual file being sent.
users This is a JSON list of Wickr user IDs to send a message to. For example: "[ user1, user2, user3 ]". This Key is not used when sending to a secure room or group conversation, use the vgroupid Key when sending to secure room or group conversations. A separate 1on1 message will be sent to each of the users in this list. If you want to send using the "users" key make sure the "vgroupid" key is not in the body.
bor The burn-on-read value to use when sending the message. Optional, will default to the current value set for the conversation.
ttl The time-to-live value to use when sending the message (referred to as Expiration Time in clients). Optional, will default to the current value set for the conversation.
vgroupid The vgroupid to use when sending to a secure room or group conversation. Do NOT use this value when sending to 1on1 conversations using the "users" key.

For those familiar with Postman, the following shows an example body set to send a file to two users:

drawing

Make sure to follow the formatting shown for the "users" value.

WARNING: The content-type of the body is "multipart/form-data", which includes the "attachment" and the "users" or "vgroupid". The "ttl" and "bor" are optional.

Received Message

The Wickr IO client has the capability to receive messages and the Web Interface integration provides several ways to get access to those messages. The messages can be forwarded to another application or retrieved via a REST call. To have received messages forwarded to another application a callback location will need to be set (see the URL Callbacks section). If a callback method is not defined the messages will queue up on the Wickr IO client until they are retrieved. The get received messages API can be used to retrieve the messages.

The format of the messages received will be described in the message format section.

URL Callbacks

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 Wickr IO client you can use a URL like the following:

http://localhost:4100

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

Set URL Callback API

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

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

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

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

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

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:

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

Delete URL Callback

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

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

The client will respond with a success or failure response.

Statistics APIs

Each Wickr IO 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

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:

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

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

{
    "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.

Example curl script to perform a get statistics:

curl -v -k -s -X GET -H "$AUTH" http://10.2.0.1:4001/WickrIO/V1/Apps/123456/Statistics
Clear Statistics API

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 Wickr IO client:

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

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 Wickr IO client is a part of.

Create Secure Room API

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

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

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:

{
    "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 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:

{
    "vgroupid": "S0b503ae14cc896aad758ce48f63ac5fae0adccd78ef18cde82563c63b2c7761"
}

The following is a sample curl script to create a room, the data.json file contains the body of the request. The data.json contents would be something similar to that shown above.

curl -v -k -s -X POST -H "$AUTH" -H "$CONTENT" http://10.2.0.10:4001/WickrIO/V1/Apps/123456/Rooms -d "@data.json"
Get Rooms API

This API will return a list of rooms that are known by the Wickr IO client. The Wickr IO client will only know about rooms that it is a member of. To get a list of rooms send an HTTP GET to the following URI:

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

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

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

The following is sample curl script to retrieve the list of rooms:

curl -v -k -s -X GET -H "$AUTH" http://10.2.0.20:4001/WickrIO/V1/Apps/123456/Rooms
Get Secure Room API

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

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

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

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

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.

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

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

The secure room with the same vGroupID will be deleted. This API is used for both the delete room and the leave room action, the reason argument identifies which action to perform. The default value for the reason argument is the delete action, in which case the reason argument can be omitted.

The following curl script is an example of how to delete a specific room:

curl -v -k -s -X DELETE -H "$AUTH"  http://10.100.8.27:6379/WickrIO/V1/Apps/123456/Rooms/S3947c067fa3edc9b0154e82e9ed1cf39904784f344e5923c4c683f27bed2faf
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 Wickr IO client, then determine which room to leave. Also, saving the vGroupID returned from the create room API can be used as well.

To leave a secure room, send an HTTP DELETE command using the following URI, make sure to specify the reason argument with the value of leave.

https://<host>:<port>/WickrIO/V1/Apps/<API Key>/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:

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

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

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:

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

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.

Create Group Conversation API

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

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

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.

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

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:

{
    "vgroupid": "S0b503ae14cc896aad758ce48f63ac5fae0adccd78ef18cde82563c63b2c7761"
}
Get Group Conversations API

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

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

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

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

To get the details of a specific group conversation, send a HTTP GET command using the following URI with the vGroupID of the specific group conversation:

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

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

{
    "rooms": [
        {
            "members": [
                { "name" : "username001" },
                { "name" : "username002" }
            ],
            "vgroupid": "S00bf0ca3169bb9e7c3eba13b767bd10fcc8f41a3e34e5c54dab8bflkjdfde"
        }
    ]
}
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 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.

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

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

The group conversation with the same vGroupID will be deleted.

ZenDesk Integration

Use this bot to handle customer support and automatically create Zendesk tickets for users, all without leaving Wickr's secure messaging platform. Just plug in your Zendesk account info and the bot will pull all the fields and questions required to submit a Ticket from the pre-configured Zendesk account and will prompt the user to enter them. Once the user confirms the information he entered the bots will submit the ticket to Zendesk.

Usage:

Message the bot and it will initiate a ticket creation process based on your responses.

Requirements:

If you are the admin and setting up this bot, you need to have the following information:

Required tokens:

Configuration:

  1. Go into your ZenDesk account and on the left side menu bar select the settings icon
  2. Scroll down and find the "Channels" section, then select "API"
  3. Create a new Active API Token under the "Token Access" section
  4. Save the API token

Developing Integrations

This section describes how you can create your own Wickr IO integration and install it on a running Wickr IO Integration Gateway. Wickr IO integrations are written using Node.js. As mentioned earlier, an optional REST API is provided to support non-Node.js integrations as well as integrations with remote systems. The REST API is provided by the Wickr IO Web Interface integration.

Integration software interacts with the Wickr IO client in several ways. The main interaction is the runtime interaction where the integration communicates with the Wickr IO client through the Wickr IO 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. The Wickr IO Bot APIs also provide higher-level capabilities that will make developing Wickr IO Integration software easier.

drawing

The image above depicts the Wickr IO Gateway software architecture, including the integration software components. The Wickr IO integration software includes software components that perform the actual integration/bot functionality, and a set of software scripts used to maintain the integration. Later in this document we will define these required scripts that an integration must support in order for it to operate successfully on the Wickr IO Integration Gateway.

Setup

To get started with modifying an existing integration or creating your own, you would need to go into the installed client's integration app folder:

NOTE: Keep in mind that this all happens inside a Docker container, and you already have Node.JS and NPM installed in the containers environment.

Integration Runtime

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 “wickrio-example-app” package contains the appropriate entry in the “dependencies” list. Also, to make developing an integration easier and better you should include the Wickrio Bot API package which has functions that will help manage the bot and it's user database. To enable a user database saving and persistence, set the "database" property in the file to true, just like in the following example (NOTE: Version numbers may be different due to software updates):

{
  "name": "wickrio-example-app",
  "version": "5.92.2",
  "description": "WickrIO Node.js API example app",
  "main": "example-app.js",
  "dependencies": {
    "prompt": "^1.3.0",
    "wickrio-bot-api": "5.87.x"
  },
  "scripts": {
    "start": "forever start -m 5 ./forever.json",
    "stop": "forever stop wickrio-example-app",
    "restart": "forever restart wickrio-example-app"
  },
  "repository": {
    "type": "git",
    "url": "https://github.com/WickrInc/wickrio-example-app"
  },
  "keywords": [
    "wickr",
    "wickrio",
    "wickrbot",
    "bot",
    "bots",
    "secure",
    "messaging",
    "api"
  ],
  "database": true
}

In this specific package.json you see the scripts to start and stop the integration use the the forever software. Here is an example of the "processes.json" file for the "wickrio-example-app" integration:

{
  "apps": [
    {
      "name": "WickrIO-Example-App_me-test2-bot",
      "args": [],
      "script": "node example-app.js",
      "exec_interpreter": "none",
      "autorestart": false,
      "watch": [
        "package.json"
      ],
      "ignore_watch": [
        ".git"
      ],
      "env": {
        "tokens": {
          "BOT_USERNAME": {
            "value": "me-test2-bot",
            "encrypted": false
          }
        }
      },
      "out_file": "log.output",
      "error_file": "err.output"
    }
  ]
}```

This is a fairly basic example of the "processes.json" file. Some integrations have many tokens and values which will be placed in the "env.tokens" area of the file.  The "out_file" and "error_file" are used to identify files where normal and error output is saved, respectively.

To use the Wickr IO addon APIs 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:

<div class="center-column"></div>

var addon = require('wickrio_addon'); ```

With this statement you will now have access to the Wickr IO Node.js addon API, which is fully documented in the next section of this document.

The WickrIO Bot API adds some higher-level functionality that will make your integrations easier to develop. Details of this API will be discussed later. To use the Wickr IUO Bot API in your integration insert the following require() statement in your JavaScript code:

var botapi = require('wickrio-bot-api');

Node.js Addon API

This section describes the Wickr IO Node.js addon and how to use it with several examples. The APIs provided by the Wickr IO Node.js addon a low-level APIs, using the APIs provided by the Wickr IO Bot API provide a higher-level approach to some of the main aspects of an Wickr IO integration interfacing with a Wickr IO client. You will still need to use the Wickr IO Node.js addon to perform most interactions with the Wickr IO client. The APIs supported by the Wickr IO Node.js addon allow you to access all of the necessary functionality from the Wickr IO client to communicate with other Wickr users within the Wickr network.

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 the Wickr IO REST API.

When using the Wickr IO Node.js addon you will have access to one Wickr IO client at a time. It is not currently possible for an integration to communicate with more than one Wickr IO client at the same time via the addon. Interaction with the Node.js is as follows:

  1. Initialize the Wickr IO Node.js addon interface. This is done by calling the clientInit() API, and supplying the user name of the Wickr IO client that is going to be used. The start() API provided by the Wickr IO Bot API uses the clientInit() API to initiate a connection to the Wickr IO client. We recommend using that API instead.
  2. Interact with the Wickr IO client by calling the appropriate APIs.
  3. When your program is complete then call the closeClient() API to gracefully stop processing. The close() API, provided by the Wickr IO Bot API, uses the closeClient() API to shut down the connection to the Wickr IO client.

The addon APIs are described in detail in the following sections.

Startup and Shutdown APIs

This section describes the APIs used to start and stop the connection between the Wickr IO integration and the Wickr IO client.

The interface between the Wickr IO integration and the Wickr IO client needs to be initialized. Initialization includes identifying the Wickr IO client and making sure the Wickr IO client is in the appropriate state, for example running and logged into the Wickr network. Once the interface between the client and the integration has been initialized you can start using the other Wickr IO Node.js addon APIs. Also, the interface should be gracefully shutdown when you are done using the APIs.

NOTE: Using the Wickr IO Bot API provides a higher-level API (start()) that will call the appropriate APIs in this addon.

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.

NOTE: If you use the Wickr IO Bot API, the call to the start() API will call the clientInit() API.

closeClient()

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

NOTE: If you use the Wickr IO Bot API, the call to the close() API will call the closeClient() API.

isConnected(int seconds)

The isConnect() API checks if there is a valid connection from the calling Wickr IO integration to the Wickr IO client. The call will wait the input number of seconds for a connection. The API returns true if a response was received from the client within the amount of seconds input, otherwise it will return false.

WARNING: If true is returned it does not mean the client is prepared to handle other requests yet. Use the getClientState() API to make sure the client is in the appropriate state. For most APIs the client should be in the RUNNING state.

NOTE: The Wickr IO Bot API's start() API uses this API to make sure the connection to the client exists.

getClientState()

This API retrieves the current state of the Wickr IO client the integration is connected with. The value returned is one of the following possible values:

It is important to make sure the Wickr IO client is in the RUNNING state before performing any API calls that require access to the Wickr network. Doing so before then may have unpredictable results.

NOTE: The Wickr IO Bot API's start() API uses this API repetitively to make sure the client is in the RUNNING state before returning.

Configuration API

The configuration API is used by the integration to configure specific Wickr IO client modes of operation. Since the Wickr IO client is a separate software module this API will provide a method to modify how the client operates. Typically, the use of these APIs is done after the interface to the Wickr IO client has been initialized.

cmdSetControl(string configKey, string configValue)

This API will tell the Wickr IO client to set the specific configKey to the input configValue. You will have to make a call to cmdSetControl() for each configKey value that is being set. The following is a list of configKey values that can be set:

Config Key Description
attachLifeMinutes This is a number that represents the number of minutes an attachment (file) will remain on the Wickr IO client. After that amount of time the attachment will be removed. A value of 0 will keep attachments on the system indefinitely, this is the default value. It is highly recommended that this value is set to something other than 0.
doreceive If set to 'false' the Wickr IO client will NOT forward incoming Wickr messages to the integration software. This is useful for transmit only integrations. The default value is 'true'.
duration This value is used to make the Wickr IO client and integration to perform a restart after a number of seconds. A value of 0 will not perform a restart. This value is helpful for testing, or if you wish to perform periodic restarts. The default value is '0'.

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()

This API will return a list of messaging and error statistics, for example.

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

The following table describes each of the statistics that can be returned by this API:

Statistics Description
message_count The number of received messages that are currently queued to a conversation on the Wickr IO client. These queues feed into the main receive queue that is used by the message callback and retrieval APIs.
outbox_sync The number of outbox sync messages received. Outbox sync messages are messages that were sent by another device for this Wickr IO client. This is only valid when there are multiple devices configured for a Wickr IO client, which is not typical.
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 sent to a callback process. This number will be decremented for each message that is retrieved from the Wickr IO client using the cmdGetReceivedMessage() API or received by the integration software successfully via the asynchronous message handling (i.e. callback).
pending_messages The number of messages that are currently queued to be sent from the Wickr IO client to Wickr clients on the Wickr network.
received The number of messages that the Wickr IO client has received.
recv_errors The number of errors that occurred while receiving messages.
sent The number of messages that have been sent by the Wickr IO client.
sent_errors The number of errors that have occurred while trying to send messages.

cmdClearStatistics()

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

Wickr Client APIs

This section describes APIs that provide information about Wickr Clients. You can use these APIs to get information about a Wickr client that the bot can communicate with.

cmdGetUserInfo(string users[])

This API returns information about the each of the users from the input array of Wickr user IDs. The value returned is a JSON object with two arrays, one for the Wickr users that exist and one for the Wickr users that do not exist. The following is an example of the JSON returned:

{
    "users" : [
        { "name" : "bobsmith@company.com", "full_name" : "Bob Smith", "is_bot", false" },
        { "name" : "joebrown@companuy.com", "full_name" : "Joe Brown", "is_bot", false" }
        ],
    "failed" : [ "failedUser1", "failedUser2" ]
}

WARNING: This API requires interaction with the Wickr server, so keep the number of users on the input list small so the response does not take too long.

cmdGetClientInfo()

This API will retrieve the bot client information. The values are returned in a JSON list of objects.

{
    "version" : "<bot client's version>",
    "organization" : "Wickr, Inc."
}

This API can be used to verify the version of the client.

cmdSetVerificationMode(string mode)

This API is used to set the verification mode that the bot client will operate under. The possible values for the input mode are "automatic" or "manual", all other values will return an error. If the verification mode is set to "automatic" then any client the bot client interacts with becomes unverified, the bot client will automatically put that client into the verified state. If the verification mode is set to "manual" then it is up to the bot integration to peridically get the verification list, using the "cmdGetVerificationList" API and then calling the "cmdVerifyUsers" or "cmdVerifyAllUsers" APIs.

cmdGetVerificationList(string mode)

This API will return a list of users that have become unverified. The mode argument is optional. Normally, this API will return users that have a failed verification status. When you call this function with a mode value of "all" then this API will return users that are not verified, meaning they can have a verification status of failed, unverified or pending. The value returned will be a JSON string with a list of users and their verification status. These verification functions are necessary when verification is done manually but the bot integration.

The following is a sample response:

{
    "users" : [
        { "user": "wickrID1", "reason": "failed" },
        { "user": "wickrID2", "reason": "unverified" },
        { "user": "wickrID3", "reason": "pending" }
    ]
}

cmdVerifyUsers(string users[])

This API will verify all of the users in the input users array. The verification status for each of these users will be changed to verified. You will only need to use this API if your bot was setup to do verification manually.

cmdVerifyAll()

This API will verify all users that are in the unverified or failed verification state. This will only be necessary if the bot is doing verification manually.

Secure Room Conversation APIs

This section describes the APIs that perform operations on Wickr secure rooms. The operations you can perform include adding, modifying, deleting and retrieving secure rooms. For APIs where you are dealing with a specific secure room, you will need to have the VGroupID that is associated with that room.

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

This API creates a new secure room. The arguments of this request will contain the information associated with the room.

The members and moderators arguments are arrays of strings, that are Wickr IDs. The members array is the complete list of members of the secure room. The moderators array is a list of the moderators of the secure room. The moderators must also be in the members list. There must be at least one moderator in the room.

The ttl is the time to live value. The bor is the burn on read value. These values are strings but the contents of the string is a number. The ttl and bor values are optional. If the bor value is included then the ttl value must also be included.

{
    "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 room.

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 add room API can be used as well.

cmdGetRoom(string vgroupid)

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.

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

cmdGetRooms()

This API will return a list of secure rooms that are known by the Wickr IO client. The Wickr IO client will respond with a JSON array of the secure rooms that the Wickr IO client is a member of. The following is an example of what the JSON returned from this API:

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

cmdLeaveRoom(string vgroupid)

This API will instruct the Wickr IO client to leave the secure room identified by the input 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.

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:

The Wickr IO client must be a moderator for the room identified by the input vGroupID, otherwise the request will fail.

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 Wickr IO client is a part of.

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

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.

{
    "vgroupid": "G0b503ae14cc896aad758ce48f63ac5fae0adccd78ef18cde82563c63b2c7761"
}

cmdDeleteGroupConvo(string vgroupid)

This API will instruct the Wickr IO client to leave a group conversation. You can only actually delete a group conversation if the client is the last member of the group conversation.

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.

cmdGetGroupConvos()

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.

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

cmdGetGroupConvo(string vgroupid)

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.

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

Receive Message APIs

These messaging APIs are used to retrieve Wickr messages received by the Wickr IO client. Messages received by the Wickr IO client can be retrieved using one of the following methods:

The Wickr IO APIs will only support one receive message method at a time. When a message has successfully been transferred from the Wickr IO client to the integration software that message will be removed from the Wickr IO client queue. The Wickr IO client will not save messages after completion of the transfer.

The format of the messages received is described in the message format section.

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 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 message 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. When using this method of receiving messages be careful to make sure the software running on the Wickr IO Docker image can access the URL.

cmdGetMsgCallback()

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.

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

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.

Transmit Message Arguments

There are several arguments to the transmit APIs that need more detailed descriptions.

Message Meta Arguments

New to the 5.81 version of WickrIO, is the support for button and table GUI widgets. These GUI widgets are only supported in text messages, file messages do not support them. The transmit APIs have been modified to support an optional argument (messagemeta) that identifies these buttons or tables. The messagemeta argument is a JSON string that identifies the GUI elements associated with the message being transmitted. The following figure shows the JSON associated with two buttons, one is a normal message button and the other is a location button:

{
    "buttons" : [
        {
            "type": "message",
            "text": "Button Text",
            "message": "/action"
        },
        {
            "type": "getlocation",
            "text": "Send Location"
        }
    ]
}

The "type" object identifies the type of the button, and the "text" identifies the text that will be displayed on the button to the user. The "message" object of the message button is what the client will send back to the bot when the button is selected. The "getlocation" type of button, when selected the client will send the client's location to the bot.

The table GUI widget is used to display a selectable list of information on the client. The messagemeta JSON string can contain a "table" object and a "textcut" object. The "textcut" object is optional. The "table" object contains all the details of the table to be shown. The "textcut" object contains a list of values that indicate which characters in the message text should be cut if the client supports the table GUI widget. Normally, if a client does not support the table GUI widgets it will just display the message text. If the client does support the table GUI widgets it will display the message text, minus the text referenced by the "textcut" values, and then the list GUI. The following is a sample.

{
    "table" : {
        "name": "Table heading",
        "firstcolname": "Column 1",
        "secondcolname": "Column 2",
        "actioncolname": "Action",
        "rows": [
            {
                "firstcolvalue": "123",
                "secondcolvalue": "Hello",
                "response": "1"
            },
            {
                "firstcolvalue": "2838",
                "secondcolvalue": "There",
                "response": "2"
            }
        ]
    },
    "textcut" : [
        { "startindex": 0, "endindex": 75 }
    ]
}

The sample above shows all of the possible objects associated with the "table" and "textcut" objects. The "textcut" array is optional. The "secondcolname" and "secondcolvalue" objects are optional. The table can have one or two columns.

To include buttons or lists in your text messages you will create a JSON string and that wil be the messagemeta argument to the message sending APIs (shown below). The following is an example of the Javascript code for creating the messagemeta string for some buttons. When the button is selected the 'message' value will be sent to the bot.

const messagemeta = {
    buttons: [
        {
            type: 'message',
            text: 'yes',
            message: 'yes',
        },
        {
            type: 'message',
            text: 'no',
            message: 'no',
        }
    ],
}
const messagemetastring = JSON.stringify(messagemeta)

The following is an example Javascript for creating the message meta string for a list. The action column contains the value that will be returned to the bot when that item is selected. In this case it will be the number '1', '2' or '3'.

const users = [ 'user1@somewhere.com', 'user2@somewhere.com', 'user3@somewhere.com' ]

let messagemeta = {
    table: {
        name: 'List of Users',
        firstcolname: 'User',
        actioncolname: 'Select',
        rows: [],
    },
    textcut: [
        {
            startindex: 0,
            endindex: entriesString.length - 1,
        },
    ],
}

for (let i = 0; i < users.length; i++) {
    const response = i + 1
    const row = {
        firstcolvalue: users[i],
        response: response.toString(),
    }
    messagemeta.table.rows.push(row)
}

const messagemetastring = JSON.stringify(messagemeta)

Message ID Arguments

The messageID argument for the transmit functions is used to track the status of transmits. Bot integrations like the broadcast bot use the messageID values to track the process of a broadcast. The messageID can be used later to retrieve the status of the transmission of all messages associated with that messageID value.

Flags Arguments

The flags arguments to the transmit functions is not fully defined. It will be defined in a future document.

Transmit Message APIs

The transmit message APIs support transmitting normal messages as well as files. Messages and files will be transmitted to specific 1-on-1, secure room, or group conversations on the Wickr network via the Wickr IO client. For secure rooms and group conversations you will need to have the vGroupID associated with the specific conversation.

Some of the arguments to these functions are optional. Required arguments will always be listed first in the function definitions. The order of the arguments must follow the defined function signature. If you are going to use an optional argument that is after one you are not going to use then you will have to pass an appropriate value for the optional argument you are not using (i.e. "" for string arguments, [] for array arguments).

cmdSend1to1Message(string users[], string message, string ttl, string bor, string messageID, string flags[], string messagemeta)

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 API request "users" field contains 5 users then 5 messages will be sent, using the text from the "message" field.

The users array and message arguments are required, the remaining arguments are optional.

cmdSendRoomMessage(string vgroupid, string message, string ttl, string bor, string messageID, string flags[], string messagemeta)

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.

The vgroupid and message arguments are required, the remaining arguments are optional.

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

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 or a URL that identifies a remotely accessible file. If this is a local file, the file must be located in a location on the client that is accessible by the bot's client software running on the Wickr IO Docker image. The displayname field will be sent in the file transfer message.

The users array and filename arguments are required, the remaining arguments are optional.

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

This API is used to send a file to a secure room or group conversation. The file will be sent to the conversation associated with the input vgroupid. The filename identifies a file that is located on the client system or a URL that identifies a remotely accessible file. If this is a local file, the file must be located in a location on the client that is accessible by the bot's client software running on the Wickr IO Docker image. The displayname field will be sent in the file transfer message.

The vgroupid and filename arguments are required, the remaining arguments are optional.

cmdSendMessageUserNameFile(string fileName, string message, string ttl, string bor, string messageID, string flags[], string messagemeta)

This API is used to send a message to a list of Wickr clients contained in the input file. The "fileName" contains the full pathname of a file that is readable by the WickrIO bot. The file contains a list of Wickr users, one per line in the file. The input message will be sent to each user on a separate 1-to-1 conversation. So, if the API request "fileName" file contains 5 users then 5 messages will be sent, using the text from the "message" field.

The fileName and message arguments are required, the remaining arguments are optional.

cmdSendAttachmentUserNameFile(string fileName, string attachment, string displayname, string ttl, string bor, string messageID, string messagemeta)

This API is used to send a file to a list of Wickr clients contained in the input file. The "fileName" contains the full pathname of a file that is readable by the WickrIO bot. The file contains a list of Wickr users, one per line in the file. The input file identified by the "attachment" will be sent to each user on a separate 1-to-1 conversation. So, if the API request "fileName" file contains 5 users then 5 messages will be sent, using the file from the "attachment" field.

The fileName and attachment arguments are required, the remaining arguments are optional.

Network and Security Group Message APIs

These APIs are used to send messages and files to the users in a Wickr network or security group. Since Wickr bots can only transmit to clients in the same network, the Wickr network is the network that the bot is in. The Wickr bot can transmit to any of the security groups that are associated with the network it is associated with.

cmdSendNetworkMessage(string message, string ttl, string bor, string messageID, string flags[], string messagemeta)

This API is used to send a message to all of the Wickr clients in the bot client's Wickr network. The message will be sent to each user on a separate 1-to-1 conversation. So, if the associated network contains 100 users then 100 messages will be sent, using the text from the "message" field.

The message argument is required, the remaining arguments are optional.

cmdSendNetworkAttachment(string filename, string displayname, string ttl, string bor, string messageID, string message, string messagemeta)

This API is used to send a file to all of the Wickr clients in the bot client's Wickr network. The file will be sent to each of the users in the Wickr network via individual 1-to-1 conversations. The filename identifies a file that is located on the client system or a URL that identifies a remotely accessible file. If this is a local file, the file must be located in a location on the client that is accessible by the bot's client software running on the Wickr IO Docker image. The displayname field will be sent in the file transfer message.

The message field is used to also transmit a message, in addition to sending the attachment.

The filename argument is required, the remaining arguments are optional.

cmdSendNetworkVoiceMemo(string filename, string displayname, string ttl, string bor, string messageID, string message, string messagemeta)

This API is used to send a voice memo to all of the Wickr clients in the bot client's Wickr network. The voice memo will be sent to each of the users in the Wickr network via individual 1-to-1 conversations. The filename identifies a voice memo file that is located on the client system, this file must be located in a location on the client that is accessible by the bot's client software running on the Wickr IO Docker image. The displayname field will be sent in the file transfer message.

The message field is used to also transmit a message, in addition to sending the attachment.

The filename argument is required, the remaining arguments are optional.

cmdGetSecurityGroups(string page, string size)

This API will return a list of information for the Security Groups that are associated with the Wickr network the bot client is in. The page and size values are used to iterate through a large list of security groups. The page identifies which page of security groups to retrieve, where each page contains size number of entries. The page and size input values are optional but if specified they both have to be specified.

The value returned is a JSON array containing the following entries:

{
  "size" : <size of security group>,
  "name" : "<security group name>",
  "id" : "<security group ID>"
}

The "size" value is the number of users that are in the security group. The "name" is the actual name of the security group. The "id" is a unique identifier for the security group. The "id" value is used in the following APIs to send to security groups users.

cmdSendSecurityGroupMessage(string message, string groupids[], string ttl, string bor, string messageID, string flags[], string messagemeta)

This API is used to send a message to all of the Wickr clients in the security groups identified by the groupids value. The message will be sent to each user on a separate 1-to-1 conversation. So, if the associated security groups contain 100 users then 100 messages will be sent, using the text from the "message" field.

The message and groupids arguments are required, the remaining arguments are optional.

cmdSendSecurityGroupAttachment(string groupids[], string fileName, string displayname, string ttl, string bor, string messageID, string message, string messagemeta)

This API is used to send a file to all of the Wickr clients in the security groups identified by the groupids value. The file will be sent to each of the users via individual 1-to-1 conversations. The filename identifies a file that is located on the client system or a URL that identifies a remotely accessible file. If this is a local file, the file must be located in a location on the client that is accessible by the bot's client software running on the Wickr IO Docker image. The displayname field will be sent in the file transfer message.

The message field is used to also transmit a message, in addition to sending the attachment.

The groupids and fileName arguments are required, the remaining arguments are optional.

cmdSendSecurityGroupVoiceMemo(string groupids[], string fileName, string displayname, string ttl, string bor, string messageID, string message, string messagemeta)

This API is used to send a voice memo to all of the Wickr clients in the security groups identified by the groupids value. The voice memo will be sent to each of the users via individual 1-to-1 conversations. The filename identifies a voice memo file that is located on the client system, this file must be located in a location on the client that is accessible by the bot's client software running on the Wickr IO Docker image. The displayname field will be sent in the file transfer message.

The message field is used to also transmit a message, in addition to sending the attachment.

The groupids and fileName arguments are required, the remaining arguments are optional.

Message Status APIs

These APIs are available to the bulk send APIs of the Wickr IO bot (i.e. network and security sending, file name list sending). The APIs will provide the ability to track the number of messages sent and remaining to be sent as well as if errors have occured during the sending of any of the messages. Errors will be identified on a per user basis as well, which can help determine if there was a problem sending to specific Wickr users.

cmdAddMessageID(string messageid, string sender, string target, string datesent, string message)

Before sending a message that you want to track you will need to call this API to add the message ID information to the Wickr IO client. This API is used to add a message ID entry to the Wickr IO clients database. The key part of this API is the message ID, it MUST be unique. The other values are determined by the integration using this API.

The messageid value should uniquely identify the message being sent.

The sender is a string that should be used to identify the sender of the message. The contents of this value is up to the integration using it. It can be used to restrict access to the message ID information, so that users interacting with your integration cannot see message information for other users.

The target is a string that should be used to identify who the message(s) are being sent to. The contents of this value is up to the integration using it. The intent is to determine what type of message was being sent.

The datesent is used to identify the date and time when the message was sent. The contents of this value is up to the integration using it.

The message value is used to save the actual message or a string that identifies to the users the message that was sent.

cmdDeleteMessageID(string messageid)

This API will delete all entries in the Wickr bot's client database associated with the input message ID value.

cmdGetMessageIDEntry(string messageid)

This API will retrieve the information associated with the input message ID value. The value returned is a JSON object with the following format:

{
  "message_id" : "<message ID value>",
  "sender"     : "<sender value>",
  "target"     : "<target value>",
  "when_sent"  : "<when sent value>",
  "message"    : "<message value>"
}

cmdGetMessageIDTable(string page, string size)

This API is used to retrieve all of the message ID entries from the Wickr bot client's database. Since this table can get very large over time you will need to limit the number of entries retrieved by using the page and size values. The page is a 0 relative value used to identify which page to retrieve, where each page contains a number of entries equal to the size value. If the table is large enough you will need to iterate through each page until the number of entries is less than the size value. The return value from this API is a JSON array of the message ID objects, as shown in the cmdGetMessageIDEntry() API above.

cmdCancelMessageID(string messageID)

This API is used to cancel the transmit associated with the input messageID value. The bot client will attempt to stop the transmission. There is no guarantee that the transmit will be fully cancelled, but any subsequent transmits associated with the messageID should not occur.

cmdGetMessageStatus(string messageid, string type, string page, string size)

This API is used to retrieve the status of a specific message, identified by the input messageid value. The type value identifies what type of information should be returned. There are two types of message status values that can be returned:

The type value is optional, if not specified the default is to return a "summary" status of the associated message transmission. If the status to be returned is a "summary" then the following JSON object will be returned:

{
  "num2send" : <number of users to send to>,
  "pending"  : <number pending to send>,
  "sent"     : <number sent>,
  "failed"   : <number failed to send>,
  "acked"    : <number acked by receiver>
}

The values returned are all numbers. The "acked" value is the number of users that have responded to the bot. NOTE: a user sending a message to the bot will acknowledge all message ID entries associated with that user. This behavior will change in future versions.

If the type value is "full" then an array of values is returned, one for each user that the message is targeted to. The JSON array returned will contain objects with the following format:

{
  "user"           : "<user ID>",
  "status"         : <status of message to user>,
  "status_message" : "<error status if any>"
}

The "user" value is the user name that the message will be sent to. The "status" value is a number value that identifies the status of the message that is being sent to the "user". The "status" can have a value of one of the following:

If the "status" value returned for a user is a failed (3) then the "status_message" value will also be returned, otherwise the "status_message" value will not be returned.

The page and size input values are optional but should be used if the number of users the message is sent to is large. The page is a 0 relative value used to identify which page to retrieve, where each page contains a number of entries equal to the size value. If the table is large enough you will need to iterate through each page until the number of entries is less than the size value.

cmdSetMessageStatus(string messageid, string user, string status, string statusmessage)

This API can be used to modify the status and status message associated with a specific user's message status. The statusmessage value is optional. The messageid and user value will uniquely identify a message ID entry in the Wickr bot client's database. If there is no entry for the associated message ID and user then an entry will be created in the database.

The messageid value can have an empty string value (i.e. ""), which can be used to update ALL message ID entries for the specified user. This can be used for example to acknowledge all messages sent to that user. If the messageid value is empty and there are NO user entries for the user then nothing will be added to the database.

Key-Value APIs

These APIs provide the ability to save and retrieve values to/from a persistent encrypted 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.

These APIs do not have any relationship to the Wickr messaging, they are supplied for use by the Wickr IO integrations to have a way to save persistent data.

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.

Node.js Bot API (Development toolkit)

This section describes the Wickr IO Node.js Bot API framework and how to use it with several examples below. This API provides tools for an easier and more efficient development of Wickr IO integration bots. It utilizes the Wickr IO Node.js addon APIs to make it easier to develop integrations.

The Wickr IO Node.js Bot API is published to the default NPM registry. The name of the published module is wickrio-bot-api.

You will need to have a require() statement to include the Wickr Node.js Bot API in your integration. Also, since the Wickr IO addon is required you will need to have a require() statement for it as well. For example:

var addon = require('wickrio_addon');
var botapi = require('wickrio-bot-api');

start(client_username)

This API is used to start the connection with the Wickr IO client and get it ready for use. This API uses the Wickr IO addon clientInit(), isConnected() and getClientState() APIs to make sure the Wickr IO client connection is initialized, there is a valid connection and the client is in the RUNNING state. This is helpful since it may take the Wickr IO bot client longer to initialize than your integration.

If you use this API you will not need to call these addon APIs. This means you don't need to use clientInit() in your code, since calling this function does it for you. Eventually, it checks if the database option was turned on in package.json and proceeds to call encryptEnv() and loadData() accordingly, in order to encrypt user entered environment variables and load up the user database from a previous session, if there is one. NOTE: A DATABASE_ENCRYPTION_KEY will need to be added to the integrations config values in order for this to work

Parameters:

Returns:

This API returns true if successful, else returns false.

Example:

Here is sample code that shows the use of this API. This code is taken from the wickrio-example-app integration.

async function main() {
  try {
    var status;
    if (process.argv[2] === undefined) {
      bot_username = tokens.BOT_USERNAME.value;
      bot = new WickrIOBotAPI.WickrIOBot();
      status = await bot.start(bot_username)
    } else {
      bot = new WickrIOBotAPI.WickrIOBot();
      status = await bot.start(process.argv[2])
    }
    if (!status)
      exitHandler(null, {
        exit: true,
        reason: 'Client not able to start'
      });
    ///////////////////////
    //Start coding below
    ///////////////////////
    await bot.startListening(listen); //Passes a callback function that will receive incoming messages into the bot client
  } catch (err) {
    console.log(err);
  }
}

startListening(callback)

This API initiates the asynchronous reception of received messages from the Wickr IO client. The passed callback function will be called when a message is received by the associated client.

This API replaces the addon's cmdStartAsyncRecvMessages() API call.

Parameters:

Returns:

This API returns true if successful, else returns false.

Example:

Receive Asynchronous Messages

close()

This API will close the currently open connection to the Wickr IO client. This should be called when done interacting with the client set in the “start()” API. If asynchronous received message handling has been initiated it will be stopped. After that the connection to the Wickr IO client will be stopped.

The Wickr IO addon API closeClient() will be called by this API, so you do not need to do that.

Example:

The following example calls the close API in the exitHandler() function. This code was taken from the wickrio-example-app.

async function exitHandler(options, err) {
  var closed = await bot.close();
  console.log(closed);
  if (err) {
    console.log("Exit Error:", err);
    process.exit();
  }
  if (options.exit) {
    process.exit();
  } else if (options.pid) {
    process.kill(process.pid);
  }
}

encryptEnv()

This API encrypts any environment variables that were input in the configuration part and were saved in the processes.json file, environment variable can include app tokens such as 3rd-Party API Tokens(ex: Google App Client ID), or bot client specific variables such as a Bot Client Server.

loadData()

This API reads the encrypted user database from 'users.txt', which is an array of users personal information with their Wickr emails and any other values such as personal access tokens they have saved from 3rd party integrations, then it decrypts it and loads it onto the passed wickrUsers array variable.

Parameters:

None

Returns:

This API returns nothing.

saveData()

Encrypts the user database array contained in the wickrUsers variable, which is an array of users personal information with their Wickr emails and any other values such as personal access tokens they have saved from 3rd party integrations, and saves it to the 'users.txt' file.

Parameters:

None

Returns:

This API returns true if successful, else returns false.

addUser(wickrUser)

This API adds a user to the bot's user database array called wickrUsers, which is an array of users personal information with their Wickr emails and any other values such as personal access tokens they have saved from 3rd party integrations,.

Parameters:

Returns:

This API returns the user object after it is added to the user database.

parseMessage(message)

This API parses and breaks down an incoming received message from the client. If successful the parsed values will be returned in an object.

Parameters:

Returns:

This API returns an object with relevant properties extracted from the message JSON object, such as: message, command, argument, vGroupID, sender's email, convo type. The properties returned a relevant to the type of message that was parsed, for example file messages will return information about the file, voice memo messages will return information about the voice memo and the associated file, location messages will return location information, etc...

var parsedObj = {
    'message': request,     // the actual message
    'command': command,     // the bot command parsed from the message
    'argument': argument,   // arguments for the bot command
    'vgroupid': vGroupID,   // the associated vgroupID
    'userEmail': sender,    // the Wickr ID of the sending user
    'convotype': convoType, // either 'personal', 'groupconvo' or 'room'
    'msgtype': messageType  // either 'message', 'edit', 'keyverify', 'call', 'location', or 'file'
};

Example:

Receive Asynchronous Messages

getUser(userID)

This API searches the user database for the input user ID and returns the WickrUser object if found.

Parameters:

Returns:

This API returns the user object if successful, else returns false.

getUsers()

This API is used to retrieve the entire user database.

Returns:

Returns the bot's user database array.

deleteUser(userID)

Searches the user database for the passed user, deletes the user and returns the WickrUser object if successful, else returns false.

Parameters:

getVersions(packageFile)

This API returns a string that contains the versions associated with all of the main components of the WickrIO environment. This includes the docker tag, bot client version, WickrIO Addon version, WickrIO Bot API version and the integration's version. The docker tag version is only supported in versions 5.81 and newer.

Parameters:

Returns:

This API returns a string that contains all of the version numbers.

Example:

The following is sample output from this API:

Docker Tag: 5.81.13.01
Bot Client: v5.81.3
Integration: 5.81.3
WickrIO Addon: 5.81.1
WickrIO API: 5.81.1

Addon and Bot API usage

This section contains several examples of the use of the Wickr IO addon and the Wickr IO Bot API.

API Initialization

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 “start()” API (from the Wickr IO Bot APIs) and passing the client name associated with the Wickr IO client. For example:

const WickrIOAPI = require('wickrio_addon'); //WickrIO node.js addon which allows talking directly to our api
const WickrIOBotAPI = require('wickrio-bot-api'); //Development toolkit to help create bots/integrations
const WickrUser = WickrIOBotAPI.WickrUser;

var bot, tokens, bot_username, bot_client_port, bot_client_server;
var tokens = JSON.parse(process.env.tokens);

async function main() {
  try {
    bot_username = tokens.BOT_USERNAME.value;
    bot = new WickrIOBotAPI.WickrIOBot();
    var status = await bot.start(bot_username)
    if (!status)
      exitHandler(null, {
        exit: true,
        reason: 'Client not able to start'
      });
  } catch (err) {
    console.log(err);
  }
}

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

Sending message to a room

The following code fragment shows the use of the cmdSendRoomMessage() API to send a message to a specific secure room. Before making the call you will need to get a valid vGroupID.

var msg = "Sorry, I'm not allowed to delete all the files in the directory.";
try {
    var sMessage = WickrIOAPI.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

The following code shows the creation of a secure room and then sending a file to that room:


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 = WickrIOAPI.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 = WickrIOAPI.cmdSendRoomAttachment(vGroupID, attachmentURL, displayname);
    //if successful should print "Sending message"
    console.log(cmd);
} catch(err){
    //Handle errors here
    console.log(err);
}

Receive Asynchronous Messages

There are two types of messaging APIs supported by the Wickr IO Node.js addon:

The following code shows you how to initiate the asynchronous messaging and shows a callback function that will process the incoming messages.

await bot.startListening(listen); //Passes a callback function that will receive incoming messages into the bot client

async function listen(message) {
  try {
    var parsedMessage = bot.parseMessage(message); //Parses an incoming message and returns and object with command, argument, vGroupID and Sender fields
    if (!parsedMessage) {
      return;
    }
    console.log('parsedMessage:', parsedMessage);
    var wickrUser;
    var command = parsedMessage.command;
    var message = parsedMessage.message;
    var argument = parsedMessage.argument;
    var userEmail = parsedMessage.userEmail;
    var vGroupID = parsedMessage.vgroupid;
    var convoType = parsedMessage.convoType;
    var personal_vGroupID = "";
    if (convoType === 'personal')
      personal_vGroupID = vGroupID;
    var location = bot.findUser(userEmail); //Check if a user exists in the database and get his position in the database
    console.log('location:', location)
    if (location === -1) {
      wickrUser = new WickrUser(userEmail, {
        index: 0,
        personal_vGroupID: personal_vGroupID,
        command: "",
        argument: ""
      });
      var added = bot.addUser(wickrUser);
      console.log(added);
    }
    var user = bot.getUser(userEmail);
    user.token = "example_token_A1234";

    //how to determine the command a user sent and handling it
    if (command === '/help') {
      var reply = "What can I help you with?";
      var sMessage = WickrIOAPI.cmdSendRoomMessage(vGroupID, reply); //Respond back to the user or room with a message(using vGroupID)
      var users = [userEmail];
      var sMessage = WickrIOAPI.cmdSend1to1Message(users, reply); //Respond back to the user(using user wickrEmail)
      console.log(sMessage);
    }
  } catch (err) {
    console.log(err);
  }
}

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.

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 "close()" Bot API. This will also stop the asynchronous message receiving for the bot.

process.stdin.resume(); //so the program will not close instantly

async function exitHandler(options, err) {
  var closed = await bot.close();
  console.log(closed);
  if (err) {
    console.log("Exit Error:", err);
    process.exit();
  }
  if (options.exit) {
    process.exit();
  } else if (options.pid) {
    process.kill(process.pid);
  }
}


//catches ctrl+c and stop.sh events
process.on('SIGINT', exitHandler.bind(null, {
  exit: true
}));

// catches "kill pid" (for example: nodemon restart)
process.on('SIGUSR1', exitHandler.bind(null, {
  pid: true
}));
process.on('SIGUSR2', exitHandler.bind(null, {
  pid: true
}));

//catches uncaught exceptions
process.on('uncaughtException', exitHandler.bind(null, {
  exit: true
}));

Loggging API

This section describes the logging module that can be imported from the WickrIOAPI. This logging module allows for different log levels and log file rotations in the bot integrations. Winston logger is used as the logging library and the default log levels are those predefined by NPM and in oder of importance are: error, warn, info, verbose, debug, and silly.

To get started with the logger first import WickrLogger from the wickrio-bot-api library. Then you can access a new logger like so:

const logger = new WickrLogger().getLogger()

If you are currently using console.log as your default logger all instances of console.log can be piped through the logger with this block of code:

console.log = function () { logger.info(util.format.apply(null, arguments)) }

Similarly console.error can be piped through the logger like so:

console.error = function () { logger.error(util.format.apply(null, arguments)) }

The logger will look to the processes.json for the log level, max log file size, and max number of log files. These values can be changed by updating the values of LOG_LEVEL, LOG_FILE_SIZE, and LOG_MAX_FILES in the env section of processes.json.

Without modifying the log_tokens the log level will be set to info, the max file size will be set to 10MB and the max number of log files will be set to 5.

{
  "apps": [
    {
      "name": "WickrIO-Broadcast-Bot",
      "args": [],
      "script": "./build/index.js",
      "exec_interpreter": "node",
      "autorestart": false,
      "watch": ["package.json"],
      "ignore_watch": [".git"],
      "env": {
        "tokens": {}
        "log_tokens":
        {
          "LOG_LEVEL": "debug",
          "LOG_FILE_SIZE": "10m",
          "LOG_MAX_FILES": "5"
        }
      }
    }
  ]
}

Python Bot development

To develop WickrIO integrations in languages other than JavaScript such as Python, you will need to set up a Web REST API Interface integration on your machine and send HTTP/HTTPS requests to it. The following examples show how to do it in python:

Set up your python app:

import requests
import json
URL = "http://localhost:4001/WickrIO/V1/Apps/CLIENT_API_KEY"
PARAMS = {'Accept': '*/*', 'Content-Type': 'application/json',
          'Authorization': 'Basic AUTH_KEY'}

Send 1-to-1 Message

data = {
    "message": "Welcome to Wickr! This message will self-destruct eventually.",
    "users": [
        {"name": "exampleuser@wickr.com"}
    ]
}
sendMessage = requests.post(URL + "/Messages",
                            headers=PARAMS,
                            data=json.dumps(data))
print(sendMessage.content)

Add Room

data = {
    "room": {
        "title": "Security Group room for Sports in Bot Testing Network",
        "description": "Security Group room for Sports in Bot Testing Network",
        "ttl": "25536000",
        "bor": "0",
        "members": [
            {"name": "wickruser1@wickr.com"},
            {"name": "wickruser2@wickr.com"}
        ],
        "masters": [
            {"name": "wickruser1@wickr.com"}
        ]
    }
}
AddRoom = requests.post(URL + "/Rooms",
                        headers=PARAMS,
                        data=json.dumps(data))
json_data = json.loads(AddRoom.text)
room = json_data['vgroupid']
print(room)

Send Room message

data = {
    "message": "Welcome to Wickr! This message will self-destruct eventually.",
    "vgroupid": "examplevgroupid"
}
sendMessage = requests.post(URL + "/Messages",
                            headers=PARAMS,
                            data=json.dumps(data))
print(sendMessage.content)

Get Statistics

getStatistics = requests.get(URL + "/Statistics",
                             headers=PARAMS)
print(getStatistics.json())

Delete Statistics

deleteStatistics = requests.delete(URL + "/Statistics",
                                   headers=PARAMS)
print(deleteStatistics.content)

Get Room

payload = {
    'vgroupid': room}
getRoom = requests.get(URL + "/Rooms/{0}".format(room),
                             headers=PARAMS)
print(getRoom.json())

Modify Room

data = {
        "title": "Modified room",
        "description": "Testing ModifyRoom command",
        "ttl": "25536000",
        "bor": "0"
}
modifyRoom = requests.post(URL + "/Rooms/{0}".format(room),
                           headers=PARAMS,
                           data=json.dumps(data))
print(modifyRoom.content)

Add Group Convo

data = {
    "groupconvo": {
        "members": [
            {"name": "exampleuser@wickr.com"},
            {"name": "exampleuser02@wickr.com"}
        ]
    }
}
AddGroupConvo = requests.post(URL + "/GroupConvo",
                              headers=PARAMS,
                              data=json.dumps(data))
print(AddGroupConvo.content)
response = json.loads(AddGroupConvo.text)
print(response['vgroupid'])
groupConvo = response['vgroupid']
print(groupConvo)

Get Group Convos(All)

getGroupConvos = requests.get(URL + "/GroupConvo",
                              headers=PARAMS)
print(getGroupConvos.json())

Get Group Convo(One)

getGroupConvo = requests.get(URL + "/GroupConvo/{0}".format(groupConvo),
                             headers=PARAMS)
print(getGroupConvo.json())

Delete Group Convo(One)

payload = groupConvo  # double check this
deleteGroupConvo = requests.delete(URL + "/GroupConvo/{0}".format(groupConvo),
                                   headers=PARAMS)
print(deleteGroupConvo.content)

Get Message

getMessage = requests.get(URL + "/Messages",
                          headers=PARAMS)
print(getMessage.json())

Set MsgRecvCallback

payload = {'callbackurl': 'http://localhost:8080/apps/callback'}
setMsgRecvCallback = requests.post(URL + "/MsgRecvCallback",
                                   headers=PARAMS,
                                   params=payload)
print(setMsgRecvCallback.content)

Get MsgRecvCallback

getMsgRecvCallback = requests.get(URL + "/MsgRecvCallback",
                                  headers=PARAMS)
print(getMsgRecvCallback.content)

Delete MsgRecvCallback

deleteMsgRecvCallback = requests.delete(URL + "/MsgRecvCallback",
                                        headers=PARAMS)
print(deleteMsgRecvCallback.content)

Integration Setup and Configuration

Before you can get to the run time operation of a Wickr IO integration the integration software 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. These specifications identify how components of your integrations interact with the Wickr IO Gateway services and command line interface components.

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 is very simply done by making it public on the NPM registry.

Integration Software Components

Aside from the main integration software module, each Wickr IO integration will have several software components that are required for the integration to work within the Wickr IO Integration Gateway. The integration software will have software modules (usually shell scripts) to support the following interactions with the Wickr IO control software:

Each of these interactions will require the integration software to contain specific scripts or other capabilities. These scripts will be called directly from the Wickr IO command line interface module during the addition, starting and stopping of a Wickr IO client. The following sections will describe each one of these.

Integration Software Download

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.

This will download and install all of the required dependencies onto the Wickr IO Gateway system. For example, the files specific to the “my-wickrio-integration” will be placed in the integration directory location associated with the Wickr IO client the integration is to interact with. So for example if the Wickr IO client was "my_bot" the location would be "/opt/WickrIO/clients/my_bot/integration/my-wickrio-integration".

You can also clone an integration straight from our GitHubo repo and replace the files in your installed integrations folder location (usually at /opt/WickrIO/clients/my_bot/integration/my-wickrio-integration) with the ones from the cloned package.

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:

{
  "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": "5.87.x"
  },
  "scripts": {
    "start": "node my_wickrio_integration.js",
    "stop": "pkill --signal SIGINT fileBot"
  }
}

For the software download requirement, the “wickrio_addon” must be in the “dependencies” list. Note, the version numbers identified in this document may not be accurate.

Integration Installation

After a Wickr IO integration has been downloaded there may be some other installation steps necessary. The integration must contain an install.sh executable script. The Wickr IO system will run this script after the software has been downloaded.

If you do not have any installation steps to perform then just supply an empty install.sh file. The script should be executable.

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 to 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 command line interface will run the configure.sh script during the configuration phase of installing a client. The configure.sh file will also be run when upgrading or modifying an integration.

The Wickr IO command line interface interacts with the configure.sh script to prompt the user for input. Any output from the configure.sh script 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 process these values. Processing may be saving the value 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

In this example the script echoes the "prompt: Please enter your client username:" string. Then it performs a "read input" statement to get the input passed to it from the Wickr IO command line interface. In this case the value input by the user is output to the "client_bot_username.txt" file.

The Wickr IO Node.js addon has APIs to save and retrieve type value pairs, but the APIs is only available when the client is running, which is not true during the install and configuration process. 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.

As of the 5.47 version of the Wickr IO docker image, it may be necessary to specify which version of node you want your integration to run with. The 5.47 version of the docker image contains node versions 8 and 10. If you want to use the node 8 version for your integration you should have a start.sh that looks like the following:

#!/bin/bash
if [ -f "/usr/local/nvm/nvm.sh" ]; then
  . /usr/local/nvm/nvm.sh
  nvm use 8.17.0
fi
npm start

If you want to use the node 10 version then you should have a start.sh file that looks like the following:

#!/bin/bash
if [ -f "/usr/local/nvm/nvm.sh" ]; then
  . /usr/local/nvm/nvm.sh
  nvm use 10.18.1
fi
npm start

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 stop the integration, otherwise the “npm stop” script will be run.

Integration Upgrade

The Wickr IO command line interface has a command to upgrade an integration. This command 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. The following is an example upgrade.sh script:

i#!/bin/sh

#
# Save the input values:
#
export OLD_MYBOT_LOCATION=$1
export NEW_MYBOT_LOCATION=$2

#
# Save the version from the OLD location
#
old_version="$OLD_MYBOT_LOCATION/VERSION"
version=`cat "$old_version"`

cd $OLD_MYBOT_LOCATION

#
# Copy the json files to the new software location
set +e
mv integrations.json integrations_old.json
cp integrations_old.json users.json processes.json tokensInput.txt toRemove.txt $NEW_MYBOT_LOCATION
set -e

#
# Move the OLD installation to a saved directory
# Remove a previous one if necessary
#
cd ..
rm -rf mybot.old_V$version
mv mybot mybot.old_V$version

#
# Move the NEW installation to the myybot directory
#
cd $NEW_MYBOT_LOCATION/..
mv $NEW_MYBOT_LOCATION mybot

NOTE: when upgrading custom integration software from an 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 script is NOT part of the new integration software then the default operation will be to remove the old software installation associated with a particular integration 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.

Creating an Integration Locally

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 Wickr IO Gateway command line interface has several commands which are useful when creating your own integrations. These are:

When you are adding a new Wickr IO client to the Wickr IO 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 command line interface 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 Wickr IO client 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.

Files that you should include in the export are the following:

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.

Files that you should NOT include in the export are the following:

After the integration is exported the location of the 'tar.gz' file will be displayed. You can copy that file to another Wickr IO gateway or use it on the local Wickr IO 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:
#  Name          Status   Integration         Misc
===========================================================
0  desktop_bot   Running  new_welcome_bot
1  npm_test_bot  Running  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/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/client_bot_username.txt? (default: yes):no
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/configure.sh? (default: yes):
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/hello_world_bot.js? (default: yes):
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/install.sh? (default: yes):
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/package-lock.json? (default: yes):no
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/package.json? (default: yes):
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/README.md? (default: yes):
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/start.sh? (default: yes):
Include file /opt/WickrIO/clients/npm_test_bot/integration/my-hello-world-bot/stop.sh? (default: yes):
Include directory /opt/WickrIO/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/WickrIO/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

Troubleshooting Integrations

To manage and control integrations behind the scenes we use a production process manager for Node.js called forever. If you need to get advanced control on an integration, you can run forever commands but you will have to run them inside the Docker container you are running the Wickr IO gateway, the following section will show you how to do that.

Configuration

Forever is used to start, stop and maintain the bots. The configuration of bot tokan values will add the token definitions to the "env" object in the processes.json file. For most bots these values will need to be added to the process.env values. The wickrio-bot-api contains a function that will transfer the token values from the processes.json file to the process.env, the following is that function:

bot.processesJsonToProcessEnv()

Just make sure to run this function before your code attempts to reference any of the token values in the process.env object. You will need to make sure the wickrio-bot-api is included in your dependencies.

Running commands in Docker environment

  1. Find and copy your docker container's ID: docker ps
  2. Get into the container's command line terminal: docker exec -i -t container_ID /bin/bash

Useful advanced debugging commands

Definitions

This section contains definitions of objects and message formats that are referenced by other parts of this site.

Wickr Message Formats

This section will describe the format of the Wickr messages that will be exposed by the Wickr IO addon APIs and the Wickr IO Web Interface REST messaging APIs. This section will describe each of the Wickr message types you may encounter. Each type of message has a message type field, the following table identifies the values contained in the "msgtype" field:

Message Type msgtype value
Text message 1000
Verification messages 3000
File transfer 6000
Calling message 7000
Location message 8000
Edit message 9000
Edit Reaction message 9100
Create room 4001
Modify room members 4002
Leave room 4003
Modify room parameters 4004
Delete room 4005
Delete message 4011
Message attributes message 4012
Message attributes sync request 4013
Modify private property 4014

All of the messages are represented using JSON. The following table describes the possible fields that are contained in the message JSON. NOTE: the edit messages are only seen by the compliance bot installations.

Field Description
control JSON object that defines the control message information. Contents described below.
file JSON object that defines the details of a file transfer message. Contents described below.
id Unique identifier for the message
message The text associated with a text message
msgtype Type of message, values defined in table above.
msg_ts The time the message was sent, accurate to the microsecond.
receiver Wickr ID of the receiver, for 1-to-1 messages.
sender Wickr ID of the sending client.
sender_type indicates if this is a guest user or normal user.
time Displayable time message was sent.
time_iso The time in ISO format (YYYY-MM-DD hh:mm:ss.xxx)
vgroupid The unique vGroupID of the conversation.

The following sub-sections will describe each of these message formats.

One-to-one messages

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

{
    "message_id":"3960e020ca4211e799802f2894564caa",
    "message":"This is a typical 1:1 message",
    "msg_ts":"1510777143.738976",
    "msgtype":1000,
    "receiver":"user001",
    "sender_type": "normal",
    "sender":"user003",
    "time": "7/11/23 5:19 PM",
    "time_iso": "2023-07-11 17:19:58.781",
    "ttl": "7/10/24 5:19 PM",
    "vgroupid":"fb6e21630c05fde50ae39113c3626018712cf2c374b4a80eba4d28ced9419c07"
}

Group and Room Conversation messages

The following shows a normal group and secure room conversation message format.

{
    "message_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"
}

In some cases, the Wickr IO client does not track the list of clients associated with group conversations, so the list of destination clients will not be included. You can use the supplied Wickr IO APIs to retrieve the members associated with a secure room or group conversation vGroupID.

Text Messages with Links

If you send a text message that contains links, and the security group settings have the "Send Link Preview" option enabled, the text message will contain a list of the URLs for those links:

{
   "links":[
      {
         "url":"https://testdaily.com/image/test-laughing/"
      }
   ],
   "message":"Check out this link https://testdaily.com/image/test-laughing/",
   "message_id":"fb7d7d20b25d11eb9a2d77f565346d8b",
   "msg_ts":"1620740228.594362",
   "msgtype":1000,
   "receiver":"bnuser02@userworld.com",
   "sender":"bnuser01@userworld.com",
   "time":"5/11/21 1:37 PM",
   "ttl":"6/10/21 1:37 PM",
   "vgroupid":"2c0ae523d2b1af3e43af80b5fafec05548fd2e33fee4c021c66033c6416bb6bb"
}

File Transfer messages

This message type contains information about a file transfer message. The "file" JSON object contains the details of the file being transferred, described in this table:

Field Description
filename The display name of the file being transferred.
guid A unique identifier for the transferred file.
isscreenshot Boolean field that identifies if the file is a screen shot image.
localfilename The full path name of the file on the Wickr IO Gateway system.

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

{
    "file": {
        "filename": "picture.jpeg",
        "guid": "AD20D048-9B60-4F32-A691-2D4BE4152E58",
        "localfilename": "/opt/WickrIO/clients/compliancebot01/attachments/attachment_20171116111610865_picture.jpeg",
        "uploadedbyuser": "cn0623_01@amazon.com",
        "uploadedtimestamp": "7/11/23 5:22 PM"
    },
    "message_id": "91a189c0cae911e79ec4eb19a763225b",
    "msg_ts": "1510849017.756174",
    "msgtype": 6000,
    "sender": "user003",
    "sender_type": "normal",
    "time": "7/11/23 5:22 PM",
    "time_iso": "2023-07-11 17:22:02.348",
    "vgroupid": "S3042f1bd04491c6f3732a871e27ab516a8d1534cc1e2d25c4e4869ce72e8541"
}

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.

Calling messages (current)

The format of the pre-5.47 versions of WickrIO will be described in the following section. Calling messages will have a "call" object with a subset of the following values:

Name Description
calluri The URI associated with the call.
calluriipv6 the IPv6 URI associated with the call
duration The call duration in seconds. Sent in the end of call message. The duration of a call in a room starts immediately regardless if any users answer the call. The duration of a call in a one-on-one conversation will begin when the called user answers the call.
invitemsgid The message ID associated with the original call start message. This is sent when another user is added to a call.
meetingid The unique meeting ID associated with the call.
messagetype The type of call message this is, see table below.
participants List of username hash values for all of the potential participants of the call.
startmsgid The message ID associated with the call start message.
status The current state of the call (i.e. starting, completed)
version The call protocol version
versioncheck TBD

The "status" fields identifies the current state of the call, the following table identifies what the "status" values are:

Call Status status value
Call starting 0
Call completed 1
Call missed 2
Call cancelled 3

The "messagetype" identifies the message type of the call message, the following table identifes the "messagetype" values:

Call Message Type Value Description
Start call 0 Starting a call
End call 1 Ending a call
Missed call 2 Missed a call request
Declined call 3 Declined a call request
Silent ring 4 Sent from a device when it answers a call. This is so that the other devices for that client will stop ringing.

Typical call in a room

The following is a sequence of messages that the compliance bot will receive for calling between three users in a room. This is a simple call where one user initiates the call in the room the other two users answer the call and the user that initiates the call ends the call. The "vgroupid" will identify the conversation that this call be occurring on.

The first message you will see it the call starting message. The "call" objects will identify the list of participants in the call, in this case there are 3 participants for this call.

{
    "call":{
        "calluri":"18.213.206.249:16390",
        "certificates":[
           "-----BEGIN CERTIFICATE-----\...\n-----END CERTIFICATE-----\n",
           "-----BEGIN CERTIFICATE-----\...\n-----END CERTIFICATE-----\n",
        ],
        "domain":"amazon.com",
        "calluriipv6":"[2600:1f18:2741:9e01:61b9:1869:8e1e:4082]:16390",
        "meetingid":"bb7f4478-2614-4ffb-9038-2a7c5cce90b7",
        "messagetype":0,
        "participants":[
            "6424ebbd79af79e80c709e93aba0aa80281562955c2502f3ae762d90ee47c257",
            "da870dddf24b41691ef514c2daa002d7ccd936b6df3f8e9c552ad08337dff4be",
            "43f2cab0977ba85452d113170f282c5018f406f524a541595f2ea94c59ed2a83"
        ],
        "status":0,
        "version":2,
        "versioncheck":true,
        "vgroupid":"S49bf359b1229270fdbbc9fbca6289ce1f2171bf9f278c7b37cd3a76ab12e2e1"
    },
    "message_id":"20cc69c0ed2d11eabecd817847e86976",
    "msg_ts":"1599058866.990588",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:34.404",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"S49bf359b1229270fdbbc9fbca6289ce1f2171bf9f278c7b37cd3a76ab12e2e1"
}

When a user answers a call you will see the following message types. These messages have a "messagetype" of 4 which is sent to tell the other devices for that user to stop ringing. You will see one of these for each participant that is in the call, aside from the user originating the call.

{
    "call":{
        "messagetype":4,
        "startmsgid":"20cc69c0ed2d11eabecd817847e86976",
        "status":0,
        "version":2,
        "versioncheck":true
    },
    "message_id":"23a4b710ed2d11eab7697d766fcb32a2",
    "msg_ts":"1599058871.990588",
    "msgtype":7000,
    "sender":"cbtestuser@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:34.404",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"S49bf359b1229270fdbbc9fbca6289ce1f2171bf9f278c7b37cd3a76ab12e2e1"
}

When the call is done you will see the following message to end the call. The "duration" will identify how long, in seconds, the call was live for. This value may be different than if you calculate the time of the original call start message to this call complete message. The "duration" is a more accurate amount of time based on the connected call.

{
    "call":{
        "duration":83,
        "meetingid":"bb7f4478-2614-4ffb-9038-2a7c5cce90b7",
        "messagetype":1,
        "startmsgid":"20cc69c0ed2d11eabecd817847e86976",
        "status":1,
        "version":2,
        "versioncheck":true
    },
    "message_id":"52ec4ab0ed2d11eabecd817847e86976",
    "msg_ts":"1599058950.990589",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"S49bf359b1229270fdbbc9fbca6289ce1f2171bf9f278c7b37cd3a76ab12e2e1"
}

Adding user to a call

During a call it may be necessary to add a user to a call. The following sequence will show a normal call started with two users, and then a third user is added to the call. Please note, the call is started on a specific conversation identified by the "vgroupid" value (in this case the vgroup ID is "S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"). When additional users are added you will see the "vgroupid" values associated with each of the one-on-one conversations to each of the new users (in this case the vgroup ID for the 1-on-1 conversation between cbtestusertwo@wickr.com and cbtestuserthree@wickr.com is "4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b").

The following is the initial start call message, it only includes the original two participants. Please note the "vgroupid" is a secure room conversation, identified by the "S" character at the beginning of the "vgroupid".

{
    "call":{
        "calluri":"18.213.206.249:16386",
        "calluriipv6":"[2600:1f18:2741:9e01:61b9:1869:8e1e:4082]:16386",
        "meetingid":"177539f4-7d60-4c52-8f1c-d98f421e847f",
        "messagetype":0,
        "participants":[
            "da870dddf24b41691ef514c2daa002d7ccd936b6df3f8e9c552ad08337dff4be",
            "43f2cab0977ba85452d113170f282c5018f406f524a541595f2ea94c59ed2a83"],
        "status":0,
        "version":2,
        "versioncheck":true
        },
    "message_id":"3af57350ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063205.990632",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"
}

The following message is the called user accepting the call, by turning off the ringing in the other devices.

{
    "call":{
        "messagetype":4,
        "startmsgid":"3af57350ed3711eab7697d766fcb32a2",
        "status":0,
        "version":2,
        "versioncheck":true
        },
    "message_id":"4068dde0ed3711eabecd817847e86976",
    "msg_ts":"1599063214.990632",
    "msgtype":7000,
    "sender":"cbtestusertwo@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"
}

The following message is sent when a new participant is added to the call. Notice the different "vgroupid" value in the mssage, it is associated with the one-to-one conversation between cbtestuser@wickr.com and cbtestuserthree@wickr.com. The "invitemsgid" is the same value as the message that the call was started with. The "meetingid" is the same value as the running call's "meetingid", seen in the initial start call message.

{
    "call":{
        "calluri":"18.213.206.249:16386",
        "calluriipv6":"[2600:1f18:2741:9e01:61b9:1869:8e1e:4082]:16386",
        "invitemsgid":"3af57350ed3711eab7697d766fcb32a2",
        "meetingid":"177539f4-7d60-4c52-8f1c-d98f421e847f",
        "messagetype":0,
        "participants":[
            "6424ebbd79af79e80c709e93aba0aa80281562955c2502f3ae762d90ee47c257"
        ],
        "startmsgid":"3af57350ed3711eab7697d766fcb32a2",
        "status":0,
        "version":2,
        "versioncheck":true
        },
    "message_id":"526beb90ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063245.990632",
    "msgtype":7000,
    "receiver":"cbtestuser@wickr.com",
    "sender":"cbtestuserthree@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

The following message is sent from the new participant when accepting the call.

{
    "call":{
        "messagetype":4,
        "startmsgid":"3af57350ed3711eab7697d766fcb32a2",
        "status":0,
        "version":2,
        "versioncheck":true
        },
    "message_id":"54ebdfb0ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063249.990632",
    "msgtype":7000,
    "receiver":"cbtestuserthree@wickr.com",
    "sender":"cbtestuser@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

This message is sent to the original "vgroupid" when the call is ended. The original conversation only contains users that were invited to the original call.

{
    "call":{
        "duration":54,
        "meetingid":"177539f4-7d60-4c52-8f1c-d98f421e847f",
        "messagetype":1,
        "startmsgid":"3af57350ed3711eab7697d766fcb32a2",
        "status":1,
        "version":2,
        "versioncheck":true
        },
    "message_id":"5bbf0150ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063260.990632",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"
}

This message is also sent to the one-on-one "vgroupid" for the invited user when the call is ended. Users that were invited to a running call will be sent the message to end a call from the user that originated the call, not from the user that invited them to the meeting. The "vgroupid" used to communicate with these "invited" users will be associated with a one-to-one conversation between the user that initiated the call and the invited user.

{
    "call":{
        "duration":54,
        "meetingid":"177539f4-7d60-4c52-8f1c-d98f421e847f",
        "messagetype":1,
        "startmsgid":"526beb90ed3711eab7697d766fcb32a2",
        "status":1,
        "version":2,
        "versioncheck":true
        },
    "message_id":"5bc59100ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063260.990632",
    "msgtype":7000,
    "receiver":"cbtestuser@wickr.com",
    "sender":"cbtestuserthree@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

Missed Call

If a call is attempted on a one-to-one conversation and the target participant does not answer the call you will see a message with a missed call "messagetype" value of 2. This message is sent from the user originating the call to the called user. There is no duration associated with this call and should not be considered a completed call.

{
    "call":{
        "messagetype":2,
        "startmsgid":"e7dd80b0ed3e11eab7697d766fcb32a2",
        "status":2,
        "version":2,
        "versioncheck":true
        },
    "message_id":"fa0a5d80ed3e11eab7697d766fcb32a2",
    "msg_ts":"1599066532.990665",
    "msgtype":7000,
    "receiver":"cbtestusertwo@wickr.com",
    "sender":"cbtestuserthree@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"ec6cfd71ccb4034c9d77263da8c28d01d19a6f91746d3b9b61b868d0663008a4"
}

Declined Calls

If a user on a one-on-one call selects to ignore the call, a declined call message will be seen. You should not see this type of message on room conversations.

{
    "call":{
        "messagetype":3,
        "startmsgid":"a1072ee0ed5f11eabecd817847e86976",
        "status":3,
        "version":2,
        "versioncheck":true
        },
    "message_id":"a26f4a60ed5f11eabecd817847e86976",
    "msg_ts":"1599080559.990805",
    "msgtype":7000,
    "receiver":"cbtestuserthree@wickr.com",
    "sender":"cbtestuser@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:24 PM",
    "time_iso": "2023-07-11 17:24:42.045",
    "ttl": "7/10/24 5:24 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

Calling messages (pre-5.47)

This section will describe the format of the json associated with calling for pre-5.47 versions of the WickrIO products. Calling messages will have a "call" object with a subset of the following values:

Name Description
meetingid The unique meeting ID associated with the call.
status The current state of the call (i.e. starting, completed)

The "status" fields identifies the current state of the call, the following table identifies what the "status" values are:

Call Status status value
Call starting 0
Call completed 1
Call missed 2
Call cancelled 3

Typical call in a room

The following is a sequence of messages that the compliance bot will receive for calling between three users in a room. This is a simple call where one user initiates the call in the room the other two users answer the call and the user that initiates the call ends the call. The "vgroupid" will identify the conversation that this call be occurring on.

The first message you will see it the call starting message. The potential list of participants of the call can be deduced by the users in the convo identified by the "vgroupid" value.

{
    "call":{
        "meetingid":"bb7f4478-2614-4ffb-9038-2a7c5cce90b7",
        "status":0
    },
    "message_id":"20cc69c0ed2d11eabecd817847e86976",
    "msg_ts":"1599058866.990588",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "time":"9/2/20 3:01 PM",
    "vgroupid":"S49bf359b1229270fdbbc9fbca6289ce1f2171bf9f278c7b37cd3a76ab12e2e1"
}

When a user answers a call you will see the following messages.

{
    "call":{
        "status":0
    },
    "message_id":"23a4b710ed2d11eab7697d766fcb32a2",
    "msg_ts":"1599058871.990588",
    "msgtype":7000,
    "sender":"cbtestuser@wickr.com",
    "time":"9/2/20 3:01 PM",
    "vgroupid":"S49bf359b1229270fdbbc9fbca6289ce1f2171bf9f278c7b37cd3a76ab12e2e1"
}

When the call is done you will see the following message to end the call.

{
    "call":{
        "status":1
    },
    "message_id":"52ec4ab0ed2d11eabecd817847e86976",
    "msg_ts":"1599058950.990589",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "time":"9/2/20 3:02 PM",
    "vgroupid":"S49bf359b1229270fdbbc9fbca6289ce1f2171bf9f278c7b37cd3a76ab12e2e1"
}

Adding user to a call

During a call it may be necessary to add a user to a call. The following sequence will show a normal call started with two users, and then a third user is added to the call. Please note, the call is started on a specific conversation identified by the "vgroupid" value (in this case the vgroup ID is "S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"). When the additional user is added you will see the "vgroupid" associated with the one-on-one conversation to that new user (in this case the vgroup ID is "4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b").

The following is the start call message, it only includes the original two participants:

{
    "call":{
        "meetingid":"177539f4-7d60-4c52-8f1c-d98f421e847f",
        "status":0
        },
    "message_id":"3af57350ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063205.990632",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "time":"9/2/20 4:13 PM",
    "vgroupid":"S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"
}

The following message is the called user accepting the call.

{
    "call":{
        "status":0
        },
    "message_id":"4068dde0ed3711eabecd817847e86976",
    "msg_ts":"1599063214.990632",
    "msgtype":7000,
    "sender":"cbtestusertwo@wickr.com",
    "time":"9/2/20 4:13 PM",
    "vgroupid":"S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"
}

This message is sent when a new participant is added to the call. Notice the different "vgroupid" value in the mssage. The "meetingid" is the same as the running call's "meetingid".

{
    "call":{
        "meetingid":"177539f4-7d60-4c52-8f1c-d98f421e847f",
        "status":0
        },
    "message_id":"526beb90ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063245.990632",
    "msgtype":7000,
    "receiver":"cbtestuser@wickr.com",
    "sender":"cbtestuserthree@wickr.com",
    "time":"9/2/20 4:14 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

The following message is sent from the new participant when accepting the call.

{
    "call":{
        "status":0
        },
    "message_id":"54ebdfb0ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063249.990632",
    "msgtype":7000,
    "receiver":"cbtestuserthree@wickr.com",
    "sender":"cbtestuser@wickr.com",
    "time":"9/2/20 4:14 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

This message is sent to the original "vgroupid" when the call is ended.

{
    "call":{
        "status":1
        },
    "message_id":"5bbf0150ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063260.990632",
    "msgtype":7000,
    "sender":"cbtestuserthree@wickr.com",
    "time":"9/2/20 4:14 PM",
    "vgroupid":"S4666b353873113884feb66d1409875a81b40aa5c0ddbab040ec11f1b38e752c"
}

This message is also sent to the one-on-one "vgroupid" for the invited user when the call is ended.

{
    "call":{
        "status":1
        },
    "message_id":"5bc59100ed3711eab7697d766fcb32a2",
    "msg_ts":"1599063260.990632",
    "msgtype":7000,
    "receiver":"cbtestuser@wickr.com",
    "sender":"cbtestuserthree@wickr.com",
    "time":"9/2/20 4:14 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

Missed Call

If a call is attempted on a one-to-one conversation and the target participant does not answer the call you will see a message with a missed call "messagetype" value of 2. This message is sent from the user originating the call to the called user. There is no duration associated with this call and should not be considered a completed call.

{
    "call":{
        "status":2
        },
    "message_id":"fa0a5d80ed3e11eab7697d766fcb32a2",
    "msg_ts":"1599066532.990665",
    "msgtype":7000,
    "receiver":"cbtestusertwo@wickr.com",
    "sender":"cbtestuserthree@wickr.com",
    "time":"9/2/20 5:08 PM",
    "vgroupid":"ec6cfd71ccb4034c9d77263da8c28d01d19a6f91746d3b9b61b868d0663008a4"
}

Declined Calls

If a user on a one-on-one call selects to ignore the call, a declined call message will be seen. You should not see this type of message on room conversations.

{
    "call":{
        "status":3
    },
    "message_id":"1739df60ed4011eabecd817847e86976",
    "msg_ts":"1599067011.990670",
    "msgtype":7000,
    "receiver":"cbtestuserthree@wickr.com",
    "sender":"cbtestusertwo@wickr.com",
    "time":"9/2/20 5:16 PM",
    "vgroupid":"4c84cfa0a7b780f76fdb8d86cb5569f61e66a7a43ef8ab1cc5b537b427e1989b"
}

Location messages

This message is sent when a user sends their location in a conversation. The location will contain the user’s latitude and longitude:

{
    "location":{
        "latitude":45.75017899435506,
        "longitude":-74.99449803034105
    },
    "message_id":"1f88fdc08bec11ea81b689d23fa72c7b",
    "msg_ts":"1588365684.583407",
    "msgtype":8000,
    "receiver":"user003",
    "sender":"user100",
    "sender_type": "normal",
    "time": "7/11/23 5:33 PM",
    "time_iso": "2023-07-11 17:33:24.394",
    "ttl": "7/10/24 5:33 PM",
    "vgroupid":"4ebf561eb2214c4e6f924d09e37bf80b6f9b85cb96b72badb03753d9ed26f7f4"
}

Edit messages

There are current two types of edit messages supported, the location and the text types. The location type of edit message is sent when a user is sharing their location with someone else. These edit message types are supported as of version 5.47.30.

{
    "edit":{
        “type”:”location”,
        “shareexpiriation”:””;
        "latitude":45.75017899435506,
        "longitude":-78.99449803034105
    },
    "message_id":"1f88fdc08bec11ea81b689d23fa72c7b",
    "msg_ts":"1588365684.583407",
    "msgtype":9000,
    "receiver":"user003",
    "sender":"user100",
    "sender_type": "normal",
    "time": "7/11/23 5:30 PM",
    "time_iso": "2023-07-11 17:30:15.103",
    "ttl": "7/10/24 5:30 PM",
    "vgroupid":"4ebf561eb2214c4e6f924d09e37bf80b6f9b85cb96b72badb03753d9ed26f7f4"
}

The text type of edit message is sent when the user sends a message that includes links in it. For example the user sends a message with the link https://howdoyoudo.com in it, the following is what the edit message would look like:

{
    "edit":{
        "originalmessageid":"11457fa08da211ea881baffab0b42745",
        "text":"https://howdoyoudo.com",
        "type":"text"
    },
    "message_id":"1163e5b08da211eab775a5032a0322ca",
    "msg_ts":"1588553780.419871",
    "msgtype":9000,
    "sender":"user001@amazon.com",
    "sender_type": "normal",
    "time": "7/11/23 5:30 PM",
    "time_iso": "2023-07-11 17:30:15.103",
    "ttl": "7/10/24 5:30 PM",
    "vgroupid":"S243f2ec645d3961bdd531f51f3244205d292b8d0fbd41802827746271d31d41"
}

If you send a text message with a link and the security group has the "Send Link Preview" option enabled, the edit message may contain an array of links information and link image meta information. The following shows these additional fields: 

{
    "edit":{
      "linkimagemeta":{
         "domain":"userworld.com",
         "guid":"c43c71ef-4373-444e-a22d-dfce34d38a7a",
         "hash":"32bc71721bea8a456a06f364995012d3ebfc41aaaad0c2dd632b0f0bae4690f4bffcd5a4c23b4af16086fcfcd43d20058ca67ae10a7b38d74c2bffa21ea8de05",
         "key":"00a85d12214f596d4eac929d82287cccdead2a00c542f850322c1655494be2a40d"
      },
      "links":[
         {
            "faviconurl":"https://testdaily.com/favicon.ico",
            "imageurl":"https://testdaily.com/uploads/gallery/test-laughing.gif",
            "pagetitle":"Test laughing",
            "sitename":"Test Daily",
            "url":"https://testdaily.com/gallery/image/Test-laughing/"
         }
      ],
      "originalmessageid":"fb7d7d20b25d11eb9a2d77f565346d8b",
      "text":"https://twinsdaily.com/gallery/image/2234-burns-laughing/",
      "type":"text"
    },
    "message_id":"fe9c4950b25d11eb9a2d77f565346d8b",
    "msg_ts":"1620740233.829096",
    "msgtype":9000,
    "receiver":"bnuser02@userworld.com",
    "sender":"bnuser01@userworld.com",
    "sender_type": "normal",
    "time": "7/11/23 5:35 PM",
    "time_iso": "2023-07-11 17:35:41.411",
    "ttl": "7/10/24 5:35 PM",
    "vgroupid":"2c0ae523d2b1af3e43af80b5fafec05548fd2e33fee4c021c66033c6416bb6bb"
}

Edit Content messages

The Edit Content messages are sent when a user edits the contents of a previously sent message. The Edit Content message will contain the message ID associated with the original message and the text of the updated message. The original message text will not be included. This message type was introduced in the 5.92 version of the WickrIO software. The Edit Content messages are used to identify when the text of a message is edited as well as when the links contained in a message are edited.

The following is a basic example of an Edit Content message where the text is edited:

{
    "content_edited": true,
    "edit":{
        "type":"edit_content",
        "originalmessageid":"36028e2025dd11ec9cdafd3f2bfa110f",
        "text":"This is the edited message"
    },
    "message_id":"3fcef29025dd11ec9cdafd3f2bfa110f",
    "msg_ts":"1633439273.17562",
    "msgtype":9000,
    "receiver":"user001+comp9321_01@wickr.com",
    "sender":"user001+comp9321_02@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:35 PM",
    "time_iso": "2023-07-11 17:35:41.411",
    "ttl": "7/10/24 5:35 PM",
    "vgroupid":"56e3b0570daad62b2e2d14db8d33632f6175514022183a042660c7b8901dec79"
}

The "type" value, within the "edit" group, identifies this as an Edit Content message. The "originalmessageid" identifies the message ID of the original message. The "text" field is the new value of the message.

If the original message contains links, and the "Send Link Previews" option is set for the security group, there will be two Edit Content messages sent. One of these messages is associated with the text message changes and another that will contain the link image meta information. The Edit Content message that contains the "content_edited" with a true value is associated with the message text, as seen below:

{
    "content_edited":true,
    "edit":{
        "type":"edit_content",
        "originalmessageid":"f4bddd80255e11ec8c960b356f9f1aad",
        "text":"This is a test with https://wickr.com",
        "links":[
            { "url":"https://wickr.com" }
        ],
    },
    "message_id":"b17cffb0264911ec9cdafd3f2bfa110f",
    "msg_ts":"1633485849.387294",
    "msgtype":9000,
    "receiver":"user001+comp9321_01@wickr.com",
    "sender":"user001+comp9321_02@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:35 PM",
    "time_iso": "2023-07-11 17:35:41.411",
    "ttl": "7/10/24 5:35 PM",
    "vgroupid":"56e3b0570daad62b2e2d14db8d33632f6175514022183a042660c7b8901dec79"
}

The following Edit Content message is associated with the links that are in the message.

{
    "edit":{
        "type":"edit_content",
        "originalmessageid":"f4bddd80255e11ec8c960b356f9f1aad",
        "text":"This is a test with https://wickr.com",
        "linkimagemeta":{
            "domain":"wickr.com",
            "guid":"4747a757-32db-4748-8a59-f5fc02cf811b",
            "hash":"4848c43ba0ac0cca685cd3053076198f6d710ed02fa7adf4822ba752e48c5328b7bc947d6e0499bfca6d83c86bf805d3b2ed6a7adfa1b300d0be669a1a5e0d3c",
            "key":"0016c4902a79160966335053c07d96accd048ca5ce858f9def2364d11c36b7f345"
        },
        "links":[
            {
                "description":"Wickr provides end-to-end encrypted messaging, audio calling, video conferencing, file and location sharing, and more.",
                "faviconurl":"https://wickr.com/favicon.ico",
                "imageurl":"https://wickr.com/wp-content/uploads/2020/12/wickr-pro-screens-4-1.png",
                "pagetitle":"Home",
                "sitename":"Wickr",
                "url":"https://wickr.com"
            }
        ]
    },
    "message_id":"b270fca0264911ec9cdafd3f2bfa110f",
    "msg_ts":"1633485850.986206",
    "msgtype":9000,
    "receiver":"user001+comp9321_01@wickr.com",
    "sender":"user001+comp9321_02@wickr.com",
    "sender_type": "normal",
    "time": "7/11/23 5:35 PM",
    "time_iso": "2023-07-11 17:35:41.411",
    "ttl": "7/10/24 5:35 PM",
    "vgroupid":"56e3b0570daad62b2e2d14db8d33632f6175514022183a042660c7b8901dec79"
}

Edit Reaction messages

The edit reaction messages are used to modify the reactions associated with a message. The message layout is similar to the Edit message layout, but the "msgtype" value is 9100. The "edit" object contains the following fields:

Field Name Description
originalmessageid The message ID of the message that the reaction is associated with
reactAdded This is a boolean that is true if the reaction is added and false if removed
reaction This is the reaction to enable or disable
type This is always the value "reaction"

The "sender" field will identify who is adding or removing a reaction. The client should display the reaction and which users were associated with that reaction.

The following is a sample of adding a reaction to a message. 

{
    "edit":{
      "originalmessageid":"a1c00830ad3911ebaa04213b1ad0a9b2",
      "reactAdded":true,
      "reaction":"👍",
      "type":"reaction"
    },
    "message_id":"b6d3d1b0add011ebb00f1b2dbb810704",
    "msg_ts":"1620239749.707944",
    "msgtype":9100,
    "receiver":"bn0523_bcast_bot",
    "sender":"bnuser01@userworld.com",
    "sender_type": "normal",
    "time": "7/11/23 5:35 PM",
    "time_iso": "2023-07-11 17:35:41.411",
    "ttl": "7/10/24 5:35 PM",
    "vgroupid":"4b32d7c8c6c37cc9e9506e9ed98ce37f0a96e1e45fcd4ca6f6d00c9d435d82e3"
}

The following is a sample of removing a reaction to a message. 

{
    "edit":{
      "originalmessageid":"a1c00830ad3911ebaa04213b1ad0a9b2",
      "reactAdded":false,
      "reaction":"👍",
      "type":"reaction"
    },
    "message_id":"68596ac0add211ebb00f1b2dbb810704",
    "msg_ts":"1620240477.36364",
    "msgtype":9100,
    "receiver":"bn0523_bcast_bot",
    "sender":"bnuser01@userworld.com",
    "sender_type": "normal",
    "time": "7/11/23 5:35 PM",
    "time_iso": "2023-07-11 17:35:41.411",
    "ttl": "7/10/24 5:35 PM",
    "vgroupid":"4b32d7c8c6c37cc9e9506e9ed98ce37f0a96e1e45fcd4ca6f6d00c9d435d82e3"
}

Wickr Control messages

Wickr control messages are used to setup and configure the Wickr group and secure room conversations. These control messages will also be passed on to the integration software. You can use these control messages to construct and maintain the list of users that are part of group and secure conversations.

The “control” JSON object contains the specific control message fields, as described in this table:

Field Description
bor The burn on read time in seconds.
changemask A number that is the sum of values associated with which fields are being changed by the control message. Table below defines these values.
description The description of the secure room conversation.
masters Array of Wickr IDs that are moderators for the secure room conversation. In group conversations all members should be moderators.
members Array of Wickr IDs that are members of the group or secure room conversation.
title The title of the secure room conversation
ttl The time to live value in seconds.

The changemask value is a number value that is created by adding the following flag values, based on what fields are contained in the “control” object:

Field Value
Masters field 1
Time to live 2
Title field 4
Description 8
Meeting ID key 16
Burn on read 32
File vault info 64

The file vault info message type was added in version 5.47.30 of the product.

The following sections contain examples of control messages, note the values of the changemask fields.

Create Room Control Message

The create room control message is used to create a group or secure room conversation. The following depicts a typical create room control message:

{
    "control":{
        "bor":0,
        "changemask":47,
        "description":"",
        "masters":["user001", "user002"],
        "members":["user001", "user002", "user003"],
        "msgtype":4001,
        "title":"Creating a room",
        "ttl":2592000
    },
    "message_id":"be452b00f89711e883588d1e7a946847",
    "msg_ts":"1544019125.75323",
    "msgtype":4001,
    "sender":"user002",
    "sender_type": "normal",
    "time": "7/11/23 5:12 PM",
    "time_iso": "2023-07-11 17:12:45.168",
    "ttl": "7/10/24 5:12 PM",
    "vgroupid":"S58a15186365d2125a9b417e71b99bcb29e3770078e157e953cfbe28443eb750"
}

In the example above you will see the changemask value 47 which is equal to the sum of the “burn on read” (32), “masters field” (1), “time to live” (2), “title field” (4) and the “description” (8). The changemask values are used in other control messages as well.

Modify Room Members Control Message

The modify room member control message is used to modify the list of users associated with a group or secure room conversation. Members can be added or removed from the conversation using this control message.

{
    "control":{
        "addedusers":[],
        "deletedusers":["testbot"],
        "msgtype":4002
    },
    "message_id":"d34058a0f89711e88760d7c8037ea946",
    "msg_ts":"1544019160.275884",
    "msgtype":4002,
    "sender":"user002",
    "sender_type": "normal",
    "time": "7/11/23 5:15 PM",
    "time_iso": "2023-07-11 17:15:49.079",
    "ttl": "7/10/24 5:15 PM",
    "vgroupid":"S58a15186365d2125a9b417e71b99bcb29e3770078e157e953cfbe28443eb750"
}

The addedusers field identifies the list of users that were added to the conversation. The deletedusers field identifies the list of users that were removed from the conversation.

NOTE: this control message has a fixed set of fields and does not require the changemask field.

Leave Room Control Message

The leave room control message is sent when a user is leaving a secure room or group conversation. The sender is the user leaving the conversation

{
    "message_id":"f660fe80f89711e887d86d198d2ef374",
    "msg_ts":"1544019219.210107",
    "msgtype":4003,
    "sender":"user002",
    "sender_type": "normal",
    "time": "7/11/23 5:54 PM",
    "time_iso": "2023-07-11 17:54:31.688",
    "ttl": "7/10/24 5:54 PM",
    "vgroupid":"S58a15186365d2125a9b417e71b99bcb29e3770078e157e953cfbe28443eb750"
}

This control message is a simple control message and does not contain the "control" JSON object. The msgtype fields identifies the leave room action.

Modify Room Parameters Control Message

The modify room parameters control message is used to modify one or more fields associated with a group or secure room conversation.

{
    "control":{
        "bor":0,
        "changemask":47,
        "description":"change description",
        "masters":["user001", "user002"],
        "members":["user002","user002"],
        "msgtype":4004,
        "title":"Creating a room",
        "ttl":2592000
    },
    "message_id":"db805750f89711e8a01ab328ac0b2f04",
    "msg_ts":"1544019174.117057",
    "msgtype":4004,
    "sender":"user002",
    "sender_type": "normal",
    "time": "7/11/23 5:59 PM",
    "time_iso": "2023-07-11 17:59:57.473",
    "ttl": "7/10/24 5:59 PM",
    "vgroupid":"S58a15186365d2125a9b417e71b99bcb29e3770078e157e953cfbe28443eb750"
}

This message is similar to the create room control message. The changemask field has the same definition as well.

The following control message is sent when a file is added or removed from the list of files to the room’s Saved Items list (added in version 5.47.30):

{
    "control":{
        "bor":0,
        "changemask":64,
        "description":"",
        "filevaultinfo":{
            "domain": "somewhere.com",
            "filehash":"4eab763c5f3211ca93966a…d3e461c27f5432c1",
            "guid":"D094F147-0490-4A14-9A65-6F23C896A8B4",
            "key":"00f8058d88e6b7520849bbfd8e6b5cc12d35a70c856dde44d64e2e331fc50ce700",
        },
        "masters":["puser002","user001"],
        "members":["puser002","user001"],
        "msgtype":4004,
        "title":"Test",
        "ttl":2592000
    },
    "message_id":"c3cb62e08dff11eab641a549111a64cb",
    "msg_ts":"1588594022.928361",
    "msgtype":4004,
    "sender":"user001",
    "sender_type": "normal",
    "time": "7/11/23 6:01 PM",
    "time_iso": "2023-07-11 18:01:58.799",
    "ttl": "7/12/23 6:01 PM",
    "vgroupid":"S243f2ec645d3961bdd531f51f3244205d292b8d0fbd41802827746271d31d41"
}
File Management Actions in Modify Room Parameters Control Message

In version v6.34 a new field "filemgtaction" is added to FileVaultInfo section of modify room parameters control message to support Wickr file management functionality.

Below table lists values of "action" field in "filemgtaction".

action Description
create Create a folder
upload Upload a file
save Save a file to the room
rename Rename a file or folder
move Move a file or folder
delete Delete a file or folder

Below table lists values of "target" field in "filemgtaction".

target Description
file Target is a file
folder Target is a folder

Below table lists all other fields in "filemgtaction".

field Description
fileguid File guid for 'upload' action
filekey File key for 'upload' action
filehash File hash for 'upload' action
filedomain File domain for 'upload' action
localfilename The full path name of the file on Wickr IO Gateway system for 'upload' action
name Name of the file or folder
oldname Old name of the file or folder for 'rename' action
path Path of the file or folder
originpath Origin path of the file or folder for 'move' action
impactedfiles List of impacted files for 'delete' action
modifiedbyuser User who performs the action
modifiedtimestamp Timestamp as seconds since epoch of the action

Some examples are given below.

The following control message is used when a file "sample.pdf" is uploaded to root folder "/" by "user001" via file management UI. All the relevant are in "filemgtaction" section.

{"control":{"bor":0,"changemask":64,"description":"","filevaultinfo":{"domain":"somewhere.com","filehash":"41a8df167cecda78c4...9dc7dc14dcc1d8","filemgtaction":{"action":"upload","filedomain":"somewhere.com","fileguid":"9083f39c-f9aa-4fd0-9b4b-be9ced1774c9","filehash":"165f555b2b3e0c112...c8192794eed6b367","filekey":"00b5d0a4a7e902c1b1189e5bc9b4a38986e53548d8e7ed11e430554db63e99c7d8","localfilename":"/tmp/compliance_24731556_bot/compliance/attachments/attachment_20240307180433840_9083f39c-f9aa-4fd0-9b4b-be9ced1774c9_sample.pdf","modifiedbyuser":"user001","modifiedtimestamp":"2024-03-07 18:04:31","name":"sample.pdf","path":"/","target":"file"},"guid":"b19169cc-9113-4d0f-b819-8c01d18b792c","key":"00cf0b0c7073b2665f949aa3e602ff308d8de7d85039ce20a2cadc8ce823951854"},"masters":["user001","user002"],"members":["user001","user002"],"msgtype":4004,"title":"Test","ttl":31536000},"dstusers":[{"name":"user001","networkid":"67169081"},{"name":"user002","networkid":"24731556"}],"members_accurate":true,"message_id":"2717fb00dcad11ee9930cb85c8895a50","msg_ts":"1709834673.840591","msgtype":4004,"sender":"user001","srcuser":{"name":"user001","networkid":"67169081"},"time":"7 Mar 2024 18:04:33","time_iso":"2024-03-07 18:04:33.840","ttl":"7 Mar 2025 18:04:33","vgroupid":"S491a9b09b7069ed3be0b4a092964a99ff59254c1df5b6d1676694def7af44a5"}

The following control message is used when the file "sample.pdf" is moved from root folder "/" to "/folder1" by "user001" via file management UI. All the relevant are in "filemgtaction" section.

{"control":{"bor":0,"changemask":64,"description":"","filevaultinfo":{"domain":"somewhere.com","filehash":"2effdb9f6094bff22dedb...218f7657da5651","filemgtaction":{"action":"move","modifiedbyuser":"user001","modifiedtimestamp":"2024-03-07 18:05:04","name":"sample.pdf","originpath":"/","path":"/folder1","target":"file"},"guid":"09a09900-5b9c-45e6-a97f-2820f2466743","key":"00b1248616bc3d72ae4b214bbc7304261b792a7a31c0aba3f92af7565edc0a2287"},"masters":["user001","user002"],"members":["user001","user002"],"msgtype":4004,"title":"DR test room","ttl":31536000},"dstusers":[{"name":"user001","networkid":"67169081"},{"name":"user002","networkid":"24731556"}],"members_accurate":true,"message_id":"3a9a7cc0dcad11ee9930cb85c8895a50","msg_ts":"1709834706.573013","msgtype":4004,"sender":"user001","srcuser":{"name":"user001","networkid":"67169081"},"time":"7 Mar 2024 18:05:06","time_iso":"2024-03-07 18:05:06.573","ttl":"7 Mar 2025 18:05:06","vgroupid":"S491a9b09b7069ed3be0b4a092964a99ff59254c1df5b6d1676694def7af44a5"}

The following control message is used when a folder "folder1" which contains files "sample.pdf" and "sample2.pdf" is deleted from root folder "/" by "user001" via file management UI. All the relevant are in "filemgtaction" section.

{"control":{"bor":0,"changemask":64,"description":"","filevaultinfo":{"domain":"somewhere.com","filehash":"bfea98caea2cd5de8c04b5...55fc8705ec16","filemgtaction":{"action":"delete","impactedfiles":["sample.pdf","sample2.pdf"],"modifiedbyuser":"user001","modifiedtimestamp":"2024-03-07 18:06:14","name":"folder1","path":"/","target":"folder"},"guid":"e3f70f43-6f79-461b-8213-084c5c7380ac","key":"00fd0ab641b39a981a657ca1202ea4e16f99d820b78bfc15e293d5635fa3e0da32"},"masters":["user001","user002"],"members":["user001","user002"],"msgtype":4004,"title":"test room","ttl":31536000},"dstusers":[{"name":"user001","networkid":"67169081"},{"name":"user002","networkid":"24731556"}],"members_accurate":true,"message_id":"63bf04e0dcad11ee9930cb85c8895a50","msg_ts":"1709834775.598738","msgtype":4004,"sender":"user001","srcuser":{"name":"user001","networkid":"67169081"},"time":"7 Mar 2024 18:06:15","time_iso":"2024-03-07 18:06:15.598","ttl":"7 Mar 2025 18:06:15","vgroupid":"S491a9b09b7069ed3be0b4a092964a99ff59254c1df5b6d1676694def7af44a5"}

Delete Room Control Message

The delete room control message is used to delete a specific group or secure room conversation. 

{
    "message_id":"06364710f89811e899418b6723464a0c",
    "msg_ts":"1544019245.773676",
    "msgtype":4005,
    "sender":"user002",
    "sender_type": "normal",
    "time": "7/11/23 6:03 PM",
    "time_iso": "2023-07-11 18:03:01.100",
    "ttl": "7/12/23 6:03 PM",
    "vgroupid":"S7879eb406958d83b991a5f2acb29e5ad8565a4faa41e1c5cbd7004c5586ddd5"
}

Like the leave room control message, this control message does not have a "control" JSON object. The msgtype identifies that action to be performed.

Delete message

Here is the delete control message that will delete a message from all of the specified sender's devices. The sender is the sender of the control message, not the original sender of the message being deleted. The message will not be deleted from other users devices: The message to delete is identified by the id value in the control group.

{   
    "control":
    {   
        "message_id":"a59a3520ca2f11e7a14cd1c8bf2a1be8",
        "isrecall":false,
        "msgtype":4011
    },
    "message_id":"aa4a3580ca2f11e7a156a34c720bab3d",
    "msg_ts":"1510769172.735225",
    "msgtype":4011,
    "sender":"user003",
    "time":"11/15/17 1:06 PM",
    "vgroupid":"Sb0e9297f2208dc86b63b288df8c226882e1052b65022edb9edb9ecf6e77db08"
}

Here is the delete control message that will recall the message from all users the message was sent to:

{
    "control":
    {
        "isrecall":true,
        "message_id":"c2855a10ca2f11e7afa15b0943d8c736",
        "msgtype":4011
    },
    "message_id":"c5bce5e0ca2f11e78946112c51861afa",
    "msg_ts":"1510769218.785332",
    "msgtype":4011,
    "sender":"user003",
    "time": "7/11/23 6:04 PM",
    "time_iso": "2023-07-11 18:04:03.772",
    "ttl": "7/10/24 6:04 PM",
    "vgroupid":"Sb0e9297f2208dc86b63b288df8c226882e1052b65022edb9edb9ecf6e77db08"
}

Modify private property

This message identifies when a conversation is pinned or un-pinned. The "pinned" value will be true when the conversation is pinned, and "false" when it is being un-pinned.

{
    "control":
    {
        "pinned":true,
        "msgtype":4014
    },
    "message_id":"c5bce5e0ca2f11e78946112c51861afa",
    "msg_ts":"1510769218.785332",
    "msgtype":4014,
    "sender":"user003",
    "sender_type": "normal",
    "time": "7/11/23 6:07 PM",
    "time_iso": "2023-07-11 18:07:21.981",
    "ttl": "7/10/24 6:07 PM",
    "vgroupid":"Sb0e9297f2208dc86b63b288df8c226882e1052b65022edb9edb9ecf6e77db08"
}

This message identifies when a message is starred:

{
    "control": {
      "attributes": [
        {
          "isstarred": true,
          "msgid": "74f16f3011d511ee9456414dec7866b3"
        }
      ],
      "msgtype": 4012
    },
    "message_id": "7a38aa00201511eeb723c79384d92c63",
    "msg_ts": "1689098711.200122",
    "msgtype": 4012,
    "sender": "cn0623_01@amazon.com",
    "sender_type": "normal",
    "time": "7/11/23 6:05 PM",
    "time_iso": "2023-07-11 18:05:11.200",
    "ttl": "7/10/24 6:05 PM",
    "vgroupid": "S5d76ccc43c2bb3bc93e7273798ce8f4b89bfa8429b33888fbcd454e5d233a19"
}

Text Message Meta Data

As of the 5.81 release of WickrIO, support was added to record the text message meta data fields. These fields are used to define GUI widgets specific to the text message being transmitted. Specific GUI widgets include buttons and list items. If you are interested in creating bots with buttons or lists, refer to the transmit message arguments section of the Node.js Addon APIs.

Text Message Table Meta Data

The following text message is a broadcast bot's response to a /report command. This sample message contains two meta objects, the "tablemeta" object and the "textcutmeta" object. The "tablemeta" object contains information used to display the list on the Wickr client. The column name objects define the headers for the table. The "items" array contains the entries for the table. The "textcutmeta" array contains information used to remove parts of the "message" value when displaying the message to the user. This is done because the text of the "message" may be redundant to the information contained in the "tablemeta" object. This will allow Wickr clients that do not yet support the "tablemeta" protocol yet.

{
   "message":"Here are the past 5 broadcast message(s):\n(1) this is a broadcast\n(2) Send to one user\n(3) This is the 3rd broadcast\n(4) Hello World!\n(5) Test one\nTo get started, select the broadcast for which you would like to generate a report",
   "message_id":"80cff660a75a11eb986e31ce44694ab3",
   "msg_ts":"1619529271.494966",
   "msgtype":1000,
   "receiver":"bnuser01@userworld.com",
   "sender":"bn0523_bcast_bot",
   "tablemeta":{
      "actioncolumnname":"Select",
      "firstcolumnname":"Message",
      "items":[
         {
            "firstcolumnvalue":"this is a broadcast",
            "response":"1"
         },
         {
            "firstcolumnvalue":"Send to one user",
            "response":"2"
         },
         {
            "firstcolumnvalue":"This is the 3rd broadcast",
            "response":"3"
         },
         {
            "firstcolumnvalue":"Hello World!",
            "response":"4"
         },
         {
            "firstcolumnvalue":"Test one",
            "response":"5"
         }
      ],
      "name":"List of Sent Broadcasts"
   },
   "textcutmeta":[
      {
         "end":146,
         "start":0
      }
   ],
   "sender_type": "normal",
   "time": "7/11/23 6:07 PM",
   "time_iso": "2023-07-11 18:07:21.981",
   "ttl": "7/10/24 6:07 PM",
   "vgroupid":"4b32d7c8c6c37cc9e9506e9ed98ce37f0a96e1e45fcd4ca6f6d00c9d435d82e3"
}

The text message above is a sample, and does not include all of the optional fields for the meta data you may see in a message. The "tablemeta" object can contain the following objects:

Name Description
name This object is a string that is the name of the table
firstcolumnname This object is a string that is the name of the first column of the table
secondcolumnname This object is a string that is the name of the second column of the table. This is optional.
actioncolumnname This object is a string that is the name of the action column of the table. This is optional.
items This is an array of entries for the table.

The items is an array and can contain 0 or more entries for the table. Each entry in this table will contain the following objects:

Name Description
firstcolumnvalue This object is a string that is the value for the first column.
secondcolumnvalue This object is a string that is the value for the second column. This is optional.
response This object is a string that is the value to be returned to the bot when the list is selected. This is optional.

The "textcutmeta" is used to maintain some backwards compatability with Wickr clients that do not support lists. The "textcutmeta" is a list that identifies text characters that will be removed from the message text when the client supports table meta data. Typically the text that is removed is when the list information is in the message text, see the example above. The fields of the each of the "textcutmeta" entries identifies the starting index and ending index of what characters to cut from the message text. These values are 0 relative for the first character in the message text.

The following figure shows, on an Android client, how a list will be displayed:

drawing

Text Message Button Meta Data

As of the 5.81 release of WickrIO, support was added for buttons. Wickr clients that support these buttons will display the buttons when the message is received from the bot. There are several types of buttons, but selecting a button will perform a specific operation, including sending a message to the bot or sending your location to the bot. The following is an example of a text message with button meta data:

{
   "buttonmeta":[
      {
         "msgbutton":{
            "message":"/ack",
            "text":"/Ack"
         }
      },
      {
         "locationbutton":{
            "locationtype":0,
            "text":"/Ack with Location"
         }
      }
   ],
   "message":"this is a broadcast\n\nBroadcast message sent by: bnuser01@userworld.com\n\nPlease acknowledge message by replying with /ack",
   "message_id":"744dc0c0a75a11eb986e31ce44694ab3",
   "msg_ts":"1619529250.508240",
   "msgtype":1000,
   "receiver":"bnuser01@userworld.com",
   "sender":"bn0523_bcast_bot",
   "sender_type": "normal",
   "time": "7/11/23 6:07 PM",
   "time_iso": "2023-07-11 18:07:21.981",
   "ttl": "7/10/24 6:07 PM",
   "vgroupid":"4b32d7c8c6c37cc9e9506e9ed98ce37f0a96e1e45fcd4ca6f6d00c9d435d82e3"
}

The "buttonmeta" array contains all of the buttons associated with this text message. There are three types of buttons supported:

Name Description
msgbutton This is a normal button type that contains the text of the button and the message to be sent to the bot when the button is clicked.
locationbutton This is a location button that will perform a location based operation. Currently, the "locationtype" value of 0 means the client will send the location of the device to the bot when the button is selected. There will be other location type buttons supported in the future.

The "msgbutton" object will have the following objects:

Name Description
text This is the text of the button to be displayed
message This is the message that will be sent to the bot when the button is selected.

The "locationbutton" type will perform a location type of operation. The "locationbutton" object will have the following objects:

Name Description
text This is the text of the button to be displayed
type The type of location operation to perform. Value of 0 is to have the client send the location to the bot when the button is selected. Other location button types will have the option to start and stop location sharing, not implemented yet.

Wickr Data Retention Message Formats

As of version v6.18 the Wickr SAAS data retention bot (wickrio/bot-compliance-cloud) will include more information about conversation membership as well as network information for each of the users. Several new values will be added to the JSON to identify the user(s) associated with a message as well a information about each of the users. The new fields are:

Name Description
dstuser Used for direct messages to indicate the destination user
dstusers Used for group and room conversations to indicate the destination users
srcuser Used to indicate the sending user
members_accurate A boolean value that indicates the accuracy of the dstusers value

The dstuser and srcuser will contain the "name" and the "networkid" that the user is associated with (if it is known). The "networkid" may not be known when initial messages are recieved by the data retention bot for the associated user. The data retention bot will make a call to the server to retrieve the "networkid" value, subsequent messages received or sent to the user will contain the "networkid" value.

The dstusers is a list of destination users that is associated with a specific group/room conversation. The data retention bot will monitor received control messages for the conversations and maintain the associated conversation members. This list may not be accurate all the time, it depends on whether the data retention bot service has been active while the data retention bot has been receiving control messages that indicate the actual membership of the specific room/group. If the data retention bot has confidence of the accuracy for the specific conversation membership the "members_accurate" value will have a boolean true value, otherwise the value will be false. Any time the data retention service is disabled, all group/room conversations will have a "members_accurate" value of false until the data retention bot receives a conversation's control message with the membership list.

The following is an example of the message format for a direct message.

{
    "dstuser": {
      "name": "p5accuser@companyx.com",
      "networkid": "55512133"
    },
    "message": "Hello, how are you?",
    "message_id": "81b536d01cfb11eead5feb72a3629ba3",
    "msg_ts": "1688757703.357440",
    "msgtype": 1000,
    "receiver": "welcomebot",
    "sender": "pat02-02@amazon.com",
    "srcuser": {
      "name": "pat02-02@amazon.com",
      "networkid": "58271037"
    },
    "time": "7/7/23 7:21 PM",
    "time_iso": "2023-07-07 19:21:43.357",
    "ttl": "7/6/24 7:21 PM",
    "vgroupid": "9d37dda35211920010715db50bc1f9604841607ee5959a22a5b766669e22a9c2"
}

Please note that the "networkid" values are different, this version supports fedreated data retention. The "networkid" values are helpful to see that the data retention bot is capturing messages from other networks.

The following is an example of a message format for a room conversation message:

{
  "dstusers": [
    {
      "name": "userabc@amazon.com",
      "networkid": "33718250"
    },
    {
      "name": "pat02-02@amazon.com",
      "networkid": "58271037"
    },
    {
      "name": "web-bot",
      "networkid": "33718250"
    }
  ],
  "members_accurate": false,
  "message_id": "bf809620174d11eeb25b7fafcf29b6b4",
  "msg_ts": "1688133318.786757",
  "msgtype": 4005,
  "sender": "web-bot",
  "srcuser": {
    "name": "web-bot",
    "networkid": "33718250"
  },
  "time": "6/30/23 1:55 PM",
  "time_iso": "2023-06-30 13:55:18.786",
  "ttl": "7/30/23 1:55 PM",
  "vgroupid": "Sb2724449b46b1c6f5f03848d0c3e174f76602af53b513835f1cd09156242556"
}

Wickr Compliance/Data Retention Error Formats

This section describes the format of all the potential Wickr errors that are included in the Compliance bot and SAAS data retention bot's JSON in case of unanticipated errors.

Attachments' Errors

The errors related to attachements can occur while trying to download or saving/uploading the attachment. In both cases, the attachment is not retained by the bot and the error is written to the JSON.

The following is an example of an error when download of an attachment fails.

{
    "bor":"5/20/24 12:27 PM",
    "error":"Could not schedule download!",
    "message_id": "91a189c0cae911e79ec4eb19a763225b",
    "msg_ts": "1510849017.756174",
    "msgtype": 6000,
    "sender": "user003",
    "sender_type": "normal",
    "time": "7/11/23 5:22 PM",
    "time_iso": "2023-07-11 17:22:02.348",
    "vgroupid": "S3042f1bd04491c6f3732a871e27ab516a8d1534cc1e2d25c4e4869ce72e8541"
}

The following is an example of an error when saving to local disk or uploading to S3 of an attachment fails.

{
    ""bor":"5/20/24 12:27 PM",
    "error":"Error processing file. File was not saved to disk.",
    "file": {
        "filename": "picture.jpeg",
        "guid": "AD20D048-9B60-4F32-A691-2D4BE4152E58",
        "localfilename": "/opt/WickrIO/clients/compliancebot01/attachments/attachment_20171116111610865_picture.jpeg",
        "uploadedbyuser": "cn0623_01@amazon.com",
        "uploadedtimestamp": "7/11/23 5:22 PM"
    },
    "message_id": "91a189c0cae911e79ec4eb19a763225b",
    "msg_ts": "1510849017.756174",
    "msgtype": 6000,
    "sender": "user003",
    "sender_type": "normal",
    "time": "7/11/23 5:22 PM",
    "time_iso": "2023-07-11 17:22:02.348",
    "vgroupid": "S3042f1bd04491c6f3732a871e27ab516a8d1534cc1e2d25c4e4869ce72e8541"
}

Troubleshooting

These are troubleshooting suggestions associated with running the WickrIO gateway, clients and integrations. Also, troubleshooting issues you may run into when developing your own WickrIO integrations. This section will describe some possible issues you may run into while using the Wickr IO client and the associated services.

Enterprise, adding new bot does not show new password

We have found bug in the Enterprise WickrIO CLI that hides the new password when you are adding a bot for a new bot account. This problem occurs due to a bug in the debugging output, and will only happen when you turn debugging on (debug on) and then off (debug off).

Solution:

There is a fix for this issue in the 5.116.19.02 version of the Enterprise WickrIO docker images.

If you have an older version you can turn debugging off (debug off) then you should restart the docker image so that the issue is cleared from memory.

WickrIO bots stop sending after upgrading to 5.116.x version

Some customers have experienced this issue after attempting to deploy bot containers from the 5.92.x version directly to the 5.116.x version.

Solution:

Performing an incremental upgrade from 5.92.x to 5.112.x then 5.116.x seems to have fixed this problem. If you continue to encounter issues please contact support.

WickrIO Not working on Mac M1 hosts

The WickrIO docker images are not built to run on the Mac M1 hosts. In testing with the Mac M1 hardware we discovered an issue with an interaction with the exec() commands. This caused failures when trying to start a bot from the CLI.

Solution:

If you want to run the WickrIO docker images on Mac M1 hardware you should take the following steps:

WickrIO Fails startup due to directory permissions

When running the docker container on a Mac system, if you have not changed the write permissions on the /opt directory you will get a failure when starting the WickrIO docker container. This problem happens when running the WickrIO docker container after the ‘./start.sh’ step, you will see the following errors:

"QIODevice::write (QFile, "/opt/WickrIO/logs/WickrIOSvr.output"): device not open
terminate called after throwing an instance of 'zmq::error_t'
what(): No such file or directory
./start.sh: line 3: 7 Aborted WickrIOSvr"

This has only been seen on Mac systems. This happens when a user creates the /opt directory as root, and then runs container as a user.

Solution:

This is caused by a permission issue in the /opt directory. To fix the problem change the permissions of the /opt/WickrIO directory (or the name of the directory you created to be used by your installation) so it is writeable. The following command will fix this problem:

chmod 777 /opt/WickrIO

Host system running out of disk space

Your system is running out of space and you are unable to download and run a new docker container. This problem may occur if you do not remove old docker containers from your system.

Solution:

Wickr IO Client does not start

If your WickrIO client will not start, and none of the previous solutions work then try this possible solution. 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 command line interface of the WickrIO Docker container 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

If the WickrIO integration you are using requires the sending and/or receiving of files but you are not receiving or able to send files, then it is possible there is a problem with the date and/or time your system has currently set. The system Wickr uses to transfer encrypted files needs the host date and time to be accurate. If they are not accurate then the file transfer systems will fail to accept files.

Solution.

Make sure the host machine date and time is accurate, typically by installing and running an NTP service on your host system.

Docker Mounts denied Error

If ever getting the following error: "docker: Error response from daemon: Mounts denied: The path /opt/WickrIO is not shared from OS X and is not known to Docker."

Solution.

Restart Docker

Cannot load Docker image

If you receive the following error then you may have to make sure you have permissions to access the unix socket to communicate with the Docker engine:

docker: Got permission denied while trying to connect to the Docker daemon socket at unix:...

This link will help you set the appropriate permissions for your Docker user account.

Log and Output File locations

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 cannot 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.

To view logs in real time, run the following command from the /opt/WickrIO/clients/<client name>/logs directory:

tail -f *.output

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.

The Wickr IO Integrations can generate log information as well that can be very useful in diagnosing problems. These logs will be found in the integration directory associated with the Wickr IO Client Integration. For example, a broadcast bot with the client name of "test_bot" would use the following location:

/opt/WickrIO/clients/test_bot/integration/wickrio-broadcast-bot

Typical Wickr IO Integrations will write output to a file named "log.output" and error output will be written to a file named "err.output". Output in the "err.output" is an indication that the Integration has crashed.

Problems creating bots

If you are having issues creating WickrIO bots using the WickrIO command line interface, this procedure will help you view more detailed debugging information on the command line interface.

Solution.

To turn on debugging output modify the /opt/WickrIO/WickrIO.ini file. Be mindful of the host path versus the docker path.

Add the following to the ini file:

[configuration]
debugOutput=true

If the [configuration] exists already, just add the debugOutput line to that group.

The docker image tag that contains the support for this starts with the 5.68.14.03 tag. This should work for all docker images of this specific tag. For example, the latest version for bot-cloud is 5.116.18.01, for bot-enterprise is 5.116.18.01:

wickr/bot-enterprise:5.116.18.01
wickr/bot-enterprise-services:5.116.18.01

You will need to kill the docker image, and start it up with this new image. Also, should restart the docker image if you change the debugOutput. It is highly recommended to pause the bot clients before you kill a docker image, just in case.

When you run commands at the Wickr IO command line interface it will output alot of debug information with this option turned on.

Client and Integration Compatibility Issues

With the release of new Wickr IO Integrations and changes to the Wickr IO Addon APIs, it is possible there will be compatibility issues that will cause Integrations to not work. This may happen when adding new Integrations to an older Wickr IO Docker container. In this case using the latest version of the Docker container will fix this problem.

There are several ways to identify there is a compatibility issue causing the bots to stop working. Looking at the Integration's log or err output files may help identify this as a problem. For example, the Integration log files for the test_bot that uses the wickrio-broadcast-bot integration will be located in the following location:

/opt/WickrIO/clients/test_bot/integration/wickrio-broadcast-bot

If you see the following message in an integration's log file there is a compatibility issue:

UnhandledPromiseRejectionWarning: Error: Failed to create getClientState command. action 'get_state' unknown!

Another indication of an Integration compatibility issue is if the Integration version is out of date. This will be indicated by the "Needs Upgrade!" indication for a Wickr Client in the output of the command line interface "list" command. For example, the following output shows the current integration is out of date for the file_10_bot client.

Current list of clients:
#  Name                Status   Integration              Version  Events  Misc
========================================================================================
0  file_10_bot         Paused   wickrio-file-bot         5.38.15  0       Needs Upgrade!
1  example_10_bot      Running  wickrio-example-app      5.47.13  5
2  web_10_bot          Paused   wickrio_web_interface    5.47.13  0

This doesn't always mean there is an issue with the client, but if you are having issues with the Integration associated with this client then performing an upgrade on it may fix the problem.

Solution.

It is highly recommended to use the latest release of the Wickr IO Docker image(s). Using the latest version of the Wickr IO Docker container should fix most of these compatibility issues.

If the integration needs to be upgraded then running the "upgrade" command on the command line interface may solve the problem as well. Make sure the client is in the paused state.

If you need to contact Wickr support it will help to have the version number of the Docker container before doing so. You can get the version number on the Wickr IO command line interface, with the "version command. Newer versions of the Wickr IO Docker image will also show the version numbers of the integrations, output when you run the "list" command. When dealing with Integration issues it will be helpful to have the version numbers for the integrations as well. These can be found in the package.json files for the integration.

When you start using version 5.47 of the WickrIO Docker images you will need to make sure you use the appropriate version of node. This is dependent on which version of the wickr-addon you are using. If you are using version 5.44.x then you should be okay, but if you are using version 5.38.x or older then you may have a problem. The version 5.47 version and new of WickrIO will support versions 8.17.0 and 10.18.1 of node. If you need to use the version 8 of node then there are several ways to make sure that is selected. You can change the start.sh file to be like the following:

#!/bin/bash
if [ -f "/usr/local/nvm/nvm.sh" ]; then
  . /usr/local/nvm/nvm.sh
  nvm use 8.17.0
fi
npm start

The nvm command will be used to select which version of node will be running in your integration's context.

Multiple instances of same Integration on a Docker image

There is a known issue with running multiple instances of the same Integration on a Docker image. The issue is associated with the name associated with the Integration. The NPM process management cannot handle multiple instances of the same name. An upcoming release will fix this issue.

Solution.

If you cannot wait for a fix to this problem then there is a manual process you can perform to allow multiple instances to run. By changing the names associated with each of the Integrations on your system, that are of the same Integration type. You will have to edit the processes.json file in the Integration's directory, for example:

/opt/WickrIO/clients/test_bot/integration/wickrio-broadcast-bot/processes.json

Change the "name" value to be unique, we suggest you just add the name of the associated Wickr IO Client to the name (which has to be unique within a Docker container), for example:

      "name": "WickrIO-Broadcast-Bot_test_bot",

You will need to pause and restart each of the integrations to make this work.

Too many bot devices

Bot clients do not remove old devices when starting up. It is possible that if you move a bot many times to different machines you may reach the limit of 50 devices. When moving the bot to different devices or re-creating a bot it will be created with a new device. It is possible you will reach the limit of 50 devices. When you do reach that limit it is possible the bot will not work anymore.

Solution.

As of version 5.81 there is a manual way to clear out old bot devices. To do this you will need to modify the bot's .ini file. This is a one shot setting that will be used by the bot client to clear out old devices. The one shot setting will contain a value which is the number of seconds that the bot device has since logged in. If the bot device's last login was greater than that number seconds it will be suspended. The following is a sample of what you can put in the bot's .ini file:

[oneshot]
suspenddeviceafterseconds=120

In the example, the number of seconds is 120 (or 2 minutes). This will NOT suspend the current device, just all devices that have not logged in within the number of seconds. The .ini file is located in the client directory assocaited with the bot client, for example:

/opt/WickrIO/clients/<botname>/WickrIO<botname>.ini

Bot Provisioning Failures

When adding a bot client to a docker image some times there are issues with the provisioning step for the client. This can happen for new and existing clients, when adding the bot client. Before version 5.81, provisioning failure may return an error code which was not very helpful in determining what went wrong. The following is a list of those error codes and what they mean:

Code Definition
0 Successfully provisioned the client
1 User already exists, which usually is success
2 User was not found. Server does not recognize the user
3 Bad credentials entered, the password is not valid
4 General error for provisioning failures, check the logs
5 The user or devices is suspended
6 The number of login attempts has been exceeded
7 User was created but the database already exists on the system

Solution.

The 5.81 release has exposed the provisioning logging to help diagnose these issues better. This log will be found the the following file: /opt/WickrIO/WickrIOProvisionLog.output

Network Timeouts

If your bot is failing to interact with the backend servers and the logs are showing time errors, we have a way to increase the timeout for the network requests. This is not necessarily a solution to your problem, but is a way to increase the timeout and eliminate this as a reason for the connection issues.

Solution.

To increase the network timeouts you will need to modify the ini file for the bot client. The /opt/WickrIO/clients//WickrIO.ini is the appropriate file.

Add the following to the ini file:

[networksetup]
requesttimeout=<some value in seconds>
userrequesttimeout=<some value in seconds>

You will need to restart the bot after you have added this to the ini file.

Upgrading WickrIO

The WickrIO bots do not automatically upgrade, like a Wickr client does. You will need to periodically and manually upgrade the bots to make sure you have the latest software.

Solution.

The following are the steps you will perform to upgrade a WickrIO docker image and the associated bots. After this part a sample output will be shown:

docker kill MyBotName
docker rm -f MyBotName

docker run -v /opt/MyBotName:/opt/WickrIO -p 4001:4001 -d --restart=always --name="MyBotName" -ti wickr/bot-cloud:latest

The following is sample output from upgrading an old WickrIO bot running version v4.64.9.3, with a wickrio_web_interface bot. The version being upgraded to is the 5.116.18.01 version/tag.

Enter command:list
Current list of clients:
 client[0] old-test-bot, State=Running, Integration=wickrio_web_interface
Enter command:version
version: v4.64.9.3
Enter command:pause 0
Do you really want to pause the client with the name old-test-bot (default: yes):yes
Enter command:list
Current list of clients:
 client[0] old-test-bot, State=Paused, Integration=wickrio_web_interface
Enter command:read escape sequence
ubuntu@mybothost:~$ 
docker kill VeryOldBot
ubuntu@mybothost:~$ 
docker rm -f VeryOldBot
ubuntu@mybothost:~$ 
docker run -v /opt/VeryOldBot/WickrIO:/opt/WickrIO -p 4444:4444 -d --restart=always --name="VeryOldBot" -ti wickr/bot-cloud:latest
Unable to find image 'wickr/bot-cloud:latest' locally
5.116.18.01: Pulling from wickr/bot-cloud
4bbfd2c87b75: Already exists 
d2e110be24e1: Already exists 
889a7173dcfe: Already exists 
20ca454721b1: Already exists 
02c4b05cb492: Already exists 
1c731f8c023d: Already exists 
fcd34fc70cfe: Already exists 
b1fceb668295: Already exists 
68307b81514b: Pull complete 
b9f674e60307: Pull complete 
e4fd99322c5a: Pull complete 
3fdf8c473cd1: Pull complete 
9dd71d5d554c: Pull complete 
225a5f4a7590: Pull complete 
Digest: sha256:05f7d0df8a488f7e325845423d13ebda95b1967b7b00203fe2425ae35e43480f
Status: Downloaded newer image for wickr/bot-cloud:latest
71bb0c85bc4c4c92db604136ad9f64e62d9769debcfccb656794037b4dc06d44
ubuntu@mybothost:~$ docker attach VeryOldBot 

Updating integration software version numbers
Updating integration software version numbers
Searching NPM registry
Searching NPM registry

Welcome to the WickrIO Console program (v5.116.18.01)

Current list of clients:
#  Name          Status  Integration            Version  Events  Misc
======================================================================
0  old-test-bot  Paused  wickrio_web_interface  1.1.2    2       Needs Upgrade!
Enter command:
Enter command:upgrade 0
Upgrading from version 1.1.2 to version 5.82.2
Okay to proceed? (default: yes):yes
Copying wickrio_web_interface software

Upgrading wickrio_web_interface software
Installing wickrio_web_interface software
Installing
Installing
Begin configuration of wickrio_web_interface software for old-test-bot
Now using node v12.20.2 (npm v6.14.11)
adminsOptional=false
adminsOptional=false
Finished Configuring package!
Finished Configuring forever!
Finished Configuring!
Enter command:list
Current list of clients:
#  Name          Status  Integration            Version  Events  Misc
======================================================================
0  old-test-bot  Paused  wickrio_web_interface  5.82.2   2       
Enter command:start 0
Preparing to start the client with the name old-test-bot
Do you really want to start the client with the name old-test-bot:yes
Enter command:list
Current list of clients:
#  Name          Status   Integration            Version  Events  Misc
=======================================================================
0  old-test-bot  Running  wickrio_web_interface  5.82.2   3       
Enter command:

Changelog

All notable changes to this project will be documented in this file.

[6.24.06] - 2023-09-28

[6.16.20] - 2023-07-06

[6.16.19] - 2023-07-05

[6.11.05] - 2023-04-27

[5.116.19] - 2023-02-16

[5.116.19] - 2023-02-14

[5.116.18] - 2022-12-08

[5.116.13] - 2022-11-08

[5.112.12] - 2022-09-14

[5.92.07] - 2022-04-07

[5.92.06] - 2022-03-16

[5.92.03] - 2021-10-06

[5.88.06] - 2021-08-24

[5.81.13] - 2021-07-24

[5.81.13] - 2021-07-20

[5.81.11] - 2021-06-08

[5.68.14] - 2021-02-09

[5.68.14] - 2020-12-28

[5.64.14] - 2020-11-19

[5.64.11] - 2020-10-07

[5.62.5] - 2020-09-2

[5.62.4] - 2020-08-27

[5.60.4] - 2020-08-12

[5.60.2] - 2020-08-07

[5.60.2] - 2020-07-29

[5.56.15] - 2020-06-29

[5.47.13] - 2020-02-27

[5.38.23] - 2020-01-07

[5.38.17] - 2019-10-22

[5.38.14] - 2019-10-10

[5.8.1] - 2019-02-27

[5.4.7] - 2019-02-27

Release Notes

Version 6.34.05.01

The 6.34.05.01 release of the bot-cloud and bot-enterprise images are focused on the changes described below. The 6.34.02.01 bot-compliance-cloud images include the File Management and SDK changes described below.

Support File Management feature message formats

The Wickr control message formats were changed to support the Wickr File Management feature. The 6.34 versions of the WickrIO and WickrIO Compliance releases support this new message format. The Data Retention / Compliance bots will also download files that are referred to in these modified control messages. Details of these updated control messages will detailed in the appropriate WickrIO documentation.

Bug Fix: Broadcast Bot security group selection failed

Some Wickr clients have added spaces padding the security group selection which broke the broadcast bot processing of that string. Added coding in the broadcast bot to trim the padding off of the response string.

Bug Fix: Bug fixes inherited from lower layer SDK

Several bug fixes were made to the SDK that bots use to interact with the Wickr servers for login and messaging services. Changes made to improve room membership for room conversations. Changes made to improve the Wickr client record information more reliable. Removed some code associated with legacy message sends, which is not used any more.

Version 6.32.04.02

The 6.32.04.02 release is a bug fix release and focused on the following major changes:

Bug Fix: Airgap version contacting NPM Registry

Some code was found to still have references to the default NPM registry (registry.npmjs.org). Changes were made so the Airgap version does not reference any NPM registry.

Bug Fix: Read receipts not working for Broadcast Bot

Software was found to not be decoding read receipt API call responses correctly. Changes were made to fix this.

Bug Fix: Registration failures

A race condition was found which caused initial registrations to fail.

Bug Fix: Read receipts never time out

Changes were made to stop sending requests for read receipt status after one week for broadcasts.

Version 6.24.06.02

The 6.24.06.02 release is focused on the following major changes:

Bug Fix: Conversations not restored when creating new instance of bot

Found issue where Wickr conversations were not being restored correctly for new instances of a bot. This issue would present itself if you created a new instance of a bot and then tried to send a message from the bot to a secure room or group conversation. The bot would not have restored the connection list and would not have a record of the conversation.

Bug Fix: Downloading files in multi-domain environments

Found issue where the downloading of files from clients in different domains was not working for bots. This change will make sure files are downloaded when a bot downloads a file from a Wickr client from another federated domain.

Bug Fix: Handle files with long file names

When a bot receives a file with a long file name, approximately 255 characters, it adds some information to the filename which may make the file name larger than 255 characters. The bot would end up dropping the file in this case, due to operating system limitations. This fix will remove any characters at the end of the file name to keep the length under 255 characters.

Feature to send events to AWS SNS Topic

To improve the health capabilities of Wickr bots we added the ability to send events generated on a bot to an AWS SNS Topic. This topic can be used to send events to an email address or any other endpoint that can subscribe to events pushed to the defined SNS Topic. To use this feature there are environment variables (to be defined in the WickrIO documentation) that identify the AWS SNS Topic.

Created new API to set avatar for the bot client

This new bot API allows bot developers to set the avatar associated with the bot client. Details of this API will be defined in the WickrIO documentation.

Version 6.18.19.02

The 6.18.19.02 release is focused on the following major changes:

Continue using AWS ECR to host Docker images

We are starting to transition hosting our Wickr bot docker images on AWS ECR. These are the AWS ECR repositories used to host the Wickr bot docker images:

public.ecr.aws/x3s2s6k3/wickrio/bot-cloud public.ecr.aws/x3s2s6k3/wickrio/bot-enterprise public.ecr.aws/x3s2s6k3/wickrio/bot-compliance-cloud

We will continue to host production docker images on DockerHub for the next couple of releases. These are the existing DockerHub repositories we are using:

wickr/bot-cloud wickr/bot-enterprise wickr/bot-compliance-cloud

The “latest” tag will be set to the 6.18.19.02 release when it has been exposed to the public.

Two-way data retention support

The Wickr bot clients will support running with federated networks that are running data retention. When sending messages to clients in federated data retention active the bot client will also send the message to the appropriate data retention bot(s).

Data retention bots support additional user information

The SAAS data retention bot (bot-compliance-cloud) will output additional information about the users associated with a message. This new information includes the network ID as well as room membership.

NOTE: Some of this information is not immediately available to the data retention bot. For the network ID the data retention bot will need to interact with the server to get the information. The network ID for a user may not be known by the data retention bot until the server responds with that information. For the room membership information the data retention bot must capture room membership control messages that contain the current room membership. The data retention bot cannot not show a valid list of room conversation members unless it see this information. In this case an indication of the membership validity will be included with the message information.

Version 6.16.19.01

The 6.16.16.01 release is focused on the following major changes:

Continue using AWS ECR to host Docker images

We are starting to transition hosting our Wickr bot docker images on AWS ECR. These are the AWS ECR repositories used to host the Wickr bot docker images:

public.ecr.aws/x3s2s6k3/wickrio/bot-cloud
public.ecr.aws/x3s2s6k3/wickrio/bot-enterprise

We will continue to host production docker images on DockerHub for the next couple of releases. These are the existing DockerHub repositories we are using:

wickr/bot-cloud
wickr/bot-enterprise

The “latest” tag will be set to the 6.16.19.01 release when it has been exposed to the public.

Update image from Ubuntu 18.04 to Ubuntu 20.04

The Ubuntu operating system version was upgraded to Ubuntu 20.04 in all Wickr bot docker images.

Fix message send error issues

If the bot attempted to send a message to a user and that message failed to send the indication to the bot software was not indicated. The bot software would get into a frozen state and not able to proceed. This was seen with broadcasts to groups of users where a user account may be in a bad state where the bot would fail to send to it. The bot would be stuck and not able to function. This fix handles the error cases appropriately, and in the case of the broadcast bot the /report command will show the failed users.

Support for Wickr Multi-Region

All Wickr bot images will support bot clients created in other AWS regions, for example ca-central-1.

Fix Broadcast bot not receiving messages from users

If the bot sends a message to a user, before the user has sent a message to the bot, the bot software will not process the message. The creation of the user record in the database was not attaching to get message indications if the user record was created by the bot sending the initial message for that user. This can happen, for example, when setting up a broadcast bot with administrators. The broadcast bot would start by sending a welcome message to all of the administrators. The user record was not created to receive the incoming message indications, so the broadcast bot would not respond. In those cases restarting the broadcast bot would fix the indication for those users. There may be other situations where this happens.

More user-friendly bot startup failure indications

If a bot fails to startup the logs indicate this using an error code. To help indicate the actual reason for the failure a failure string will also be output to the logs.

Fix issue where bot startups more than 5 attempts will stop trying to start

If a bot fails to start more than 5 times, normally the bot will not attempt to start again without some user intervention. In some cases, the bot service will keep trying to start the bot which could lead to the bot client being suspended or the bot docker image CPU usage elevating too high. The change will keep the bot service from retrying to start the bot. The bot CLI will also indicate that there was an error in the Misc column. The CLI will also prompt the user to make sure they want to start the bot, if it was stopped due to it not starting more than 5 times.

Certain control messages did not indicate the filevault information associated with saved links and files, specifically when new users were added to rooms.

Version 6.11.05.01

This version is an update for all bots with the move from the forever process manager to the WPM2 process manager as well as more specific updates to the broadcast bot, compliance bot, bot client, and wickrio-docs. The 6.11.05.01 release is focused on the following major changes:

Using AWS ECR to host Docker images

We are starting to transition hosting our Wickr bot docker images on AWS ECR. These are the AWS ECR repositories used to host the Wickr bot docker images:

public.ecr.aws/x3s2s6k3/wickrio/bot-cloud
public.ecr.aws/x3s2s6k3/wickrio/bot-enterprise

We will continue to host production docker images on DockerHub for the next couple of releases. These are the existing DockerHub repositories we are using:

wickr/bot-cloud
wickr/bot-enterprise

The “latest” tag will be set to the 6.11.05.01 release when it has been exposed to the public.

Move from Forever process manager to WPM2

This change affects all bots as they were all using the forever process manager. WPM2 is an internal project that can be found on NPM at: https://www.npmjs.com/package/wpm2

With WPM2 we rely on the use of PID files to keep track of the running process and the ability to kill the running process based on the PID (process ID) and WPM2 handles keeping the bot running and ending the process gracefully when we go to pause or restart the bot. Here is an example of what the new package.json scripts look like: 

"restart": "kill $(cat $(cat pidLocation.json)) && nohup wpm2 start --no-metrics ./wpm.json >>wpm2.output 2>&1 & echo $! > $(cat pidLocation.json)",
"start": "nohup wpm2 start --no-metrics ./wpm.json >>wpm2.output 2>&1 & echo $! > $(cat pidLocation.json)",
"stop": "kill $(cat $(cat pidLocation.json))",

Performance improvement for large broadcast

Performance has been improved for large broadcasts in the broadcast bot. The pre-send preparation of the broadcast bot will see an obvious increase in performance for large broadcasts.

Updating the Support email in all the bots

In any bots and documentation that made reference to Wickr support we were using the old support@wickr.com email. All these instances have been updated to the new support email: wickr-support@amazon.com.

Updated JSON timestamp

An ISO format timestamp has been added for message JSON. This was done in the compliance bot and all messages passed to bots and integrations.

Mutex Lock Enhancements

Mutex lock enhancements have been made to reduce the possibilities of database lockups.

Version 5.116.19.02

This version is a bug fix release.

Fix for Enterprise updated password not showing

This version of the enterprise docker image(s) will fix an issue where the changed password was not being shown if you run the "debug on" command and then the "debug off" command on the CLI. The debug state was not being set correctly to off when the "debug off" command was performed, which caused a problem processing the messages from the provisioning software. The debugging output was stopped but the internal state was not updated appropriately.

Version 5.116.18.01

This version is an update for the wickr/bot-enterprise and the wickr/bot-cloud Docker images. The 5.116.18.01 release is a patch release. Please see the Version 5.116.13.01 Release notes for details of the 5.116 version. This version includes the following two changes:

Fix for Missing Rooms

A bug was detected when upgrading to the 5.112 or 5.112.13.01 releases of the WickrIO Bots, which made secure room and group conversations not visible to bots/integrations. These conversations were not deleted they were not being made visible to the bot APIs. This release fixes these issues.

Fix for upgrades from old bot versions

This issue was seen when an upgrade was performed from an old version of the WickrIO docker image, specifically 5.62.05.02. The issue was caused by a new database field not being added during the migration from the old version to the recent version (i.e. 5.112 or 5.116).

To identify if your bot is experiencing this issue, the log files will contain a failure message when ever the bot receives a message. The failure message will contain the following text and can be seen in the WickrIO.output file:

BULK INSERT MESSAGE: Failed, can't prepare insertQuery

After installing the 5.116.18.01 version this issue should be fixed.

Fix to address high CPU

Several customers have reported WickrIO bots randomly running at high CPU rates, and staying at that rate. We have reproduced the problem. This patch release contains a change that has shown to eliminate this problem. If you have seen this issue and want to confirm it is the same CPU issue please do the following:

docker exec -ti <dockerimagename/id> bash

NOTE: If you continue to have the CPU issue after installing this patch, please contact support.

Fix for SAAS Data Retention Network Transmit Failures

The 5.116.13.01 wickr/bot-cloud image would have transmit failure when operating in a SAAS Data Retention network. This version will fix that problem.

Version 5.116.13.01

This version is an update for the wickr/bot-enterprise and the wickr/bot-cloud Docker images. The 5.116.17.01 release is focused on the following two major changes:

Support for Mac M1 Host

Changes made to support running on Mac M1 machines. Older versions of the WickrIO Docker images will not run on the Mac M1 systems.

If you want to run the WickrIO Docker image(s) on a Mac M1 machine, you will have to start the Docker images with the

—platform=linux/amd64 option

We do not recommend running production bots on Mac M1 hardware at this point. Using Mac M1 systems to do development should be fine.

Support for Node 16

As of the 5.116.17.01 version, all of the Docker images and software are updated to use node version 16. Node 12 is not supported anymore and will NOT be part of the 5.116.17.01 Docker images. All of the bots and integrations shipped with the 5.116.17.01 Docker images have been updated to use Node 16. When you update your WickrIO Docker images to the 5.116.17.01 version, you will need to upgrade all bots and integrations to use the latest versions. Any bots that use Node 12 will not work when the 5.116.17.01 version is installed. The bot client will operate and show that it is running, but the bot/integration software will not be able to start up since they will be looking for Node 12. The 5.116.17.01 WickrIO Docker images contain upgrades for all of the supplied bots.

Custom Bots/Integrations

This section applies to you if you have or are developing custom Node-js bots. This does not apply to anyone using the REST APIs of the wickrio_web_interface bot.

If you are creating custom bots/integrations you will need to use the latest 5.113 version of the wickrio-bot-api or the the latest 5.113 version of the wickrio_addon (which ever is appropriate for your custom bot). For example, if you are using the wickrio-bot-api make sure the following dependency is in your package.json file:

"wickrio-bot-api": "5.113.x"

Or if you are using the wickrio_addon package make sure the following dependency is in your package.json file:

"wickrio_addon": "5.113.x"

Installation Process

We recommend that before you install the new 5.116.17.01 version of the appropriate Docker image that you pause all of the bots running on each Docker instance. Using the WickrIO CLI you should see your bot(s) in the "Paused" state.

Enter command:read escape sequence
ubuntu@ip-172-31-25-75:~$ docker attach bot_test_prod
Enter command:
Enter command:list
Current list of clients:
# Name Status Integration Version Events Misc
0 dev-test-bot Paused wickrio-compliance-bot 5.112.1 53 
Enter command:

After you start the Docker image with the 5.116.17.01 version the CLI will show that your bot has a needed upgrade available:

Welcome to the WickrIO Console program (v5.116.17.01)

Current list of clients:
# Name Status Integration Version Events Misc
0 dev-test-bot Paused wickrio-compliance-bot 5.112.1 43 Needs Upgrade!

Please make sure you upgrade each of your bots to the latest version. The following is a sample of what upgrading a compliance bot would look like. The software will be upgraded and you will be prompted to enter the configuration information for the bot (previously configured values are shown in the parenthesis).

Enter command:upgrade 0
Upgrading from version 5.112.1 to version 5.114.1
Okay to proceed? (default: yes):
Copying wickrio-compliance-bot software

Upgrading wickrio-compliance-bot software
Installing wickrio-compliance-bot software
Installing
Begin configuration of wickrio-compliance-bot software for dev-test-bot
Now using node v16.17.1 (npm v8.15.0)
Log level set to info
Max file size set to 2k
Max number of files set to 3
Creating logger
Logger created
adminsOptional=false
adminsOptional=false
 Use new file save process [yes/no]: (no) :
 Memory can reach 100% if the bot isn't restarted periodically. Please enter a time in minutes to restart the service [24hrs = 1440]: (1440) :
Finished Configuring package!
Finished Configuring forever!
Finished Configuring!
Enter command:

After upgrading your Docker image and bots you can start the bots.

FAQ

Question: Will my bots be running if I don't want to upgrade?
Answer: Your bots will continue to run if you do not upgrade to the 5.116.17.01 version. However, we recommend upgrading to receive the latest security updates.

Question: If I run into problems with the 5.116.17.01 version can I downgrade my installation?
Answer: Yes you can. The process is very similar to how you upgraded to the 5.116.17.01 version. Instead you will do the following:

Feedback Welcome

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