Threema Broadcast API (1.12.2)

Download OpenAPI specification:

E-mail: support-broadcast@threema.ch

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 created here:
Threema Broadcast > Settings > Your profile > API Keys.
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.
Requests must be limited to 10,000 per day, the server will return HTTP header code 429 if the request limit is reached.
The ratio of the number of recipients to the number of groups, feeds, or distribution lists created via API must not exceed 1:10.
Only outgoing files can be viewed in Broadcast; incoming files will not be saved and can therefore not be viewed.
A pageSize < 0 or > 5000 will abort the request and return code 400.

Bot

Get Bots

Return the list of all bots of the given Broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

query Parameters

q	string (FilterQuery) Example: q=fil Query string to filter the result

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"bots": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx"
}
],
"id": "xxxxxxxxxx",
"name": "The bot 1",
"state": "active"
},
{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/yyyyyyyyy"
}
],
"id": "yyyyyyyyy",
"name": "The bot 2",
"state": "deleted"
}
]
}

Create Bot

Create a bot

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

name

required

string [ 1 .. 256 ] characters

Bot name

Responses

Request samples

Payload

Content type

application/json

{"name": "The new bot name"
}

Response samples

201

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx"
},
{"ref": "commands",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots"
}
],
"id": "3334osykj4",
"name": "Bot 2.0",
"state": "active"
}

Get Bot Details

Return details of a bot

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx"
},
{"ref": "commands",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots"
}
],
"id": "3334osykj4",
"name": "Bot 2.0",
"state": "active"
}

Update Bot

Update a bot

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot

Request Body schema: application/json
required

name

required

string [ 1 .. 256 ] characters

Bot name

Responses

Request samples

Payload

Content type

application/json

{"name": "Bot 2.0"
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx"
},
{"ref": "commands",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots"
}
],
"id": "3334osykj4",
"name": "Bot 2.0",
"state": "active"
}

Delete Bot

Delete the bot (state dependency = 'deleted')

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot

Responses

Delete bot command

Delete the bot command

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot
commandUid required	string (BotCommandUid) = 10 characters Example: gSkZoI3SK6 Uid of the bot command

Responses

Get bot commands

Return the list of all bot commands of the given Broadcast identity bot

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
},
{"ref": "bot",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx"
}
],
"commands": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands/zzzzzzzzzz"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
}
],
"id": "zzzzzzzzzz",
"name": "The bot command 1",
"state": "active",
"inputs": ["help",
"join"
],
"output": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
},
{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands/yyyyyyyyyy"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
}
],
"id": "yyyyyyyyyy",
"name": "The bot command 2",
"state": "temporary",
"inputs": [ ],
"output": [ ]
}
]
}

Create bot command

Create a bot command

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot

Request Body schema: application/json
required

name required	string [ 1 .. 256 ] characters Bot command name
inputs	Array of strings Inputs that trigger this bot command (straight quotation marks are not allowed).
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)

Responses

Request samples

Payload

Content type

application/json

{"name": "The new bot command name",
"inputs": ["help"
],
"output": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Response samples

201

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands/zzzzzzzzzz"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
}
],
"id": "gSkZoI3SK6",
"name": "Bot command 2.0",
"state": "active",
"inputs": ["help"
],
"output": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Get Bot Command Details

Return details of a bot command

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot
commandUid required	string (BotCommandUid) = 10 characters Example: gSkZoI3SK6 Uid of the bot command

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands/zzzzzzzzzz"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
}
],
"id": "gSkZoI3SK6",
"name": "Bot command 2.0",
"state": "active",
"inputs": ["help"
],
"output": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Update Bot Command

Update a bot command

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot
commandUid required	string (BotCommandUid) = 10 characters Example: gSkZoI3SK6 Uid of the bot command

Request Body schema: application/json
required

name required	string [ 1 .. 256 ] characters Bot command name
inputs	Array of strings Inputs that trigger this bot command (straight quotation marks are not allowed).
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)

Responses

Request samples

Payload

Content type

application/json

{"name": "Bot Command 2.0",
"inputs": ["help"
],
"output": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx"
},
{"ref": "commands",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots"
}
],
"id": "3334osykj4",
"name": "Bot 2.0",
"state": "active"
}

Update Bot State

Update the state of a bot

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
botUid required	string (BotUid) = 10 characters Example: 3334osykj4 Uid of the bot
botState required	string (BotState) Enum: "active" "deleted" Example: active state of the bot

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx"
},
{"ref": "commands",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots/xxxxxxxxxx/commands"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/bots"
}
],
"id": "3334osykj4",
"name": "Bot 2.0",
"state": "active"
}

Distribution List

Get Distribution Lists

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

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

query Parameters

q	string (FilterQuery) Example: q=fil Query string to filter the result

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"distributionLists": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy"
}
],
"id": "yyyyyyyyyy",
"name": "The Distri 1"
}
]
}

Create Distribution List

Create a distribution list

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

name

required

string [ 1 .. 256 ] characters

New distribution list name

Responses

Request samples

Payload

Content type

application/json

{"name": "The Distri"
}

Response samples

201

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList"
}
],
"id": "nncbasmdl2",
"name": "The Distri",
"state": "active"
}

Get Distribution List Details

Return details of a distribution list

Authorizations:

apiKey

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

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList"
}
],
"id": "nncbasmdl2",
"name": "The Distri",
"state": "active"
}

