Skip to main content
POST
/
v2
/
topics
curl --request POST \ --url https://api.zenzap.co/v2/topics \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --header 'X-Signature: <api-key>' \ --data ' { "name": "Project Updates", "members": [ "550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002" ] } '
{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "name": "Project Updates",
  "members": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002",
    "b@660e8400-e29b-41d4-a716-446655440003"
  ],
  "externalId": "b@660e8400-e29b-41d4-a716-446655440003:campaign-q4-2024",
  "createdAt": 1699564800000
}

Authorizations

​
Authorization
string
header
required

Use your API key as the Bearer token. You can view your API key and secret in your Zenzap organization API key settings.

​
X-Signature
string
header
required

HMAC-SHA256 signature for request verification.

Headers

​
X-Signature
string
required

HMAC signature of the request.

The signature payload differs by HTTP method:

  • POST/PUT/PATCH/DELETE: HMAC-SHA256 of the request body
  • GET: HMAC-SHA256 of the full request URI (path + query string)

The signature is calculated as:

  1. Determine the payload:
    • For POST/PUT/PATCH/DELETE: Use the request body
    • For GET: Use the full request URI (e.g., /v2/members?limit=10&offset=0)
  2. Calculate HMAC-SHA256 of the payload using your API secret
  3. Hex-encode the output

Example for GET request to /v2/members?limit=10:

payload = "/v2/members?limit=10"
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)

Example for POST request with body {"topicId":"123","text":"Hello"}:

payload = '{"topicId":"123","text":"Hello"}'
signature = HMAC-SHA256(secret, payload)
X-Signature: hex(signature)
Example:

"a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6"

Body

application/json
​
name
string
required

The topic name

Maximum string length: 64
Example:

"Project Updates"

​
description
string

Optional topic description

Maximum string length: 10000
Example:

"Discussion for project milestones"

​
members
string<uuid>[]

Array of user IDs to add as topic members. Your bot will automatically be added as a member.

Example:
[
  "550e8400-e29b-41d4-a716-446655440001",
  "550e8400-e29b-41d4-a716-446655440002"
]
​
externalId
string

Optional external identifier for tracking purposes. Must be unique per bot - you cannot reuse the same external ID for multiple topics.

Maximum string length: 100
Example:

"project-alpha"

Response

Topic created successfully

​
id
string<uuid>

The created topic ID

​
name
string

The topic name

​
members
string[]

Array of member IDs in the topic (including the bot)

Example:
[
  "550e8400-e29b-41d4-a716-446655440001",
  "b@660e8400-e29b-41d4-a716-446655440003"
]
​
externalId
string

The fully qualified external ID (bot_id:your_external_id). Only present if externalId was provided in the request.

Example:

"b@660e8400-e29b-41d4-a716-446655440003:project-alpha"

​
createdAt
integer<int64>

Unix timestamp in milliseconds