Threema Broadcast API (1.0.1)

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.

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 object <application/json> (Link)
401

Invalid X-Api-Key

get /
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/

Response samples

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 object <application/json> (Link)
identities
Array of object <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

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

application/json
Copy
Expand all Collapse all
{}

Get Recipients

Return the list of all recipients of the given Broadcast identity

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

Uid of the Broadcast identity

Responses

200

RecipientIndex

Response Schema: application/json
_links
Array of object <application/json> (Link)
recipients
Array of object <application/json> (Recipient)

Recipient list

_paging
object
400

Invalid request

401

Invalid X-Api-Key

403

Forbidden

404

Identity not found

get /identities/{broadcastUid}/recipients
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/recipients

Response samples

application/json
Copy
Expand all Collapse all
{}

Get Recipient Details

Return details of a recipient

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

Uid of the Broadcast identity

threemaId
required
string (ThreemaId) 8 characters
Example: "B4UXXX11"

Threema ID of the recipient

Responses

200

Recipient detail

Response Schema: application/json
_links
Array of object <application/json> (Link)
id
string (ThreemaId) 8 characters

Threema ID of the recipient

firstName
string

First name

lastName
string

Last name

language
string

Language code of the recipients language setting

400

Invalid request

401

Invalid X-Api-Key

403

Forbidden

404

Identity or recipient not found

get /identities/{broadcastUid}/recipients/{threemaId}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/recipients/{threemaId}

Response samples

application/json
Copy
Expand all Collapse all
{}

Update Recipient

Update a recipient’s details

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

Uid of the Broadcast identity

threemaId
required
string (ThreemaId) 8 characters
Example: "B4UXXX11"

Threema ID of the recipient

Request Body schema: application/json
firstName
required
string [ 1 .. 256 ] characters

First name of the recipient

lastName
required
string [ 1 .. 256 ] characters

Last name of the recipient

language
required
string [ 2 .. 3 ] characters

Language of the recipient

Responses

204

Recipient successfully updated

400

Invalid request

401

Invalid X-Api-Key

404

Recipient or identity not found

put /identities/{broadcastUid}/recipients/{threemaId}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/recipients/{threemaId}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "firstName": "Peter",
  • "lastName": "Black",
  • "language": "en"
}

Distribution List

Get Distribution Lists

Return the list of the distribution lists of the given Broadcast identity

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

Uid of the Broadcast identity

query Parameters
q
string (FilterQuery)
Example: "fil"

Query string to filter the result

Responses

200

Feeds response

Response Schema: application/json
_links
Array of object <application/json> (Link)
distributionLists
Array of object <application/json> (DistributionList)

Distribution List

401

Invalid X-Api-Key

get /identities/{broadcastUid}/distribution_lists
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists

Response samples

application/json
Copy
Expand all Collapse all
{}

Create Distribution List

Create a distribution list

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 .. 256 ] characters

New distribution list name

Responses

201

Distribution list successfully created

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

Uid of the distribution list

name
any
state
any
Enum:"active" "deleted"
400

Invalid request (the distribution list possibly already exists)

401

Invalid X-Api-Key

post /identities/{broadcastUid}/distribution_lists
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "The Distri"
}

Response samples

application/json

Get Distribution List Details

Return details of a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

Responses

200

Distribution list response

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

Uid of the distribution list

name
any
state
any
Enum:"active" "deleted"
401

Invalid X-Api-Key

get /identities/{broadcastUid}/distribution_lists/{distributionListUid}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}

Response samples

application/json

Update Distribution List

Update the details of a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

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

New distribution list name

Responses

204

Distribution list successfully updated

400

Invalid request

401

Invalid X-Api-Key

404

Distribution list not found

put /identities/{broadcastUid}/distribution_lists/{distributionListUid}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "The Distri 2.0"
}

Get Distribution List Chat History

Return all messages of a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

Responses

200

Distribution list chat response

Response Schema: application/json
_links
Array of object <application/json> (Link)
messages
Array of object <application/json> (DistributionListChatMessage)

Distribution list chat message list

_paging
object
401

Invalid X-Api-Key

404

Distribution list not found

get /identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat

Response samples

application/json
Copy
Expand all Collapse all
{}

Send Message

Send a message to a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

Request Body schema: application/json
type
required
string
Value:"text"

Message type

body
required
object

All translated messages (Max. 3500 bytes per message)

{'de':'Nachricht', 'en': 'Message', 'tlh': 'QIn'}

Responses

201

Message successfully sent

Response Schema: application/json
id
string (DistributionListUid) 10 characters

Uid of the distribution list

type
any
Enum:"text" "image" "video" "audio" "ballot" "file"
body
any
createdAt
string <date-time>
stats
object
401

Invalid X-Api-Key

404

Invalid distribution list

post /identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat

Request samples

application/json
Copy
Expand all Collapse all
{
  • "type": "text",
  • "body":
    {
    }
}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "nncbasmdl2",
  • "type": "text",
  • "body": "Hello!",
  • "createdAt": "2018-02-28T22:20:04+0100",
  • "stats": { }
}