Update Distribution List

Update the details of a distribution list

Authorizations:

apiKey

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
required

name

required

string [ 1 .. 256 ] characters

New distribution list name

Responses

Request samples

Payload

Content type

application/json

{"name": "The Distri 2.0"
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList"
}
],
"id": "nncbasmdl2",
"name": "The Distri",
"state": "active"
}

Delete Distribution List

Delete the distribution list (state dependency = 'deleted')

Authorizations:

apiKey

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

Get Distribution List Chat History

Return all messages of a distribution list

Authorizations:

apiKey

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

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "distributionList",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy"
}
],
"messages": [{"uid": "PV9M5iWXat",
"subject": "null",
"author": "info@threema.ch",
"trackDelivery": "false",
"createdAt": "2018-02-28T22:20:04+0100",
"startAt": "2018-02-28T22:20:04+0100",
"doneAt": "2018-02-28T22:20:04+0100",
"stats": {"failed": "0",
"successfully": "42",
"received": "42",
"read": "42",
"ack": "42",
"dec": "42",
"total": "42"
}
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Send Message

Send a message to a distribution list

Authorizations:

apiKey

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	string Message type text
subject	string or null (ChatMessageSubject) Default: null Custom subject of the message
trackDelivery	boolean Default: false (only if feature is granted:) Determinate if message delivery should be tracked
startAt	integer Default: null (only if feature is granted:) Specify sending time (UTC Timestamp)
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)

Responses

Request samples

Payload

Content type

application/json

Example

text

{"type": "text",
"subject": "null",
"trackDelivery": false,
"startAt": null,
"body": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Response samples

201

Content type

application/json

Example

text

{"uid": "PV9M5iWXat",
"subject": "null",
"author": "info@threema.ch",
"trackDelivery": "false",
"createdAt": "2018-02-28T22:20:04+0100",
"startAt": "2018-02-28T22:20:04+0100",
"doneAt": "2018-02-28T22:20:04+0100",
"stats": {"failed": "0",
"successfully": "42",
"received": "42",
"read": "42",
"ack": "42",
"dec": "42",
"total": "42"
},
"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy/chat/PV9M5iWXat"
},
{"ref": "distributionList",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy/chat"
}
],
"type": "text",
"body": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Get Message

Return a message of a distribution list

Authorizations:

apiKey

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	string (DistributionListChatMessageUid) Example: PV9M5iWXat Uid of the distribution list message

Responses

Response samples

200

Content type

application/json

Example

text

{"uid": "PV9M5iWXat",
"subject": "null",
"author": "info@threema.ch",
"trackDelivery": "false",
"createdAt": "2018-02-28T22:20:04+0100",
"startAt": "2018-02-28T22:20:04+0100",
"doneAt": "2018-02-28T22:20:04+0100",
"stats": {"failed": "0",
"successfully": "42",
"received": "42",
"read": "42",
"ack": "42",
"dec": "42",
"total": "42"
},
"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy/chat/PV9M5iWXat"
},
{"ref": "distributionList",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy/chat"
}
],
"type": "text",
"body": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Delete Message

Remove a message from a distribution list

Authorizations:

apiKey

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	string (DistributionListChatMessageUid) Example: PV9M5iWXat Uid of the distribution list message

Responses

Get Message Delivery

Return message delivery stats of a distribution list message

Authorizations:

apiKey

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	string (DistributionListChatMessageUid) Example: PV9M5iWXat Uid of the distribution list message

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Request Body schema: application/json
required

q	string [ 1 .. 256 ] characters filter query
state	Array of strings (DeliveryState) filter state

Responses

Request samples

Payload

Content type

application/json

{"q": "ECHOECHO Receiver Name",
"state": ["sent",
"received",
"read",
"ack",
"dec"
]
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"deliveries": [{"date": "2018-02-28T22:20:04+0100",
"id": "ECHOECHO",
"firstName": "E",
"lastName": "Cho",
"language": "en",
"state": "ack"
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Get Message File

Return a base64 file content of a distribution list. Only outgoing files can be viewed in Broadcast; incoming files will not be saved and can therefore not be viewed.

Authorizations:

apiKey

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	string (DistributionListChatMessageUid) Example: PV9M5iWXat Uid of the distribution list message

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy/chat/PV9M5iWXat"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy/chat"
},
{"ref": "distributionList",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy"
}
],
"file": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==",
"filename": "filename.dat",
"mimetype": "application/octet-stream"
}

Get Distribution List Recipients

Return the list of the recipients of a distribution list

Authorizations:

apiKey

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

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "feed",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy"
}
],
"recipients": [{"id": "B44UXX11",
"firstName": "E",
"lastName": "Cho",
"language": "en",
"state": "active"
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Add Distribution List Recipients

Add recipients to a distribution list

Authorizations:

apiKey

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
required

recipients required	Array of strings (ThreemaId) [ items = 8 characters ] List of Threema IDs
replaceExisting	boolean Default: false Replace existing recipients with new list of recipients
filterInvalid	boolean Default: false Filter invalid and revoked Threema IDs

Responses

Request samples

Payload

Content type

application/json

{"recipients": ["B4UXXX11"
],
"replaceExisting": false,
"filterInvalid": false
}

Response samples

200

Content type

application/json

["0-12",
"ECHOECHOECHO",
"REVOKED"
]

Remove Distribution List Recipients

Remove recipients to a distribution list

Authorizations:

apiKey

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
required

recipients

required

Array of strings (ThreemaId) [ items = 8 characters ]

List of Threema IDs to remove from Distribution List

Responses

Request samples

Payload

Content type

application/json

{"recipients": ["B4UXXX11"
]
}

Remove invalid Identities

Remove invalid Identities of a distribution list

Authorizations:

apiKey

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

Response samples

200

Content type

application/json

["B4UXXX11",
"ECHOECHO"
]

Update Distribution List State

Update the state of a distribution list

Authorizations:

apiKey

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
distributionListState required	string (DistributionListState) Enum: "active" "deleted" Example: active state of the distribution list.

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList"
}
],
"id": "nncbasmdl2",
"name": "The Distri",
"state": "active"
}

