This guide provides documentation for Wickr IO Integrations. If you're using AWS Wickr, see AWS Wickr Administration Guide.

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:

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:

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.

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.

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.

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.

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:

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

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

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 are described in Wickr message formats.

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:

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.