Add a label to a topic
curl --request POST \
--url https://api.zenzap.co/v2/topics/{topicId}/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Signature: <api-key>' \
--data '
{
"labelId": "ef38388f-4cd0-46a7-9935-bac86dbc442b"
}
'import requests
url = "https://api.zenzap.co/v2/topics/{topicId}/labels"
payload = { "labelId": "ef38388f-4cd0-46a7-9935-bac86dbc442b" }
headers = {
"Authorization": "Bearer <token>",
"X-Signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Signature': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({labelId: 'ef38388f-4cd0-46a7-9935-bac86dbc442b'})
};
fetch('https://api.zenzap.co/v2/topics/{topicId}/labels', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zenzap.co/v2/topics/{topicId}/labels",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'labelId' => 'ef38388f-4cd0-46a7-9935-bac86dbc442b'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Signature: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zenzap.co/v2/topics/{topicId}/labels"
payload := strings.NewReader("{\n \"labelId\": \"ef38388f-4cd0-46a7-9935-bac86dbc442b\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zenzap.co/v2/topics/{topicId}/labels")
.header("Authorization", "Bearer <token>")
.header("X-Signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"labelId\": \"ef38388f-4cd0-46a7-9935-bac86dbc442b\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zenzap.co/v2/topics/{topicId}/labels")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"labelId\": \"ef38388f-4cd0-46a7-9935-bac86dbc442b\"\n}"
response = http.request(request)
puts response.read_body{
"id": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
"ef38388f-4cd0-46a7-9935-bac86dbc442b"
],
"updatedAt": 1699564800000
}"text is required""unauthorized""Topic not found""internal server error"Topics (group chats/channels/conversations)
Add a label to a topic
Add a label to an existing topic. Labels are defined per organization — use
GET /v2/organization/labels to discover the available label IDs.
Authorization: Your API key bot must be a member of the topic (returns 404 if not).
Validation:
labelIdmust be a valid UUID belonging to your organization (returns 400 “Invalid labelId” otherwise)- A topic can carry at most 1 label (returns 400 if the cap is exceeded)
Behavior: Idempotent — re-adding a label already on the topic returns the current state.
POST
/
v2
/
topics
/
{topicId}
/
labels
Add a label to a topic
curl --request POST \
--url https://api.zenzap.co/v2/topics/{topicId}/labels \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--header 'X-Signature: <api-key>' \
--data '
{
"labelId": "ef38388f-4cd0-46a7-9935-bac86dbc442b"
}
'import requests
url = "https://api.zenzap.co/v2/topics/{topicId}/labels"
payload = { "labelId": "ef38388f-4cd0-46a7-9935-bac86dbc442b" }
headers = {
"Authorization": "Bearer <token>",
"X-Signature": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
Authorization: 'Bearer <token>',
'X-Signature': '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({labelId: 'ef38388f-4cd0-46a7-9935-bac86dbc442b'})
};
fetch('https://api.zenzap.co/v2/topics/{topicId}/labels', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.zenzap.co/v2/topics/{topicId}/labels",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'labelId' => 'ef38388f-4cd0-46a7-9935-bac86dbc442b'
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json",
"X-Signature: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.zenzap.co/v2/topics/{topicId}/labels"
payload := strings.NewReader("{\n \"labelId\": \"ef38388f-4cd0-46a7-9935-bac86dbc442b\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("X-Signature", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.zenzap.co/v2/topics/{topicId}/labels")
.header("Authorization", "Bearer <token>")
.header("X-Signature", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"labelId\": \"ef38388f-4cd0-46a7-9935-bac86dbc442b\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.zenzap.co/v2/topics/{topicId}/labels")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["X-Signature"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"labelId\": \"ef38388f-4cd0-46a7-9935-bac86dbc442b\"\n}"
response = http.request(request)
puts response.read_body{
"id": "550e8400-e29b-41d4-a716-446655440000",
"labels": [
"ef38388f-4cd0-46a7-9935-bac86dbc442b"
],
"updatedAt": 1699564800000
}"text is required""unauthorized""Topic not found""internal server error"Authorizations
bearerAuth & hmacSignatureoauth2ClientCredentials
Bearer token for the request. Two flavors:
- Static API key — pass your API key (the value returned as
apiKeywhen the bot was created). Must be paired withX-Signature+X-Timestamp(thehmacSignaturescheme). - OAuth access token — pass the JWT returned by
POST /oauth/token. No signature headers are required.
HMAC-SHA256 signature for request verification. Required only when authenticating with a static API key. Omit when using an OAuth access token.
Headers
HMAC signature of the request for authentication and replay protection.
Required only when authenticating with a static API key. If you are using an OAuth access token (issued by POST /oauth/token), omit this header — the JWT carries all the authentication and integrity guarantees.
Replay Protection: The signature includes a timestamp to prevent replay attacks. Requests with timestamps older than 5 minutes are rejected.
The signature payload differs by HTTP method:
- POST/PUT/PATCH/DELETE: HMAC-SHA256 of
{timestamp}.{body} - GET: HMAC-SHA256 of
{timestamp}.{uri}
The signature is calculated as:
- Get the current Unix timestamp in milliseconds
- Determine the payload:
- For POST/PUT/PATCH/DELETE: Use
{timestamp}.{body}where body is the request body - For GET: Use
{timestamp}.{uri}where uri is the full request URI (e.g.,/v2/members?limit=10)
- For POST/PUT/PATCH/DELETE: Use
- Calculate HMAC-SHA256 of the combined payload using your API secret
- Hex-encode the output
- Include the timestamp in the
X-Timestampheader
Example for GET request to /v2/members?limit=10:
timestamp = 1699564800000 payload = "1699564800000./v2/members?limit=10" signature = HMAC-SHA256(secret, payload) X-Signature: hex(signature) X-Timestamp: 1699564800000
Example for POST request with body {"topicId":"123","text":"Hello"}:
timestamp = 1699564800000 payload = '1699564800000.{"topicId":"123","text":"Hello"}' signature = HMAC-SHA256(secret, payload) X-Signature: hex(signature) X-Timestamp: 1699564800000
For multipart/form-data requests, sign the exact raw request body bytes
(including boundaries and file bytes) as transmitted.
Pattern:
^[a-f0-9]{64}$Example:
"a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6"
Unix timestamp in milliseconds when the request was created. Used for replay protection — requests older than 5 minutes are rejected.
Required only when authenticating with a static API key. Omit when using an OAuth access token.
Example:
1699564800000
Path Parameters
The ID of the topic to add a label to
Body
application/json
The ID of the organization label to add to the topic. Must belong to your organization (see GET /v2/organization/labels).
Example:
"ef38388f-4cd0-46a7-9935-bac86dbc442b"
Response
Label added successfully