Feed

Get Feeds

Return the list of all feeds of the given Broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

query Parameters

q	string (FilterQuery) Example: q=fil Query string to filter the result
state	string (StateFilter) Enum: "active" "deleted" Example: state=active State to filter the result

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"feeds": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx"
}
],
"id": "xxxxxxxxxx",
"name": "The feed 1",
"state": "active"
},
{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/yyyyyyyyy"
}
],
"id": "yyyyyyyyy",
"name": "The feed 2",
"state": "active"
}
]
}

Create Feed

Create a feed

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

name required	string [ 1 .. 256 ] characters Feed name
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)
commands_on	Array of strings Commands to subscribe to the feed (straight quotation marks are not allowed).
commands_off	Array of strings Commands to unsubscribe to the feed (straight quotation marks are not allowed).
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)

Responses

Request samples

Payload

Content type

application/json

{"name": "The new feed name",
"description": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"commands_on": ["start {channel}"
],
"commands_off": ["stop {channel}"
],
"message_on": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"message_off": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Response samples

201

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds"
}
],
"id": "3334osykj4",
"name": "The feed",
"state": "active",
"description": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"commands_on": ["start {channel}"
],
"commands_off": ["stop {channel}"
],
"message_on": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"message_off": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Get Feed Details

Return details of a feed

Authorizations:

apiKey

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

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds"
}
],
"id": "3334osykj4",
"name": "The feed",
"state": "active",
"description": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"commands_on": ["start {channel}"
],
"commands_off": ["stop {channel}"
],
"message_on": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"message_off": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Update Feed

Update a feed

Authorizations:

apiKey

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
required

name required	string [ 1 .. 256 ] characters Feed name
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)
commands_on	Array of strings Commands to subscribe to the feed (straight quotation marks are not allowed).
commands_off	Array of strings Commands to unsubscribe to the feed (straight quotation marks are not allowed).
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)

Responses

Request samples

Payload

Content type

application/json

{"name": "Feed 2.0",
"description": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"commands_on": ["start {channel}"
],
"commands_off": ["stop {channel}"
],
"message_on": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"message_off": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds"
}
],
"id": "3334osykj4",
"name": "The feed",
"state": "active",
"description": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"commands_on": ["start {channel}"
],
"commands_off": ["stop {channel}"
],
"message_on": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"message_off": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Delete Feed

Delete the feed (state dependency = 'deleted')

Authorizations:

apiKey

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

Get Chat History of Feed

Return all messages of a feed

Authorizations:

apiKey

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

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "feed",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/yyyyyyyyyy"
}
],
"messages": [{"uid": "PV9M5iWXat",
"subject": "null",
"author": "info@threema.ch",
"trackDelivery": "false",
"createdAt": "2018-02-28T22:20:04+0100",
"startAt": "2018-02-28T22:20:04+0100",
"doneAt": "2018-02-28T22:20:04+0100",
"stats": {"failed": "0",
"successfully": "42",
"received": "42",
"read": "42",
"ack": "42",
"dec": "42",
"total": "42"
}
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Send Message

Send a message to a feed

Authorizations:

apiKey

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

type	string Message type text
subject	string or null (ChatMessageSubject) Default: null Custom subject of the message
trackDelivery	boolean Default: false (only if feature is granted:) Determinate if message delivery should be tracked
startAt	integer Default: null (only if feature is granted:) Specify sending time (UTC Timestamp)
	object (ChatMessageTranslation) All translated messages (Max. 3500 bytes per message)

Responses

Request samples

Payload

Content type

application/json

Example

text

{"type": "text",
"subject": "null",
"trackDelivery": false,
"startAt": null,
"body": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Response samples

201

Content type

application/json

Example

text

{"uid": "PV9M5iWXat",
"subject": "null",
"author": "info@threema.ch",
"trackDelivery": "false",
"createdAt": "2018-02-28T22:20:04+0100",
"startAt": "2018-02-28T22:20:04+0100",
"doneAt": "2018-02-28T22:20:04+0100",
"stats": {"failed": "0",
"successfully": "42",
"received": "42",
"read": "42",
"ack": "42",
"dec": "42",
"total": "42"
},
"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/3334osykj4/chat/PV9M5iWXat"
},
{"ref": "feed",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/3334osykj4"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/3334osykj4/chat"
}
],
"type": "text",
"body": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Get Message

Return a message of a feed

Authorizations:

apiKey

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
feedChatMessageUid required	string (FeedChatMessageUid) = 10 characters Example: PV9M5iWXat Uid of the feed message

Responses

Response samples

200

Content type

application/json

Example

text

{"uid": "PV9M5iWXat",
"subject": "null",
"author": "info@threema.ch",
"trackDelivery": "false",
"createdAt": "2018-02-28T22:20:04+0100",
"startAt": "2018-02-28T22:20:04+0100",
"doneAt": "2018-02-28T22:20:04+0100",
"stats": {"failed": "0",
"successfully": "42",
"received": "42",
"read": "42",
"ack": "42",
"dec": "42",
"total": "42"
},
"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/3334osykj4/chat/PV9M5iWXat"
},
{"ref": "feed",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/3334osykj4"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/3334osykj4/chat"
}
],
"type": "text",
"body": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Delete Message

Remove a message from a feed

Authorizations:

apiKey

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
feedChatMessageUid required	string (FeedChatMessageUid) = 10 characters Example: PV9M5iWXat Uid of the feed message

Responses

Get Message Delivery

Return message delivery stats of a feed message

Authorizations:

apiKey

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
feedChatMessageUid required	string (FeedChatMessageUid) = 10 characters Example: PV9M5iWXat Uid of the feed message

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Request Body schema: application/json
required

q	string [ 1 .. 256 ] characters filter query
state	Array of strings (DeliveryState) filter state

Responses

Request samples

Payload

Content type

application/json

{"q": "ECHOECHO Receiver Name",
"state": ["sent",
"received",
"read",
"ack",
"dec"
]
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"deliveries": [{"date": "2018-02-28T22:20:04+0100",
"id": "ECHOECHO",
"firstName": "E",
"lastName": "Cho",
"language": "en",
"state": "ack"
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Get Message File

Return a base64 file content of a feed. Only outgoing files can be viewed in Broadcast; incoming files will not be saved and can therefore not be viewed.

Authorizations:

apiKey

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
feedChatMessageUid required	string (FeedChatMessageUid) = 10 characters Example: PV9M5iWXat Uid of the feed message

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/yyyyyyyyyy/chat/PV9M5iWXat"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/yyyyyyyyyy/chat"
},
{"ref": "feed",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/yyyyyyyyyy"
}
],
"file": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==",
"filename": "filename.dat",
"mimetype": "application/octet-stream"
}

Get Feed Subscribers

Return the list of all subscribers of a feed

Authorizations:

apiKey

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

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "feed",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx"
}
],
"recipients": [{"id": "ECHOECHO",
"firstName": "E",
"lastName": "Cho",
"language": "en",
"state": "active"
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Add Feed Subscribers

Add subscribers to a feed

Authorizations:

apiKey

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
required

recipients required	Array of strings (ThreemaId) [ items = 8 characters ] List of Threema IDs
replaceExisting	boolean Default: false Replace existing subscribers with new list of subscribers
filterInvalid	boolean Default: false Filter invalid and revoked Threema IDs

Responses

Request samples

Payload

Content type

application/json

{"recipients": ["B4UXXX11"
],
"replaceExisting": false,
"filterInvalid": false
}

Response samples

200

Content type

application/json

["0-12",
"ECHOECHOECHO",
"REVOKED"
]

Remove Feed Subscribers

Remove subscribers to a feed

Authorizations:

apiKey

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
required

recipients

required

Array of strings (ThreemaId) [ items = 8 characters ]

List of Threema IDs to remove from the feed

Responses

Request samples

Payload

Content type

application/json

{"recipients": ["B4UXXX11"
]
}

Update Feed State

Update the state of a feed

Authorizations:

apiKey

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
feedState required	string (FeedState) Enum: "active" "deleted" Example: active state of the feed.

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx"
},
{"ref": "recipients",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/recipients"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/xxxxxxxxxx/chat"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds"
}
],
"id": "3334osykj4",
"name": "The feed",
"state": "active",
"description": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"commands_on": ["start {channel}"
],
"commands_off": ["stop {channel}"
],
"message_on": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"message_off": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Group

Get Groups

Return the list of all groups of the given Broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
optional

states	Array of strings or null (GroupState) Enum: "active" "deleted" states of the group
saveChatHistory	boolean or null only show groups which saves or does not save chat history

Responses

Request samples

Payload

Content type

application/json

{"states": ["active",
"deleted"
],
"saveChatHistory": true
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"groups": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaa"
}
],
"id": "aaaaaa",
"name": "Group 1",
"state": "active",
"saveChatHistory": false
},
{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/bbbbbb"
}
],
"id": "bbbbbb",
"name": "Group 2",
"state": "deleted",
"saveChatHistory": true
}
]
}

Create Group

Create a group

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

name required	string [ 0 .. 256 ] characters Name of the new group
members required	Array of strings List of Threema IDs
saveChatHistory	boolean Once this setting is activated, the entire group conversation (including incoming messages) is saved. All group members will be notified about changes to this setting.
filterInvalid	boolean Default: false Filter double, invalid and revoked Threema IDs

Responses

Request samples

Payload

Content type

application/json

{"name": "Project Baxter",
"members": ["ECHOECHO"
],
"saveChatHistory": true,
"filterInvalid": false
}

Response samples

201

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
},
{"ref": "member",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/members"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/chat"
},
{"ref": "image",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/image"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups"
}
],
"id": "oopphh22uu",
"name": "Project Farfalla",
"state": "active",
"saveChatHistory": false
}

Get Group Details