Get Message

Return a message of a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

distributionListChatMessageUid
required
integer (DistributionListChatMessageUid)
Example: 3920

Uid of the distribution list message

Responses

200

Distribution list message

Response Schema: application/json
id
string (DistributionListUid) 10 characters

Uid of the distribution list

type
any
Enum:"text" "image" "video" "audio" "ballot" "file"
body
any
createdAt
string <date-time>
stats
object
401

Invalid X-Api-Key

404

Distribution list not found

get /identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat/{distributionListChatMessageUid}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat/{distributionListChatMessageUid}

Response samples

application/json
Copy
Expand all Collapse all
{
  • "id": "nncbasmdl2",
  • "type": "text",
  • "body": "Hello!",
  • "createdAt": "2018-02-28T22:20:04+0100",
  • "stats": { }
}

Delete Message

Remove a message from a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

distributionListChatMessageUid
required
integer (DistributionListChatMessageUid)
Example: 3920

Uid of the distribution list message

Responses

204

Message successfully removed from distribution list

401

Invalid X-Api-Key

404

Distribution list not found

delete /identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat/{distributionListChatMessageUid}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}/chat/{distributionListChatMessageUid}

Get Distribution List Recipients

Return the list of the recipients of a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

Responses

200

RecipientIndex

Response Schema: application/json
_links
Array of object <application/json> (Link)
recipients
Array of object <application/json> (Recipient)

Recipient list

_paging
object
400

Invalid request

401

Invalid X-Api-Key

404

Distribution list not found

get /identities/{broadcastUid}/distribution_lists/{distributionListUid}/recipients
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}/recipients

Response samples

application/json
Copy
Expand all Collapse all
{}

Add Distribution List Recipients

Add recipients to a distribution list

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

Uid of the Broadcast identity

distributionListUid
required
string (DistributionListUid) 10 characters
Example: "nncbasmdl2"

Uid of the distribution list

Request Body schema: application/json
recipients
required
Array of string (ThreemaId)

List of Threema IDs

replaceExisting
required
boolean

Responses

201

Recipient successfully updated

400

Invalid request

401

Invalid X-Api-Key

post /identities/{broadcastUid}/distribution_lists/{distributionListUid}/recipients
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/distribution_lists/{distributionListUid}/recipients

Request samples

application/json
Copy
Expand all Collapse all
{
  • "recipients":
    [
    ],
  • "replaceExisting": false
}

Feed

Get Feeds

Return the list of all feeds of the given Broadcast identity

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

Uid of the Broadcast identity

query Parameters
q
string (FilterQuery)
Example: "fil"

Query string to filter the result

Responses

200

Feeds response

Response Schema: application/json
_links
Array of object <application/json> (Link)
feeds
Array of object <application/json> (Feed)

Feed list

401

Invalid X-Api-Key

get /identities/{broadcastUid}/feeds
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/feeds

Response samples

application/json
Copy
Expand all Collapse all
{}

Create Feed

Create a feed

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 .. 256 ] characters

Feed name

Responses

201

Feed successfully created

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

Uid of the feed

name
any
state
any
Enum:"active" "deleted"
400

Invalid request (invalid threemaId or feed already exists)

401

Invalid X-Api-Key

post /identities/{broadcastUid}/feeds
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/feeds

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "The new feed name"
}

Response samples

application/json
Copy
Expand all Collapse all

Get Feed Details

Return details of a feed

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

Uid of the Broadcast identity

feedUid
required
string (FeedUid) 10 characters
Example: "3334osykj4"

Uid of the feed

Responses

200

Feeds response

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

Uid of the feed

name
any
state
any
Enum:"active" "deleted"
401

Invalid X-Api-Key

get /identities/{broadcastUid}/feeds/{feedUid}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/feeds/{feedUid}

Response samples

application/json
Copy
Expand all Collapse all

Update Feed

Update a feed

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

Uid of the Broadcast identity

feedUid
required
string (FeedUid) 10 characters
Example: "3334osykj4"

Uid of the feed

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

Feed name

Responses

204

Feed successfully updated

400

Invalid request

401

Invalid X-Api-Key

404

Feed not found

put /identities/{broadcastUid}/feeds/{feedUid}
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/feeds/{feedUid}

Request samples

application/json
Copy
Expand all Collapse all
{
  • "name": "Feed 2.0"
}

Get Chat History of Feed

Return all messages of a feed

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

Uid of the Broadcast identity

feedUid
required
string (FeedUid) 10 characters
Example: "3334osykj4"

Uid of the feed

Responses

200

Feed chat response

Response Schema: application/json
_links
Array of object <application/json> (Link)
messages
Array of object <application/json> (FeedChatMessage)

Feed chat message list

_paging
object
401

Invalid X-Api-Key

404

Feed not found

get /identities/{broadcastUid}/feeds/{feedUid}/chat
Threema Broadcast API V1
https://broadcast.threema.ch/api/v1/identities/{broadcastUid}/feeds/{feedUid}/chat

Response samples

application/json
Copy
Expand all Collapse all
{