How to generate a new key pair and send a message

1. Installation

Install PHP 8.1 or later: https://php.net/manual/en/install.php. No further installation steps should be required (except for Windows users).

Windows Users

Please make sure that a suitable OpenSSL version is present on your system (it should be).

Furthermore, you should verify that extension=php_sodium.dll is present inside the php.ini file (use either php.ini-development or php.ini-production as a template).

Make sure the config does not contain any errors by checking the output of php --ini.

Afterwards, please verify the output of php -i and make sure the line sodium support => enabled is present or php -m to see whether the "sodium" module is loaded.

Please note that OpenSSL can be extremely slow on Windows which might excessively slow down cryptographic operations.

2. Download the PHP API Tool

3. Unzip the file

On Mac/Linux, run the following command in a terminal window: 
unzip threema-msgapi-sdk-php-2.3.1.zip
or
On Windows, right-click on the threema-msgapi-sdk-php-2.3.1.zip file and select “Extract All...”. A dialog box opens; enter a location and click “Extract”.

4. Generate a keypair by running the tool

IMPORTANT!

Create a backup (or preferably 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.

This means that after requesting an E2E Gateway ID with a public key, if the corresponding private key is lost, nobody will ever be able to use this Gateway ID again!

Open 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: 
./threema-msgapi-tool -g privateKey.txt publicKey.txt
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.

5. Request custom Threema ID and submit key

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

Encrypt and send your message by typing the following command: 
echo "This is my message." | ./threema-msgapi-tool -S ECHOECHO "*MYAPIID" df4oUM7eYei3kEAV privateKey.txt
Your private key will be read from the file that you generated earlier on.
* Please note: the ECHOECHO ID does not return messages from API IDs, so you will not get anything back.