Return details of a group

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
},
{"ref": "member",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/members"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/chat"
},
{"ref": "image",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/image"
},
{"ref": "index",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups"
}
],
"id": "oopphh22uu",
"name": "Project Farfalla",
"state": "active",
"saveChatHistory": false
}

Update Group

Update the details of a group

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Request Body schema: application/json
required

name required	string [ 0 .. 256 ] characters The new name for the group
saveChatHistory	boolean Once this setting is activated, the entire group conversation (including incoming messages) is saved. All group members will be notified about changes to this setting.

Responses

Request samples

Payload

Content type

application/json

{"name": "Project Bauxi",
"saveChatHistory": true
}

Remove Group

Remove a group, and send the information to all members

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Responses

Get Group Chat History

Return all messages of a group chat

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "group",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
}
],
"messages": [{"id": "GbeRraMd7S",
"messageId": "7b324aca6b4509ea",
"from": "SENDERXY",
"type": "string",
"body": "How are you?",
"caption": "Does this look good?",
"createdAt": "2018-02-28T22:20:04+0100"
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Send Group Message

Send a message to a group

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Request Body schema: application/json

type	string Message type text
body	string <= 3500 characters Content of the message (Max 3500 bytes)

Responses

Request samples

Payload

Content type

application/json

Example

text

{"type": "text",
"body": "Hello, this is a test message!"
}

Response samples

201

Content type

application/json

Example

text

{"id": "GbeRraMd7S",
"messageId": "7b324aca6b4509ea",
"from": "SENDERXY",
"type": "text",
"body": "message body",
"caption": "Does this look good?",
"createdAt": "2018-02-28T22:20:04+0100",
"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/chat/012abf39ef012003e"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/chat"
},
{"ref": "group",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
}
]
}

Get Message of Group Chat

Return a message of a group chat

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group
groupChatMessageUid required	string (GroupChatMessageUid) = 10 characters Example: GbeRraMd7S Uid of the group message

Responses

Response samples

200

Content type

application/json

Example

text

{"id": "GbeRraMd7S",
"messageId": "7b324aca6b4509ea",
"from": "SENDERXY",
"type": "text",
"body": "message body",
"caption": "Does this look good?",
"createdAt": "2018-02-28T22:20:04+0100",
"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/chat/012abf39ef012003e"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/chat"
},
{"ref": "group",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
}
]
}

Delete Group Message

Remove a message from a group chat

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group
groupChatMessageUid required	string (GroupChatMessageUid) = 10 characters Example: GbeRraMd7S Uid of the group message

Responses

Get File Content of Group Chat Message

Return a base64 file content of a group chat message. Only outgoing files can be viewed in Broadcast; incoming files will not be saved and can therefore not be viewed.

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group
groupChatMessageUid required	string (GroupChatMessageUid) = 10 characters Example: GbeRraMd7S Uid of the group message

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/012abf39ef012003e"
},
{"ref": "chat",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa/chat"
},
{"ref": "group",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
}
],
"file": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+P+/HgAFhAJ/wlseKgAAAABJRU5ErkJggg==",
"filename": "filename.dat",
"mimetype": "application/octet-stream"
}

Get Group Image

Return base64 encoded jpeg / png image or null

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "group",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
}
],
"image": "/9j/4AAQSkZJRgABAQAAAQABAAD//gAfQ29tcHJlc3NlZCBieSBqcGVnLXJlY29tcHJlc3P/2wCEAAQEBAQEBAQEBAQGBgUGBggHBwcHCAwJCQkJCQwTDA4MDA4MExEUEA8QFBEeFxUVFx4iHRsdIiolJSo0MjRERFwBBAQEBAQEBAQEBAYGBQYGCAcHBwcIDAkJCQkJDBMMDgwMDgwTERQQDxAUER4XFRUXHiIdGx0iKiUlKjQyNEREXP/CABEIAAEAAQMBIgACEQEDEQH/xAAUAAEAAAAAAAAAAAAAAAAAAAAH/9oACAEBAAAAAEL/xAAUAQEAAAAAAAAAAAAAAAAAAAAI/9oACAECEAAAACj/AP/EABQBAQAAAAAAAAAAAAAAAAAAAAj/2gAIAQMQAAAAJ/8A/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAgEBPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAwEBPwB//9k="
}

Update Group image

Update the image of the group

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Request Body schema: application/json
required

image

required

string

a base 64 encoded square jpeg or png image - max 512px. non fitting dimensions will be cropped

Responses

Request samples

Payload

Content type

application/json

{"image": "/9j/4AAQSkZJRgABAQAAAQABAAD//gAfQ29tcHJlc3NlZCBieSBqcGVnLXJlY29tcHJlc3P/2wCEAAQEBAQEBAQEBAQGBgUGBggHBwcHCAwJCQkJCQwTDA4MDA4MExEUEA8QFBEeFxUVFx4iHRsdIiolJSo0MjRERFwBBAQEBAQEBAQEBAYGBQYGCAcHBwcIDAkJCQkJDBMMDgwMDgwTERQQDxAUER4XFRUXHiIdGx0iKiUlKjQyNEREXP/CABEIAAEAAQMBIgACEQEDEQH/xAAUAAEAAAAAAAAAAAAAAAAAAAAH/9oACAEBAAAAAEL/xAAUAQEAAAAAAAAAAAAAAAAAAAAI/9oACAECEAAAACj/AP/EABQBAQAAAAAAAAAAAAAAAAAAAAj/2gAIAQMQAAAAJ/8A/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAgEBPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAwEBPwB//9k="
}

