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.

This API can be used to send messages to any Threema user, and to receive incoming messages and delivery receipts. There are two main modes of operation:

The mode that you can use depends on the way your account was set up.

To make client-side integration as simple as possible, the API is based on plain old HTTPS GET/POST operations. Authentication details (i.e. the API identity and key) are passed as GET/POST parameters as well (no need for HTTP authentication). The HTTP status code reflects the result of the operation (e.g. 200 OK, 401 Unauthorized, 402 Payment Required, 404 Not Found etc.).

Sending Messages

Basic mode

URL: https://msgapi.threema.ch/send_simple

POST parameters (application/x-www-form-urlencoded):

By using the phone or email recipient specifiers, one can avoid having to look up the corresponding ID (see "Lookup ID" below) and instead do everything in one call (may be more suitable for SMS gateway style integration).

Possible HTTP result codes:

On success (HTTP 200), the ID of the new message is returned as text/plain.

End-to-end encrypted mode

URL: https://msgapi.threema.ch/send_e2e

POST parameters (application/x-www-form-urlencoded):

The nonce should consist of 24 cryptographically secure random bytes.

Possible HTTP result codes:

On success (HTTP 200), the ID of the new message is returned as text/plain.

ID Lookups

Find ID by phone number

URL: https://msgapi.threema.ch/lookup/phone/41791234567?from=xxxxxxxx&secret=xxxxxxxx

The phone number must be passed in E.164 format, without the leading +. The API identity and secret must be passed in the corresponding GET parameters for authentication (use URL encoding).

The Threema ID corresponding to the phone number will be returned as a text/plain response.

Possible HTTP result codes:

Find ID by phone number hash

URL: https://msgapi.threema.ch/lookup/phone_hash/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef?from=xxxxxxxx&secret=xxxxxxxx

The phone number must be passed as an HMAC-SHA256 hash of the E.164 number without the leading +. The HMAC key is 85adf8226953f3d96cfd5d09bf29555eb955fcd8aa5ec4f9fcd869e258370723 (in hexadecimal).

Example: the phone number 41791234567 hashes to ad398f4d7ebe63c6550a486cc6e07f9baa09bd9d8b3d8cb9d9be106d35a7fdbc.

The API identity and secret must be passed in the corresponding GET parameters for authentication (use URL encoding).

The Threema ID corresponding to the phone number will be returned as a text/plain response.

Possible HTTP result codes:

Find ID by email address

URL: https://msgapi.threema.ch/lookup/email/john@doe.com?from=xxxxxxxx&secret=xxxxxxxx

The API identity and secret must be passed in the corresponding GET parameters for authentication (use URL encoding).

The Threema ID corresponding to the email address will be returned as a text/plain response.

Possible HTTP result codes:

Find ID by email address hash

URL: https://msgapi.threema.ch/lookup/email_hash/0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef?from=xxxxxxxx&secret=xxxxxxxx

The lowercased and whitespace-trimmed email address must be hashed with HMAC-SHA256. The HMAC key is 30a5500fed9701fa6defdb610841900febb8e430881f7ad816826264ec09bad7 (in hexadecimal).

Example: the email address test@threema.ch hashes to 1ea093239cc5f0e1b6ec81b866265b921f26dc4033025410063309f4d1a8ee2c.

The API identity and secret must be passed in the corresponding GET parameters for authentication (use URL encoding).

The Threema ID corresponding to the email address will be returned as a text/plain response.

Possible HTTP result codes:

Bulk lookup

URL: https://msgapi.threema.ch/lookup/bulk?from=xxxxxxxx&secret=xxxxxxxx

This URL can be used to lookup up to 1000 phone number hashes or email address hashes per request. See above for details on the hashing.

The API identity and secret must be passed in the URL query string for authentication (use URL encoding).

The POST request body must be a JSON document with the following format:

{
	"phoneHashes": ["27b0e25b6091a0d527e0265e2b4669691f253fd7e4fdca4e82ad37cb1e2bcc32",
		"ebe6cf4cb497b626622ed7eca80dff38a766153cb820441c03cd2677976b3b6a"],
	"emailHashes": ["eca1f01b9fa1ae14ba9d2fe236cde235c0f7877e73173d13501635a63010ded5",
		"8bb29bd2b5e7b9ca317eb345fd1f7f9a1f7a0524369872b0dac2d903fdfe36e3"],
	}

The response will also be returned as a JSON document:

{
	"phoneHash": "27b0e25b6091a0d527e0265e2b4669691f253fd7e4fdca4e82ad37cb1e2bcc32",
	"identity": "QRSTUVWX",
	"publicKey": "e58771baf2db70989d0724ef77ba6bf867d46aaa24fc2c3f8f0f144d89a6264b"
},{
	"emailHash": "8bb29bd2b5e7b9ca317eb345fd1f7f9a1f7a0524369872b0dac2d903fdfe36e3",
	"identity": "JIKLMNOP",
	"publicKey": "6a2bd9a0912d4ce0e5c6fc6c9b8ac14a8fdb6282a34c7e0f5fe57d57c54fb69f"
}

In this example, matches were found for one phone number hash and one email address hash, while no matches were found for the other hashes. Note: if both a phone number hash and an email address hash are provided that resolve to the same identity, only one entry will be returned in the response array, but it will have both a phoneHash and an emailHash key. At most 1000 hashes may be specified per request (i.e. the number of phone number hashes plus the number of email hashes may not be more than 1000).

Possible HTTP result codes:

Check file reception capability of an ID

