Get topic by external ID
Get details of a specific topic by its external ID (set when creating the topic).
Authorization: Your API key bot must be a member of the topic to access its details.
Note: For security reasons, a 404 response is returned both when the topic does not exist and when your bot is not a member of the topic.
Deep linking to topics
You can open Zenzap directly to a topic using its external ID by adding a query parameter to the Zenzap app URL.
| Component | Value |
|---|---|
| Base URL | https://app.zenzap.co |
| Query parameter | external_topic |
| Parameter value | Your external ID |
For example, use https://app.zenzap.co?external_topic=project-123 to link directly to a topic with external ID “project-123”.
This is useful for creating links from your application that navigate users directly to the relevant conversation in Zenzap.
Short vs fully qualified external ID
You can use either the short external ID (the value you passed when creating the topic) or the fully qualified external ID.
For security purposes, if multiple bots create topics with the same external ID, each topic is internally prefixed with the bot ID in the format bot_id:external_id. The bot ID follows the format b@<uuid> (e.g., b@660e8400-e29b-41d4-a716-446655440003). To avoid ambiguity, use the fully qualified format like https://app.zenzap.co?external_topic=b@660e8400-e29b-41d4-a716-446655440003:project-123.
| Format | Example URL |
|---|---|
| Short | https://app.zenzap.co?external_topic=project-123 |
| Fully qualified | https://app.zenzap.co?external_topic=b@660e8400-e29b-41d4-a716-446655440003:project-123 |
Multiple matches
If you use the short external ID and multiple bots have created topics with the same external ID, the user will see a selection screen to choose the correct topic:
Platform availability
Deep linking is currently supported on Web and Windows versions of Zenzap.
Authorizations
Use your API key as the Bearer token. You can view your API key and secret in your Zenzap organization API key settings.
HMAC-SHA256 signature for request verification.
Headers
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:
- 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)
- Calculate HMAC-SHA256 of the payload using your API secret
- 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)
"a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6"
Path Parameters
The external ID of the topic to retrieve
100Response
Topic details retrieved successfully
The topic ID
"550e8400-e29b-41d4-a716-446655440000"
The topic name
"Project Updates"
The topic description
"Discussion for project milestones"
Array of member IDs in the topic
[
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002"
]