Remove Group image

Remove the groupimage

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Responses

Get Members

Return the list of all members of a group

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "group",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/aaaaaaaa"
}
],
"members": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/recipients/AAAAAAAA"
}
],
"id": "AAAAAAAA",
"firstName": null,
"lastName": null,
"language": null,
"state": "string"
},
{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/recipients/BBBBBBBB"
}
],
"id": "BBBBBBBB",
"firstName": null,
"lastName": null,
"language": null,
"state": "string"
}
]
}

Add Group Members

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Request Body schema: application/json
required

List of the new Threema IDs

One of

members required	Array of strings (ThreemaId) [ items = 8 characters ] List of Threema IDs
replaceExisting	boolean Default: false Replace existing members with new list of members
filterInvalid	boolean Default: false Filter double, invalid and revoked Threema IDs

Responses

Request samples

Payload

Content type

application/json

Example

GroupMemberAdd

{"members": ["B4UXXX11"
],
"replaceExisting": false,
"filterInvalid": false
}

Response samples

200

Content type

application/json

["0-12",
"ECHOECHOECHO",
"REVOKED"
]

Remove Members

Remove members from a group chat

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Request Body schema: application/json
required

List of the Threema IDs

Array

string (ThreemaId) = 8 characters

Threema ID of the recipient

Responses

Request samples

Payload

Content type

application/json

["B4UXXX11",
"ECHOECHO"
]

Remove invalid Identities

Remove invalid identities of a group

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
groupUid required	string (GroupUid) = 10 characters Example: oopphh22uu Uid of the group

Responses

Response samples

200

Content type

application/json

["B4UXXX11",
"ECHOECHO"
]

Identity

Get Identities

Return the list of all Broadcast identities

Authorizations:

apiKey

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "home",
"link": "https://broadcast.threema.ch/api/v1/"
}
],
"identities": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"id": "xxyyzz0099",
"threemaId": "*BC00001",
"validUntil": "2018-02-28T22:20:04+0100",
"type": "o500",
"recipientLimit": 500
},
{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/pw5oa30xpl"
}
],
"id": "pw5oa30xpl",
"threemaId": "*BC00002",
"validUntil": "2018-02-28T22:20:04+0100",
"type": "unlimited",
"recipientLimit": null
}
]
}

Get Identity Details

Return details of the given Broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"id": "xxyyzz0099",
"threemaId": "*BC00001",
"validUntil": "2018-02-28T22:20:04+0100",
"type": "o500",
"recipientLimit": 500,
"nickname": "Nick Name",
"description": "Used by the sales departement",
"private": true,
"privateMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"invalidCommandMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"switchLanguageMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Update Identity Details

Update the details of the given Broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

nickname required	string [ 1 .. 32 ] characters Name for your Broadcast ID. This name will show up on the recipients’ end when you send them a message.
description	string Description for your Broadcast ID. This description is not used anywhere and only exists as an internal notes field.
private	boolean If the Private Broadcast is enabled, its contents are only accessible to specified recipients. By disabling this setting the Broadcast becomes public: anyone who knows the Broadcast ID can use bots and subscribe to feeds.
	object (PrivateBroadcastMessageTranslation) Automatic response to users who don’t have access to the private Broadcast. All translated messages (Max. 3500 bytes per message).
	object (InvalidCommandMessageTranslation) This text will be returned if users enter an invalid command. All translated messages (Max. 3500 bytes per message).
	object (SwitchLanguageMessageTranslation) This text will be returned after users switch languages. All translated messages (Max. 3500 bytes per message).

Responses

Request samples

Payload

Content type

application/json

{"nickname": "Nick Name",
"description": "Used by the sales departement",
"private": true,
"privateMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"invalidCommandMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"switchLanguageMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"id": "xxyyzz0099",
"threemaId": "*BC00001",
"validUntil": "2018-02-28T22:20:04+0100",
"type": "o500",
"recipientLimit": 500,
"nickname": "Nick Name",
"description": "Used by the sales departement",
"private": true,
"privateMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"invalidCommandMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
},
"switchLanguageMessage": {"de": "Nachricht",
"en": "Message",
"tlh": "Qln"
}
}

Get Identity Avatar

Return base64 encoded jpeg / png image or null

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"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

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

avatar

required

string

base 64 encoded jpeg /png image

Responses

Request samples

Payload

Content type

application/json

{"avatar": "/9j/4AAQSkZJRgABAQAAAQABAAD//gAfQ29tcHJlc3NlZCBieSBqcGVnLXJlY29tcHJlc3P/2wCEAAQEBAQEBAQEBAQGBgUGBggHBwcHCAwJCQkJCQwTDA4MDA4MExEUEA8QFBEeFxUVFx4iHRsdIiolJSo0MjRERFwBBAQEBAQEBAQEBAYGBQYGCAcHBwcIDAkJCQkJDBMMDgwMDgwTERQQDxAUER4XFRUXHiIdGx0iKiUlKjQyNEREXP/CABEIAAEAAQMBIgACEQEDEQH/xAAUAAEAAAAAAAAAAAAAAAAAAAAH/9oACAEBAAAAAEL/xAAUAQEAAAAAAAAAAAAAAAAAAAAI/9oACAECEAAAACj/AP/EABQBAQAAAAAAAAAAAAAAAAAAAAj/2gAIAQMQAAAAJ/8A/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAgEBPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAwEBPwB//9k="
}

