Threema Message API

As a developer, you will find here all necessary information and source code to successfully integrate Threema Gateway in your environment. Threema does not provide a graphical user interface for Threema Gateway. The Message API is an interface that can be used from within customer-specific software to send and receive messages via Threema Gateway.

Download PHP API Tool (SDK & Documentation)

Installation

Install PHP 5.4 or later: http://php.net/manual/en/install.php
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:
extension=libsodium.so

Use console client

Local operations (no network communication)

Encrypt

threema-msgapi-tool.php -e <privateKey> <publicKey>

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

Decrypt

threema-msgapi-tool.php -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-tool.php -h -e <email>

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

Hash Phone Number

threema-msgapi-tool.php -h -p <phoneNo>

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

Generate Key Pair

threema-msgapi-tool.php -g <privateKeyFile> <publicKeyFile>

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

Derive Public Key

threema-msgapi-tool.php -d <privateKey>

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

Network operations

Send Simple Message

threema-msgapi-tool.php -s <threemaId> <from> <secret>

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

Send End-to-End Encrypted Text Message

threema-msgapi-tool.php -S <threemaId> <from> <secret> <privateKey>

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

Send a End-to-End Encrypted Image Message

threema-msgapi-tool.php -S -i <threemaId> <from> <secret> <privateKey> <imageFile>

Encrypt the image file 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 a End-to-End Encrypted File Message

threema-msgapi-tool.php -S -f <threemaId> <from> <secret> <privateKey> <file> <thumbnailFile>

Encrypt the file (and thumbnail if given) 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.

ID-Lookup By Email Address

threema-msgapi-tool.php -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-tool.php -l -p <phoneNo> <from> <secret>

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

Fetch Public Key

threema-msgapi-tool.php -l -k <threemaId> <from> <secret>

Lookup the public key for the given ID.

Fetch Capability

threema-msgapi-tool.php -c <threemaId> <from> <secret>

Fetch the capabilities of a Threema ID

Decrypt a Message and download the Files

threema-msgapi-tool.php -r <threemaId> <from> <secret> <privateKey> <messageId> <nonce> <outputFolder>

Decrypt a box (must be provided on stdin) message and download (if the message is an image or file message) the file(s) to the given <outputFolder> folder

Remaining credits

threema-msgapi-tool.php -C <from> <secret>

Fetch remaining credits

Create a Connection


		use Threema\MsgApi\Connection;
		use Threema\MsgApi\ConnectionSettings;
		use Threema\MsgApi\Receiver;

		include 'threema_msgapi.phar'


		//define your connection settings
		$settings = new ConnectionSettings(
		'*YOUR_GATEWAY_THREEMA_ID',
		'YOUR_GATEWAY_THREEMA_ID_SECRET'
		);

		$publicKeyStore = new Threema\MsgApi\PublicKeyStores\File('/path/to/your/keystore.txt');
		$connector = new Connection($settings, $publicKeyStore);
	
	

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



		//create the connection
		//(...)
		//create a receiver
		$receiver = new Receiver('ABCD1234', Receiver::TYPE_ID);

		$result = $connector->sendSimple($receiver, "This is a Test Message");
		if($result->isSuccess()) {
			echo 'Message ID: '.$result->getMessageId();
		}
		else {
			echo 'Error: '.$result->getErrorMessage();
		}
	

Send a Text Message to a Phone-Number (Basic Mode)


	//create the connection
	//(...)

	//create a receiver
	$receiver = new Receiver('12345678901', Receiver::TYPE_PHONE);

	$result = $connector->sendSimple($receiver, "This is a Test Message");
	if($result->isSuccess()) {
		echo 'Message ID: '.$result->getMessageId();
	}
	else {
		echo 'Error: '.$result->getErrorMessage();
	}

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


		//create the connection
		//(...)

		$threemaId = 'ABCD1234';
		$msg = "This is an end-to-end encrypted message";
		
		// Specify your own private key in hex below (without the "private:" prefix)
		$senderPrivateKey = hex2bin("0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef");

		$e2eHelper = new \Threema\MsgApi\Helpers\E2EHelper($senderPrivateKey,$connector);
		$result = $e2eHelper->sendTextMessage($threemaId, $msg);

		if(true === $result->isSuccess()) {
			echo 'Message ID: '.$result->getMessageId() . "\n";
		}
		else {
			echo 'Error: '.$result->getErrorMessage() . "\n";
		}

	

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


		//create the connection
		//(...)

		$threemaId = 'ABCD1234';
		$msg = "This is an end-to-end encrypted message";
		$filePath = "/path/to/my/file.pdf";
		
		// Specify your own private key in hex below (without the "private:" prefix)
		$senderPrivateKey = hex2bin("0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef");

		$e2eHelper = new \Threema\MsgApi\Helpers\E2EHelper($senderPrivateKey,$connector);
		$result = $e2eHelper->sendFileMessage("TEST1234", $filePath);

		if(true === $result->isSuccess()) {
			echo 'Message ID: '.$result->getMessageId() . "\n";
		}
		else {
			echo 'Error: '.$result->getErrorMessage() . "\n";
		}

	

Creating a connection with advanced options

Attention

These settings change internal values of the TLS connection. Choosing wrong settings can weaken the TLS connection or prevent a successful connection to the server. Use them with care!

Each of the additional options shown below is optional. You can leave it out or use null to use the default value for this option.


		use Threema\MsgApi\Connection;
		use Threema\MsgApi\ConnectionSettings;
		use Threema\MsgApi\Receiver;

		include 'threema_msgapi.phar'

		//define your connection with advanced options
		$settings = new ConnectionSettings(
			'*THREEMA',
			'THISISMYSECRET'
			//the host to be used, set to null for default (recommend)
			null, [
				//set to true to force HTTPS, default: false
				'forceHttps' => true,
				//set the version of TLS to be used, default: null
				'tlsVersion' => '1.2',
				//choose a cipher or a list of ciphers, default: null
				'tlsCipher' => 'ECDHE-RSA-AES128-GCM-SHA256'
			]
		);

		//simple php file to store the public keys
		$publicKeyStore = new Threema\MsgApi\PublicKeyStores\PhpFile('/path/to/my/keystore.php');

		//create a connection
		$connector = new Connection($settings, $publicKeyStore);