How to generate a new key pair and send a message

1. Installation

Install PHP 5.4 or later:
For better encryption performance, install the libsodium PHP extension. This step is optional; if the libsodium PHP extension is not available, the SDK will automatically fall back to (slower) pure PHP code for ECC encryption.
To install the libsodium PHP extension:
pecl install libsodium
Then add the following line to your php.ini file:

3. Unzip the file

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

4. Generate a keypair by running the tool

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:
php threema-msgapi-tool.php -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.
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 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." | php threema-msgapi-tool.php -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.