Delete Identity Avatar

Delete the identity avatar

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Responses

Get identity languages

Return languages of the given broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"languages": [{"uid": "XZax9jV5QH",
"isoCode": "de-CH",
"name": "Schweiz",
"default": true
}
]
}

Create identity language

Create a new identity language

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

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

Request samples

Payload

Content type

application/json

{"name": "Schweiz",
"isoCode": "de-CH",
"default": true
}

Response samples

201

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"uid": "XZax9jV5QH",
"name": "Schweiz",
"isoCode": "de-CH",
"default": true
}

Set identity languages order

Set the order of identity languages

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

order

required

Array of strings

ordered array of all language uid strings

Responses

Request samples

Payload

Content type

application/json

{"order": ["XZax9jV5QH"
]
}

Get identity language

Return the Identity language

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
languageUid required	string (IdentityLanguageUid) Example: XZax9jV5QH uid of the identity language

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"uid": "XZax9jV5QH",
"name": "Schweiz",
"isoCode": "de-CH",
"default": true
}

Update identity language

Updates an existing identity language

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
languageUid required	string (IdentityLanguageUid) Example: XZax9jV5QH uid of the identity language

Request Body schema: application/json
required

name	string [ 1 .. 50 ] characters Name of the new language
isoCode	string [ 1 .. 5 ] characters ISO Code of the new language
default	boolean determinate if the new language should be the default language

Responses

Request samples

Payload

Content type

application/json

{"name": "Schweiz",
"isoCode": "de-CH",
"default": true
}

Response samples

201

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"uid": "XZax9jV5QH",
"name": "Schweiz",
"isoCode": "de-CH",
"default": true
}

Delete identity language

Delete an existing identity language

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
languageUid required	string (IdentityLanguageUid) Example: XZax9jV5QH uid of the identity language

Responses

Get Recipients

Return the list of all recipients of the given Broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"recipients": [{"id": "ECHOECHO",
"firstName": "E",
"lastName": "Cho",
"language": "en",
"state": "active"
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Delete Recipients

Remove a list of recipients of the given Broadcast identity from all lists and groups. Note that the actual removal of recipients will happen asynchronously.

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

recipients

required

Array of strings (ThreemaId) [ items = 8 characters ]

List of Threema IDs to remove from the feed

Responses

Request samples

Payload

Content type

application/json

{"recipients": ["B4UXXX11"
]
}

Get Recipient Details

Return details of a recipient

Authorizations:

apiKey

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

Response samples

200

Content type

application/json

{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/recipients/ECHOECHO"
}
],
"id": "B4UXXX11",
"firstName": "E",
"lastName": "Cho",
"language": "en",
"state": "active"
}

Update Recipient

Update a recipient’s details

Authorizations:

apiKey

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
required

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

Request samples

Payload

Content type

application/json

{"firstName": "Peter",
"lastName": "Black",
"language": "en"
}

Replace Recipient

Replace an existing recipient in all ditributionLists, feeds and groups with a new one.
Does not replace the recipient in work-synced lists (eg: 'All').

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
threemaId required	string (ThreemaId) = 8 characters Example: B4UXXX11 Existing Threema ID of the recipient

Request Body schema: application/json
required

newThreemaId

required

string = 8 characters

New Threema ID of the recipient

Responses

Request samples

Payload

Content type

application/json

{"newThreemaId": "B4UXXX11"
}

Response samples

200

Content type

application/json

{"distributionLists": ["G53cS1E817"
],
"feeds": ["EfZ6LIBl1i"
],
"groups": ["anQGXlI62c"
]
}

Avatar

Get Identity Avatar

Return base64 encoded jpeg / png image or null

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
}
],
"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

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
required

avatar

required

string

base 64 encoded jpeg /png image

Responses

Request samples

Payload

Content type

application/json

{"avatar": "/9j/4AAQSkZJRgABAQAAAQABAAD//gAfQ29tcHJlc3NlZCBieSBqcGVnLXJlY29tcHJlc3P/2wCEAAQEBAQEBAQEBAQGBgUGBggHBwcHCAwJCQkJCQwTDA4MDA4MExEUEA8QFBEeFxUVFx4iHRsdIiolJSo0MjRERFwBBAQEBAQEBAQEBAYGBQYGCAcHBwcIDAkJCQkJDBMMDgwMDgwTERQQDxAUER4XFRUXHiIdGx0iKiUlKjQyNEREXP/CABEIAAEAAQMBIgACEQEDEQH/xAAUAAEAAAAAAAAAAAAAAAAAAAAH/9oACAEBAAAAAEL/xAAUAQEAAAAAAAAAAAAAAAAAAAAI/9oACAECEAAAACj/AP/EABQBAQAAAAAAAAAAAAAAAAAAAAj/2gAIAQMQAAAAJ/8A/8QAFBABAAAAAAAAAAAAAAAAAAAAAP/aAAgBAQABPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAgEBPwB//8QAFBEBAAAAAAAAAAAAAAAAAAAAAP/aAAgBAwEBPwB//9k="
}

Delete Identity Avatar

Delete the identity avatar

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Responses

Profile

Get Profile

Get access to your Broadcast data

Authorizations:

apiKey

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "identities",
"link": "https://broadcast.threema.ch/api/v1/identities"
}
]
}

Poll

Get Polls

