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 text 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):

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:

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 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: