HOWTOs

Use console client

Local operations (no network communication)

Encrypt

.\Threema.MsgApi.Console.exe -e <privateKey> <publicKey>

Encrypt standard input using the given sender private key and recipient public key. Prints two lines to standard output: first the nonce (hex), and then the box (hex).

Decrypt

.\Threema.MsgApi.Console.exe -d <privateKey> <publicKey> <nonce>

Decrypt standard input using the given recipient private key and sender public key. The nonce must be given on the command line, and the box (hex) on standard input. Prints the decrypted message to standard output.

Hash Email Address

.\Threema.MsgApi.Console.exe -h -e <email>

Hash an email address for identity lookup. Prints the hash in hex.

Hash Phone Number

.\Threema.MsgApi.Console.exe -h -p <phoneNo>

Hash a phone number for identity lookup. Prints the hash in hex.

Generate Key Pair

.\Threema.MsgApi.Console.exe -g <privateKeyFile> <publicKeyPath>

Generate a new key pair and write the private and public keys to the respective files (in hex).

Derive Public Key

.\Threema.MsgApi.Console.exe -p <privateKey>

Derive the public key that corresponds with the given private key.

Network operations

Send Simple Message

.\Threema.MsgApi.Console.exe -s <to> <from> <secret>

Send a message from standard input with server-side encryption to the given ID. 'from' is the API identity and 'secret' is the API secret. Returns the message ID on success.

Send End-to-End Encrypted Text Message

.\Threema.MsgApi.Console.exe -S <to> <from> <secret> <privateKey>

Encrypt standard input and send the message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

Send End-to-End Encrypted Image Message (deprecated, use the File Message type instead)

.\Threema.MsgApi.Console.exe -S -i <to> <from> <secret> <privateKey> <imageFilePath>

Encrypt standard input and send the message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

Send End-to-End Encrypted File Message

.\Threema.MsgApi.Console.exe -S -f <to> <from> <secret> <privateKey> <file> [thumbnail]

Encrypt the file (and thumbnail) and send a file message to the given ID. 'from' is the API identity and 'secret' is the API secret. Prints the message ID on success.

ID Lookup By Email Address

.\Threema.MsgApi.Console.exe -l -e <email> <from> <secret>

Lookup the ID linked to the given email address (will be hashed locally).

ID Lookup By Phone Number

.\Threema.MsgApi.Console.exe -l -p <phoneNo> <from> <secret>

Lookup the ID linked to the given phone number (will be hashed locally).

Fetch Public Key

.\Threema.MsgApi.Console.exe -l -k <id> <from> <secret>

Lookup the public key for the given ID.

Fetch Capability

.\Threema.MsgApi.Console.exe -c <id> <from> <secret>

Fetch the capability of a Threema ID

Decrypt and download

.\Threema.MsgApi.Console.exe -D <id> <from> <secret> <privateKey> <messageId> <nonce> [outputFolder]

Decrypt a box (box from the stdin) message and download (if the message is a image or file message) the file(s) to the defined directory

Create a Connection

	string gatewayId = "*MYGWID1";
	string secret = "SECRET_OF_MY_GATEWAY_ID";

	//TODO: implement your own public key store, or use the
	//SQLite implementation "PublicKeyStoreDb", to get better performance.

	APIConnector apiConnector = new APIConnector(gatewayId, secret, null);
		
		

Send a Text Message to a Threema-ID (Basic Mode)

	//create the connection
	string threemaId = "ABCD1234";
	string textMessage = "Basic Mode Message";

	string messageId = apiConnector.SendTextMessage(threemaId, textMessage);
		

Send a Text Message to a Threema-ID (End-To-End Mode)

	//create the connection
	string threemaId = "ABCD1234";
	string textMessage = "End-To-End Encrypted Message";
	byte[] privateKey = DataUtils.ReadKeyFile("/path/to/my/private.key", Key.KeyType.PRIVATE);

	E2EHelper e2EHelper = new E2EHelper(apiConnector, privateKey);
	string messageId = e2EHelper.SendTextMessage(to, textMessage);
		

Send a File Message to a Threema-ID (End-To-End Mode)

	//create the connection
	string threemaId = "ABCD1234";
	var privateKey = DataUtils.ReadKeyFile("/path/to/my/private.key", Key.KeyType.PRIVATE);
	FileInfo fileToSend = new FileInfo("/path/to/my/pdf.pdf");
	FileInfo thumbnailFileToSend = new FileInfo("/path/to/my/pdf-thumbnail.jpg");

	E2EHelper e2EHelper = new E2EHelper(apiConnector, privateKey);
	var messageId = e2EHelper.SendFileMessage(threemaId, fileToSend, thumbnailFileToSend);
		

More examples

For more code examples please refer to the E2ETest.cs source file of the Threema.MsgApi.Test project inside the .NET solution.

Troubleshooting

General build or runtime errors

To solve potential installation problems, please make sure you have installed the following:

• .NET Framework 4.8 Runtime https://dotnet.microsoft.com/en-us/download/dotnet-framework/net48
• Microsoft Visual C++ Redistributable Package https://aka.ms/vs/17/release/vc_redist.x64.exe

Missing platform components: libsodium.dll

If upon running your project an error is shown stating that platform components are missing (e.g., “libsodium”), make sure you are building against a supported system architecture and the appropriate libsodium.dll (can be found in the lib folder) is present in your chosen architecture’s bin folder.
Alternatively, you may copy the appropriate libsodium.dll library into a directory available from your PATH or System32 folder. Text message sent with wrong characters.
This could happen if the output of the Windows Console is not UTF-8 encoded.

Configure encoding (UTF8) for Windows Console.

PowerShell (powershell):

$OutputEncoding = [console]::InputEncoding = [console]::OutputEncoding = New-Object System.Text.UTF8Encoding

Command Prompt (cmd):

chcp 65001