Threema Message API

Hier finden Sie als Entwickler alle nötigen Informationen und den Source Code zur erfolgreichen Implementierung von Threema Gateway in Ihrer Umgebung.

Threema stellt kein grafisches User-Interface für den Threema Gateway zur Verfügung. Das Message API ist eine Schnittstelle, die aus kundenspezifischer Software heraus angesprochen werden kann, um Nachrichten via Threema Gateway zu versenden und zu empfangen.

Download on github.com

Note

The Python SDK requires Python 3.7+.

On operating systems where Python 3 is not the default Python runtime, you should use pip3 instead of pip.

Prerequisites

Install Python 3, pip and the virtual environment for Python (optional).

sudo apt-get install python3 python3-pip

We recommend creating an isolated Python environment (virtualenv) for your development:

python3 -m venv threema-gateway-venv

You can switch into the created virtual environment threema-gateway-venv by running the following command:

source threema-gateway-venv/bin/activate

To deactivate the virtual environment, just run:

deactivate

Installation

If you are using a virtual environment, activate it first.

Then, install the module from the Python Package Index (PyPI) by running:

pip install threema.gateway

The required dependencies will be installed automatically. However, you may need to install libsodium.

Use console client

Local operations (no network communication)

Encrypt

threema-gateway encrypt <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-gateway decrypt <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.

Example
$ echo -n 'aff0...' | threema-gateway decrypt private:[PRIVATE_KEY] public:[PUBLIC_KEY] [NONCE]
Here, “aff0...” indicates the box (hex).

Hash Email Address

threema-gateway hash -e <email>
	

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

Hash Phone Number

threema-gateway hash -p <phoneNo>
	

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

Generate Key Pair

threema-gateway generate <privateKeyFile> <publicKeyFile>
	

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

Derive Public Key

threema-gateway derive <privateKey>
	

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

Network operations

Send Simple Message

threema-gateway send_simple <to> <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 Enrypted Text Message

threema-gateway send_e2e <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 a End-to-End Encrypted Image Message (deprecated, use the File Message type instead)

threema-gateway send_image <to> <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-gateway send_file <to> <from> <secret> <privateKey> <file> -i <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-gateway lookup <from> <secret> -e <email>
	

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

ID-Lookup By Phone Number

threema-gateway lookup <from> <secret> -p <phoneNo>
	

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

Fetch Public Key

threema-gateway lookup <from> <secret> -i <id>
	

Lookup the public key for the given ID.

Fetch Capability

threema-gateway capabilities <from> <secret> <id>
	

Fetch the capabilities of a Threema ID

Remaining credits

threema-gateway credits <from> <secret>
	

Fetch remaining credits