How to generate a new key pair and send a message
1. Install JavaIf you don't have a Java runtime installed yet, go to java.com to download one for your platform.
2. Download the Java API Tool
3. Unzip the fileOn Mac/Linux, run the following command in a terminal window:
4. Generate a keypair by running the toolOpen a shell (on Windows open the command line) and go to the directory where you have extracted the ZIP.
Create a new private and public key by typing the following command:
A new key pair will be generated. The private key will be saved in privateKey.txt and the public key in publicKey.txt. Both keys are formatted in hexadecimal with a prefix that indicates the key type.
java -jar threema-msgapi-tool.jar -g privateKey.txt publicKey.txt
IMPORTANT: Create a backup (or preferrably multiple backups) of your private key! If you lose it, your custom Threema ID will be unusable. We have no way to recover lost private keys for you, and it is also not possible to assign a new key to an existing ID.
5. Request custom Threema ID and submit keyLog in to your profile on the Threema Gateway website, click on "ID" in the navigation bar and then "Request Threema ID".
Choose End-to-End mode, enter the desired ID, and copy & paste the public key from the publicKey.txt file.
6. Wait for review
Wait until your custom Threema ID has been reviewed and accepted. As this is a manual process, it may take several days.
When your ID has been accepted, you will receive an API secret for authentication with the service.
7. Send a message
For the example below, let's say you want to send a message to the ID ECHOECHO*. Your custom ID is *MYAPIID and the API secret is df4oUM7eYei3kEAV.Before you can encrypt and send your message, you need to retrieve the recipient's public key. Type the following command to do that:
The tool will print the public key of the ID ECHOECHO:
java -jar threema-msgapi-tool.jar -l -k ECHOECHO "*MYAPIID" df4oUM7eYei3kEAV
You can store this public key so you don't have to look it up every time you want to send a message, and you can also verify it independently by comparing it with the contents of the recipient's public QR code.
Now encrypt and send your message by typing the following command:
Your private key will be read from the file that you generated earlier on. The public key of the recipient can be passed directly on the command line.
echo "This is my message." | java -jar threema-msgapi-tool.jar -S ECHOECHO "*MYAPIID" df4oUM7eYei3kEAV privateKey.txt
* Please note: the ECHOECHO ID does not return messages from API IDs, so you will not get anything back.