(only if feature is granted:) Return the list of all polls of the given Broadcast identity

Authorizations:

apiKey

path Parameters

broadcastUid

required

string (BroadcastUid) = 10 characters

Example: xxyyzz0099

Uid of the Broadcast identity

Request Body schema: application/json
optional

states	Array of strings or null (PollState) Enum: "open" "closed" states of the poll
choice_modes	Array of strings or null (PollChoiceMode) Enum: "single" "multiple" choice modes of the poll

Responses

Request samples

Payload

Content type

application/json

{"states": ["open",
"closed"
],
"choice_modes": ["single",
"multiple"
]
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "distributionList",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distributionList/yyyyyyyyyy"
}
],
"polls": [{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/polls/aabb112233"
}
],
"uid": "aabb112233",
"state": "open",
"choice_mode": "single",
"detailedResults": true,
"distinctVotes": 15,
"titles": {"en": "title",
"de": "titel"
},
"choices": [{"uid": "7PcoUKecxm",
"name": {"en": "Choice #1",
"de": "Antwortmöglichkeit #1"
}
},
{"uid": "8PcoUKecxm",
"name": {"en": "Choice #2",
"de": "Antwortmöglichkeit #2"
}
}
]
},
{"_links": [{"ref": "detail",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/polls/aabb112233"
}
],
"uid": "ccee445566",
"state": "closed",
"choice_mode": "multiple",
"detailedResults": true,
"distinctVotes": 50,
"titles": {"en": "title",
"de": "titel"
},
"choices": [{"uid": "9PcoUKecxm",
"name": {"en": "Choice #1",
"de": "Antwortmöglichkeit #1"
}
},
{"uid": "0PcoUKecxm",
"name": {"en": "Choice #2",
"de": "Antwortmöglichkeit #2"
}
}
]
}
]
}

Get Poll Details

Return details of a poll

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
pollUid required	string (PollUid) = 10 characters Example: edMk465KIA uid of the poll

Responses

Response samples

200

Content type

application/json

{"_links": [{"ref": "distributionListChatMessage",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/distribution_lists/yyyyyyyyyy/chat/PV9M5iWXat"
},
{"ref": "feedChatMessage",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/feeds/3334osykj4/chat/PV9M5iWXat"
},
{"ref": "closePoll",
"link": "http://broadcast.threema.local/api/v1/identities/xxyyzz0099/polls/aabb112233/close"
},
{"ref": "choiceVotes",
"link": "http://broadcast.threema.local/api/v1/identities/xxyyzz0099/polls/aabb112233/choice/2NK7ELWZ9v/votes"
}
],
"uid": "edMk465KIA",
"state": "open",
"choiceMode": "single",
"detailedResults": true,
"distinctVotes": 15,
"title": {"de": "Titel",
"en": "Title",
"tlh": "Qln"
},
"choices": [{"uid": "7PcoUKecxm",
"votes": 42,
"name": {"de": "Antwortmöglichkeit #1",
"en": "Choice #1",
"tlh": "Qln"
}
}
]
}

Get Poll Choice Votes

Get a list of poll choice votes

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
pollUid required	string (PollUid) = 10 characters Example: edMk465KIA uid of the poll
pollChoiceUid required	string (PollChoiceUid) = 10 characters Example: 7PcoUKecxm uid of the poll choice

query Parameters

page	integer (Page) Example: page=9 Number of page (starting with: 0)
pageSize	integer (PageSize) Example: pageSize=20 Results per page (max. recommended: 1000)

Request Body schema: application/json
required

q	string [ 1 .. 255 ] characters filter query
vote	boolean filter votes

Responses

Request samples

Payload

Content type

application/json

{"q": "ECHOECHO",
"vote": true
}

Response samples

200

Content type

application/json

{"_links": [{"ref": "identity",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099"
},
{"ref": "poll",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/polls/aabb112233"
}
],
"votes": [{"id": "ECHOECHO",
"vote": true
}
],
"_paging": {"count": 20,
"total": 400,
"page": 9,
"_links": [{"ref": "next",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=10&pageSize=20"
},
{"ref": "previous",
"link": "https://broadcast.threema.ch/api/v1/identities/xxyyzz0099/groups/oopphh22uu/chat?page=8&pageSize=20"
}
]
}
}

Close Poll

Close an open poll

Authorizations:

apiKey

path Parameters

broadcastUid required	string (BroadcastUid) = 10 characters Example: xxyyzz0099 Uid of the Broadcast identity
pollUid required	string (PollUid) = 10 characters Example: edMk465KIA uid of the poll

Threema Broadcast API (1.12.2)

Bot

Get Bots

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Create Bot

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get Bot Details

Authorizations:

path Parameters

Responses

Response samples

Update Bot

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Delete Bot

Authorizations:

path Parameters

Responses

Delete bot command

Authorizations:

path Parameters

Responses

Get bot commands

Authorizations:

path Parameters

Responses

Response samples

Create bot command

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get Bot Command Details

Authorizations:

path Parameters

Responses

Response samples

Update Bot Command

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Update Bot State

Authorizations:

path Parameters

Responses

Response samples

Distribution List

Get Distribution Lists

Authorizations:

path Parameters

query Parameters

Responses

Response samples

Create Distribution List

Authorizations:

path Parameters

Request Body schema: application/jsonrequired

Responses

Request samples

Response samples

Get Distribution List Details

Authorizations:

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required

Request Body schema: application/json
required