Before you send a file to a Threema ID using the blob upload (+ file message), you may want to check whether the recipient uses a Threema version that supports receiving files. The receiver may be using an old version, or a platform where file reception is not supported.

URL: https://msgapi.threema.ch/capabilities/XXXXXXXX?from=xxxxxxxx&secret=xxxxxxxx

The API identity and secret must be passed in the corresponding GET parameters for authentication (use URL encoding).
The result is a text/plain response of supported capabilities, separated by commas. Currently defined capabilities:

More capabilities may be added in the future (separated with commas), so you should match on substrings when checking for file. The order in which the capabilities are returned is not defined.

Example result: text,image,video,audio,file

Possible HTTP result codes:

Key Lookups

For the end-to-end encrypted mode, you need the public key of the recipient in order to encrypt a message. While it's best to obtain this directly from the recipient (extract it from the QR code), this may not be convenient, and therefore you can also look up the key associated with a given ID from the server.

URL: https://msgapi.threema.ch/pubkeys/XXXXXXXX?from=xxxxxxxx&secret=xxxxxxxx

The API identity and secret must be passed in the corresponding GET parameters for authentication (use URL encoding).
The public key corresponding to the ID will be returned as a text/plain response (hex encoded).

Possible HTTP result codes:

It is strongly recommended that you cache the public keys to avoid querying the API for each message.

Incoming Messages and Delivery Receipts

If your account is operating in end-to-end encrypted mode and incoming messages have been enabled on it, you can specify an HTTPS URL callback that will be called whenever an incoming message or delivery receipt arrives for your API identity. You can set or change the callback URL in the Threema Gateway administration panel.

Callback parameters

Your callback URL will be called with the following POST parameters (application/x-www-form-urlencoded):

Note that the message first needs to be decrypted before it can be determined whether it is an incoming text/media message or a delivery receipt.

MAC calculation

For each callback, the server includes a mac parameter than can be used to verify the authenticity of the call and the included information. This parameter is calculated as follows:

mac = HMAC-SHA256(from || to || messageId || date || nonce || box, secret)
|| denotes concatenation. The parameters are concatenated in the same form as they were included in the POST (i.e. including any hex encoding, but not including any URL encoding). The secret that is used for the HMAC operation is the API authentication secret.

It is recommended that receivers verify the mac parameter before attempting to parse the other parameters and decrypt the message.

Callback results and retry

If the connection to your callback URL fails or your callback does not return an HTTP 200 status, the API will retry 3 more times in intervals of 5 minutes. If all attempts fail, the message is discarded.

Certificates and cipher suites

The server that hosts the callback URL must use a valid and trusted SSL/TLS certificate (not self-signed). If in doubt, please contact customer service and specify the issuing CA of your certificate.

File Upload and Download

Upload

URL: https://msgapi.threema.ch/upload_blob

POST parameters (multipart/form-data):

URL parameters ("GET"):

Please note that the authentication parameters must be passed in the request URL ("/upload_blob?from=...&secret=..."), while the actual blob data needs to be sent as a multipart/form-data parameter.

Possible HTTP result codes:

The ID of the new blob is returned as text/plain. One credit is deducted for the upload of a blob.

Download

URL: https://msgapi.threema.ch/blobs/blobId

GET parameters:

Possible HTTP result codes:

Please note: after a blob download has first been attempted, the blob may be deleted from the server within an hour.

Querying Account Information

Get remaining credits

URL: https://msgapi.threema.ch/credits?from=xxxxxxxx&secret=xxxxxxxx

The API identity and secret must be passed in the corresponding GET parameters for authentication (use URL encoding).

The number of credits left on the account that the given ID belongs to will be returned as a text/plain response. Note: several IDs may use the same account, and thus share the same credit balance.

Possible HTTP result codes:

E2E Message Format

The end-to-end encrypted messages use the following binary format:

type data padding

Type 

The first byte denotes the message type:

Byte Type
0x01 Text message
0x02 Image message
0x17 File message
0x80 Delivery receipt 

Data 

The message data.

Type Data
Text UTF-8 encoded string
Image

The image data (JPEG) needs to be uploaded to the blob server.

Data Description Length
Blob ID   16 Bytes
Size Image file size in bytes 4 Bytes
Nonce Blob encryption nonce 24 Bytes
File

The file contents need to be uploaded to the blob server.

The file message data is sent as an UTF8-encoded JSON string.

JSON data format:

Key Description Type Required
b Blob ID of the file String (Binary as Hex) X
t Blob ID of the thumbnail file String (Binary as Hex)  
k Encryption key of the blobs String (Binary as Hex) X
m Mime Type of the file String X
n File name String  
s File size Long X
i Reserved, set to 0 for now Integer X
d Optional description text String  


Delivery receipt

The delivery receipt always references 1 or more message IDs.

Data Description Length
Type
Code Type
0x01 Received
0x02 Read
0x03 Acknowledged / Thumbs up
0x04 Declined / Thumbs down
1 Byte
Message ID A message ID that this receipt confirms 8 Bytes
... ...more message IDs... ...

Padding

A random amount of PKCS#7 style padding (between 1 and 255 bytes, inclusive) is appended to each message. The padding consists of the random number n repeated n times.

Example paddings:

Random Number Padding
1 0x01
3 0x030303
10 0x0a0a0a0a0a0a0a0a0a0a

To add padding (pseudocode):

	amount = random(1, 256)
	padding = [amount] * amount
	message = message + padding

To remove padding (pseudocode): 

 	amount = message[-1]
	message_without_padding = message[:-amount]

Example

The text message "hello threema" with 7 bytes of padding would look like this before encryption / after decryption: