ZEzenzap
Topics (group chats/channels/conversations)

Create a topic

Create a new topic with specified members. Your API key bot will automatically be added as a member.

Supported request modes:

  • application/json — create a topic without a cover image
  • multipart/form-data — create a topic with an optional cover image. Send a metaPart (JSON topic fields, same shape as the JSON body) and an optional filePart (the cover image). The image is validated first: an invalid or oversized image returns 400 and no topic is created (see requirements below). A valid cover is then applied to the topic (non-square images are center-cropped); if that upload step fails afterwards the topic is still created, just without a cover.

Cover image requirements (when filePart is provided):

  • must be a valid image (JPEG or PNG)
  • non-square images are automatically center-cropped to a square
  • max dimension 4096×4096; larger images return 400
  • max size 8 MB; converted to JPEG automatically

Limits:

  • topic name is limited to 64 characters
  • topic description is limited to 10000 characters
  • maximum 100 members per topic
  • you can only add members that are already in your organization
  • topic externalId is limited to 100 characters
  • externalId must be unique per bot - you cannot create multiple topics with the same externalId
post/v2/topics

Request

Headers

X-Signaturestring
Example:a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6

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:

  1. Get the current Unix timestamp in milliseconds
  2. 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)
  3. Calculate HMAC-SHA256 of the combined payload using your API secret
  4. Hex-encode the output
  5. Include the timestamp in the X-Timestamp header

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.

X-Timestampinteger
Example:1699564800000

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.

Request body

namestring required

The topic name

descriptionstring

Optional topic description

membersstring[] required

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

externalIdstring

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

Example request

{
  "name": "Project Updates",
  "description": "Discussion for project milestones",
  "members": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "externalId": "project-alpha"
}

Response

Topic created successfully

idstring uuid

The created topic ID

namestring

The topic name

membersstring[]

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

externalIdstring

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

createdAtinteger

Unix timestamp in milliseconds

Example response

{
  "members": [
    "550e8400-e29b-41d4-a716-446655440001",
    "b@660e8400-e29b-41d4-a716-446655440003"
  ],
  "externalId": "b@660e8400-e29b-41d4-a716-446655440003:project-alpha"
}

Changes

No recorded changes to this operation across all 1 revision of this API.