Threema Broadcast API (1.3.0)

Download OpenAPI specification:Download

The Threema Broadcast API is designed to let third-party applications communicate with Threema Broadcast identities.

All requests are authenticated using an X-API-Key, which can be obtained from your management cockpit.

An X-API-Key HTTP header must be sent to indicate which API key is to be used with the request.

The API key must match the remote IP (if specified for the given API key) of the connected HTTP client.

There is a request limit: When sending too many API requests, the server will return HTTP header code 429

Authentication

apiKey

Security scheme type: API Key
Header parameter name: X-Api-Key

Profile

Get Profile

Get access to your Broadcast data

Authorizations:

Responses

200

Profile response

Response Schema: application/json
_links
Array of objects <application/json> (Link)
401

Invalid X-Api-Key

get /

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Identity

Get Identities

Return the list of all Broadcast identities

Authorizations:

Responses

200

Identity index response

Response Schema: application/json
_links
Array of objects <application/json> (Link)
identities
Array of objects <application/json> (Identity)

Identity list

401

Invalid X-Api-Key

get /identities

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get Identity Details

Return details of the given Broadcast identity

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Responses

200

Identity detail

Response Schema: application/json
_links
Array of objects <application/json> (Link)
id
string (BroadcastUid) 10 characters

Uid of the Broadcast identity

threemaId
string

Threema ID of the Broadcast identity

validUntil
string <date-time>

Period of validity of the Broadcast identity *Format: iso8601 *Example: 2018-02-28T22:20:04+0100

type
string
Enum: "o15" "o50" "o100" "o500" "o1000" "unlimited" "custom"

Identity type

recipientLimit
integer

Maximum number of recipients

nickname
string

Public nickname

400

Invalid request

401

Invalid X-Api-Key

403

Forbidden

404

Identity not found

get /identities/{broadcastUid}

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities/{broadcastUid}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Set Identity Details

Return details of the given Broadcast identity

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
nickname
required
string [ 1 .. 32 ] characters

public nickname

Responses

200

Identity detail

Response Schema: application/json
_links
Array of objects <application/json> (Link)
id
string (BroadcastUid) 10 characters

Uid of the Broadcast identity

threemaId
string

Threema ID of the Broadcast identity

validUntil
string <date-time>

Period of validity of the Broadcast identity *Format: iso8601 *Example: 2018-02-28T22:20:04+0100

type
string
Enum: "o15" "o50" "o100" "o500" "o1000" "unlimited" "custom"

Identity type

recipientLimit
integer

Maximum number of recipients

nickname
string

Public nickname

400

Invalid request

401

Invalid X-Api-Key

403

Forbidden

404

Identity not found

put /identities/{broadcastUid}

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities/{broadcastUid}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "nickname": "Nick Name"
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Get Identity Avatar

Return base64 encoded jpeg / png image or null

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Responses

200

Identity Avatar response

Response Schema: application/json
_links
Array of objects <application/json> (Link)
avatar
string Nullable

base64 encoded jpeg / png group image

401

Invalid X-Api-Key

get /identities/{broadcastUid}/avatar

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/avatar

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "_links":
    [],
  • "avatar": "/9j/4AAQSkZJRgABAQAAAQABAAD//gAfQ29tcHJlc3NlZCBieSBqcGVnLXJlY29tcHJlc3P/2wCEAAQEBAQEBAQEBAQGBgUGBggHBwcHCAwJCQkJCQwTDA4MDA4MExEUEA8QFBEeFxUVFx4iHRsdIiolJSo0MjRERFwBBAQEBAQEBAQEBAYGBQYGCAcHBwcIDAkJCQkJDBMMDgwMDgwTERQQDxAUER4XFRUXHiIdGx0iKiUlKjQyNEREXP/CABEIAAEAAQMBIgACEQEDEQH/xAAUAAEAAAAAAAAAAAAAAAAAAAAH/9oACAEBAAAAAEL/xAAUAQEAAAAAAAAAAAAAAAAAAAAI/9oACAECEAAAACj/AP/EABQBAQAAAAAAAAAAAAAAAAAAAAj/2gAIAQMQAAAAJ/8A/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAgEBPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAwEBPwB//9k="
}

Update Identity Avatar image

Update Identity Avatar image

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
avatar
required
string

base 64 encoded jpeg /png image

Responses

204

Identity avatar successfully updated

400

Invalid request

401

Invalid X-Api-Key

404

Identity not found

put /identities/{broadcastUid}/avatar

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/avatar

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "avatar": "/9j/4AAQSkZJRgABAQAAAQABAAD//gAfQ29tcHJlc3NlZCBieSBqcGVnLXJlY29tcHJlc3P/2wCEAAQEBAQEBAQEBAQGBgUGBggHBwcHCAwJCQkJCQwTDA4MDA4MExEUEA8QFBEeFxUVFx4iHRsdIiolJSo0MjRERFwBBAQEBAQEBAQEBAYGBQYGCAcHBwcIDAkJCQkJDBMMDgwMDgwTERQQDxAUER4XFRUXHiIdGx0iKiUlKjQyNEREXP/CABEIAAEAAQMBIgACEQEDEQH/xAAUAAEAAAAAAAAAAAAAAAAAAAAH/9oACAEBAAAAAEL/xAAUAQEAAAAAAAAAAAAAAAAAAAAI/9oACAECEAAAACj/AP/EABQBAQAAAAAAAAAAAAAAAAAAAAj/2gAIAQMQAAAAJ/8A/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAgEBPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAwEBPwB//9k="
}

Remove Identity Avatar

Remove the identity avatar

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Responses

204

Identity avatar successfully removed

400

Invalid request

401

Invalid X-Api-Key

404

Identity not found

delete /identities/{broadcastUid}/avatar

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/avatar

Get identity languages

Return languages of the given broadcast identity

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Responses

200

Identity languages

Response Schema: application/json
_links
Array of objects <application/json> (Link)
languages
Array of objects <application/json> (IdentityLanguage)

Languages List

400

Invalid request

401

Invalid X-Api-Key

403

Forbidden

404

Identity not found

get /identities/{broadcastUid}/languages

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/languages

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Create identity language

Create a new identity language

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
name
required
string [ 1 .. 50 ] characters

Name of the new language

isoCode
required
string [ 1 .. 5 ] characters

ISO Code of the new language

default
required
boolean

determinate if the new language should be the default language

Responses

201

Identity language

Response Schema: application/json
_links
Array of objects <application/json> (Link)
uid
string (IdentityLanguageUid)

uid of the identity language

name
string

name

isoCode
string

iso code

default
boolean

default language indicator

400

Invalid request

401

Invalid X-Api-Key

403

Forbidden

404

Identity not found

post /identities/{broadcastUid}/languages

Threema Broadcast API V1

https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/languages

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "name": "Schweiz",
  • "isoCode": "de-CH",
  • "default": true
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{}

Set identity languages order

Set the order of identity languages

Authorizations:
path Parameters
broadcastUid
required
string (BroadcastUid) 10 characters
Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
order
required
Array of strings

ordered array of all language uid strings

Responses

204

Success

400

Invalid request

401

Invalid X-Api-Key

403