> ## Documentation Index > Fetch the complete documentation index at: https://docs.zenzap.co/llms.txt > Use this file to discover all available pages before exploring further. # Get topic messages > Get messages from a topic with cursor-based pagination. Messages are returned in the specified order. **Authorization:** Your API key bot must be a member of the topic to access its messages. **Pagination:** Use the `cursor` parameter with the value from `nextCursor` in the response to get the next page. The `before` and `after` parameters are mutually exclusive - use one or the other, not both. **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. ## OpenAPI ````yaml /openapi.yaml get /v2/topics/{topicId}/messages openapi: 3.0.3 info: title: Zenzap External Integration API description: > API for external applications to integrate with Zenzap. ## Getting Started Welcome to the Zenzap External Integration API documentation. This API is used to integrate with Zenzap. As a context we would like to familiarize you with the Zenzap platform and how it works. Zenzap is a platform for creating and managing topics and messages. Topics (Zenzap term for group chats/channels/conversations) are used to create and manage conversations with your team. Topics are used to group messages and tasks together. Messages are used to send and receive messages with your team. Tasks are used to create and manage tasks with your team. Members are used to manage your team members. API keys are used to authenticate your requests to the Zenzap API. API keys are created and managed by the Zenzap admin user. When you create a new API key, it would create a new bot user in Zenzap, on which behalf you can send messages, create topics, create tasks and manage members. All actions you perform with the API key will be performed on behalf of the bot user. The bot can be used within the scope of your organization. You can create topics, send messages, create tasks and manage members on behalf of the bot. 1. On a Zenzap admin user, go to https://app.zenzap.co/console 2. Create a new API key with the needed permissions 3. Copy the API key and secret from the API key settings 4. For each request: - Add the Authorization header with your API key - Generate a Unix timestamp in milliseconds - Calculate the HMAC-SHA256 signature: - For POST/PUT/PATCH/DELETE: Sign `{timestamp}.{body}` - For GET: Sign `{timestamp}.{uri}` (e.g., `/v2/members?limit=10`) - Add the X-Signature header with the hex-encoded signature - Add the X-Timestamp header with the timestamp used in the payload ## Authentication All API endpoints require two forms of authentication: 1. **Bearer Token**: Include your API key in the Authorization header: ``` Authorization: Bearer YOUR_API_KEY ``` 2. **Request Signing**: Include an HMAC signature and timestamp in headers: ``` X-Signature: X-Timestamp: ``` The signature includes a timestamp for replay protection. Requests older than 5 minutes are rejected. The signature payload differs by HTTP method: - **POST/PUT/PATCH/DELETE requests**: Sign `{timestamp}.{body}` - **GET requests**: Sign `{timestamp}.{uri}` The signature is calculated using HMAC-SHA256 with your API secret. **How to calculate:** 1. Get the current Unix timestamp in milliseconds 2. Determine the payload: - **POST/PUT/PATCH/DELETE**: Use `{timestamp}.{body}` (e.g., `1699564800000.{"topicId":"123"}`) - **GET**: Use `{timestamp}.{uri}` (e.g., `1699564800000./v2/members?limit=10`) 3. Calculate HMAC-SHA256 of the payload using your API secret 4. Hex-encode the result (64 character lowercase string) 5. Include timestamp in X-Timestamp header **Example (Python):** ```python import json import hmac import hashlib import time import requests def create_topic(name: str, members: list[str], description: str = None, external_id: str = None) -> dict: """Create a topic in Zenzap with HMAC signature and replay protection.""" # Build request body body = { "name": name, "members": members, } if description: body["description"] = description if external_id: body["externalId"] = external_id # Serialize body (no spaces for consistent signing) body_json = json.dumps(body, separators=(",", ":")) # Get timestamp for replay protection timestamp = int(time.time() * 1000) # Unix milliseconds # Create HMAC-SHA256 signature with timestamp signature_payload = f"{timestamp}.{body_json}" signature = hmac.new( API_SECRET.encode(), signature_payload.encode(), hashlib.sha256 ).hexdigest() # Make request headers = { "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", "X-Signature": signature, "X-Timestamp": str(timestamp), } response = requests.post(f"{BASE_URL}/v2/topics", headers=headers, data=body_json) response.raise_for_status() return response.json() ``` **Note:** Our API documentation tools cannot automatically generate HMAC signatures. You will need to calculate this manually or use a tool like Postman with pre-request scripts. ## Rate Limits API requests are rate limited per organization. Contact support for specific limits. version: 2.0.0 contact: name: Zenzap Support url: https://zenzap.co/support servers: - url: https://api.zenzap.co description: Production server security: - bearerAuth: [] hmacSignature: [] - oauth2ClientCredentials: [] tags: - name: OAuth description: > OAuth 2.0 `client_credentials` grant. Used by API-key bots that were created with `credentialType: oauth` to mint short-lived bearer access tokens. **In a nutshell:** 1. Get a `clientId` and `clientSecret` from your bot in the Zenzap admin console. The `clientSecret` is shown once at creation; if lost, rotate it from the same screen. 2. `POST /oauth/token` with `grant_type=client_credentials` to receive a JWT access token (1-hour TTL). 3. Call any `/v2/*` endpoint with `Authorization: Bearer `. No `X-Signature` / `X-Timestamp` headers are needed on the OAuth path. 4. Re-mint when the token expires. There is **no refresh token**. Scopes are granular per endpoint — see the [Authentication page](/api-reference/authentication#oauth-scopes) for the full scope catalog and the endpoint → scope mapping. - name: Polls description: > Operations for creating polls, recording votes, and retracting votes. Polls are posted as messages in a topic. When you create a poll, each option is assigned a server-generated 6-character ID — use those IDs as `optionId` when submitting votes. **Voting constraints:** - The bot must be a member of the topic the poll was posted in - Anonymous polls (`anonymous: true`) do not support voting via the API - Votes cannot be cast on closed or expired polls - Each `{pollId, optionId, voter}` combination is idempotent - Votes can be retracted with `DELETE /v2/polls/{pollId}/votes/{voteId}` using the `id` returned when the vote was cast - name: Agentic description: > Endpoints for AI agents to programmatically set up Zenzap organizations. Use `POST /v2/agentic/organization/create` to create an organization, install a bot, and invite a human user in a single request — no authentication required. - name: Messages description: Operations for sending messages - name: Topics (group chats/channels/conversations) description: Operations for managing topics (group chats/channels/conversations) - name: Tasks description: Operations for managing tasks - name: Members description: Operations for retrieving organization members - name: Org units description: >- Operations for listing org units (teams / locations) and managing their members - name: Long Polling description: > Long polling allows your integration to fetch outbound events instead of receiving webhooks. Use `GET /v2/updates` with: - `offset`: value returned as `nextOffset` from the previous response - `limit`: max updates per request (default 50, max 100) - `timeout`: wait time in seconds when no updates are available (default 0, max 30) Event payloads in polling responses match webhook `data` payloads for the same event type. This includes `data.message.attachments[]` with signed URLs for file/image/video/audio messages. - name: Webhooks description: > Webhooks allow your application to receive real-time notifications when events occur in Zenzap. Configure your webhook URL in the Zenzap console for your API key. ## Webhook Headers Each webhook delivery includes the following headers: - `X-Zenzap-Event`: The event type (e.g., `message.created`) - `X-Zenzap-Signature`: HMAC-SHA256 signature for verification - `X-Zenzap-Timestamp`: Unix timestamp (milliseconds) when the webhook was sent - `X-Zenzap-Delivery-Id`: Unique ID for this delivery (for deduplication) ## Signature Verification Webhooks are signed using the same API secret (`BOT_SECRET`) used for request signing. Verify webhooks by calculating: ``` expected = HMAC-SHA256(BOT_SECRET, "{timestamp}.{body}") ``` Where `{timestamp}` is from `X-Zenzap-Timestamp` and `{body}` is the raw request body. If the request includes `Content-Encoding: gzip`, decompress before verifying. ## Webhook Payload Format All webhook events follow the same envelope structure (see `WebhookEvent` schema): ```json { "id": "evt_550e8400-e29b-41d4-a716-446655440099", "type": "message.created", "eventVersion": 1, "timestamp": 1699564800000, "data": { ... } } ``` The `data` field contents vary by event type. See the schemas section for detailed payload structures. ## Event Types ### Message Events | Event | Trigger | Data Schema | |-------|---------|-------------| | `message.created` | New message sent | `WebhookMessageCreatedEvent` | | `message.updated` | Message edited or transcription completed | `WebhookMessageUpdatedEvent` | | `message.deleted` | Message deleted | `WebhookMessageDeletedEvent` | ### Reaction Events | Event | Trigger | Data Schema | |-------|---------|-------------| | `reaction.added` | Emoji reaction added | `WebhookReactionAddedEvent` | | `reaction.removed` | Emoji reaction removed | `WebhookReactionRemovedEvent` | ### Member Events | Event | Trigger | Data Schema | |-------|---------|-------------| | `member.added` | User added to topic | `WebhookMemberAddedEvent` | | `member.removed` | User removed from topic | `WebhookMemberRemovedEvent` | ### Topic Events | Event | Trigger | Data Schema | |-------|---------|-------------| | `topic.updated` | Topic name/description changed | `WebhookTopicUpdatedEvent` | ## Message Types Messages can have different types based on their content: | Type | Description | Additional Fields | |------|-------------|-------------------| | `text` | Regular text message | `text` | | `image`, `file`, `video`, `audio` | Message with attachment | `attachments[]` | | `location` | Shared location | `location` | | `task` | Task snapshot | `task` | | `contact` | Shared contact | `contact` | | `poll` | Poll | `poll` | | `call` | Audio/video call snapshot | `call` | | `admin` | System/administrative message | `text` | ## Attachments & File Access Attachment URLs in webhook payloads are signed and **expire after 60 minutes**. Download files promptly after receiving the webhook. ```json { "id": "550e8400-e29b-41d4-a716-446655440088", "type": "image", "name": "screenshot.png", "mimeType": "image/png", "url": "https://storage.zenzap.co/attachments/...?token=...&expires=..." } ``` Giphy GIFs are looping MP4s: `type` is `video` and `mimeType` is `video/mp4`. When present, `searchQuery` is the Giphy picker search text or GIF title. ## Voice Message Transcription Voice messages (audio attachments) are automatically transcribed: 1. **`message.created`** - Initial message with `transcription.status: "Pending"` 2. **`message.updated`** - Fired when transcription completes with `status: "Done"` ```json { "attachments": [{ "type": "audio", "name": "voice-note.mp3", "url": "https://...", "transcription": { "status": "Done", "text": "Hey team, just a quick update..." } }] } ``` ## Reply Messages Messages that reply to other messages include: - `parentId`: UUID of the message being replied to paths: /v2/topics/{topicId}/messages: get: tags: - Topics (group chats/channels/conversations) summary: Get topic messages description: > Get messages from a topic with cursor-based pagination. Messages are returned in the specified order. **Authorization:** Your API key bot must be a member of the topic to access its messages. **Pagination:** Use the `cursor` parameter with the value from `nextCursor` in the response to get the next page. The `before` and `after` parameters are mutually exclusive - use one or the other, not both. **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. operationId: getTopicMessages parameters: - $ref: '#/components/parameters/XSignature' - $ref: '#/components/parameters/XTimestamp' - name: topicId in: path required: true description: The ID of the topic to get messages from schema: type: string format: uuid example: 550e8400-e29b-41d4-a716-446655440000 - name: limit in: query description: 'Maximum number of messages to return (default: 50, max: 100)' required: false schema: type: integer minimum: 1 maximum: 100 default: 50 - name: cursor in: query description: >- Opaque cursor for pagination. Use the value from `nextCursor` in the response. Cursors are cryptographically signed and validated server-side to prevent tampering. required: false schema: type: string - name: before in: query description: >- Return messages created before this timestamp (Unix milliseconds). Mutually exclusive with `after`. required: false schema: type: integer format: int64 - name: after in: query description: >- Return messages created after this timestamp (Unix milliseconds). Mutually exclusive with `before`. required: false schema: type: integer format: int64 - name: senderId in: query description: Filter messages by sender ID required: false schema: type: string - name: order in: query description: 'Sort order for messages (default: desc - newest first)' required: false schema: type: string enum: - asc - desc default: desc - name: includeSystem in: query description: 'Include system messages (default: true)' required: false schema: type: boolean default: true - name: threadId in: query description: >- Filter to messages within a specific thread (replies to a parent message) required: false schema: type: string format: uuid - name: includeReactionUsers in: query description: 'Include user IDs in reaction data (default: false, heavier payload)' required: false schema: type: boolean default: false responses: '200': description: Messages retrieved successfully content: application/json: schema: $ref: '#/components/schemas/TopicMessagesResponse' example: messages: - id: 660e8400-e29b-41d4-a716-446655440001 topicId: 550e8400-e29b-41d4-a716-446655440000 senderId: 550e8400-e29b-41d4-a716-446655440001 senderName: Alice Johnson senderType: user type: poll text: >- Hello <@550e8400-e29b-41d4-a716-446655440042>, see the poll below createdAt: 1699564800000 updatedAt: 1699564800000 isEdited: false isSystem: false truncated: false attachments: - 770e8400-e29b-41d4-a716-446655440010 mentions: - 550e8400-e29b-41d4-a716-446655440042 mentionDetails: - id: 550e8400-e29b-41d4-a716-446655440042 name: Bob mentionedProfiles: - 550e8400-e29b-41d4-a716-446655440042 poll: id: 770e8400-e29b-41d4-a716-446655440010 title: Lunch spot? selectionType: single status: active options: - id: opt-1 text: Tacos - id: opt-2 text: Sushi reactions: [] - id: 660e8400-e29b-41d4-a716-446655440002 topicId: 550e8400-e29b-41d4-a716-446655440000 senderId: b@660e8400-e29b-41d4-a716-446655440003 senderName: API Bot senderType: bot type: audio text: '' createdAt: 1699564700000 updatedAt: 1699564700000 isEdited: false isSystem: false truncated: false attachments: - 550e8400-e29b-41d4-a716-446655440088 mentions: [] attachmentDetails: - id: 550e8400-e29b-41d4-a716-446655440088 type: audio name: voice-note.mp3 url: https://storage.zenzap.co/attachments/... transcription: status: Done text: Hey team, quick update on the project... reactions: [] - id: 660e8400-e29b-41d4-a716-446655440004 topicId: 550e8400-e29b-41d4-a716-446655440000 senderId: 550e8400-e29b-41d4-a716-446655440001 senderName: Alice Johnson senderType: user type: call text: '' createdAt: 1699564600000 updatedAt: 1699564660000 isEdited: false isSystem: false truncated: false attachments: - 550e8400-e29b-41d4-a716-446655440089 mentions: [] call: id: 880e8400-e29b-41d4-a716-446655440090 initiatorId: 550e8400-e29b-41d4-a716-446655440001 callType: video status: ended startedAt: 1699564600000 endedAt: 1699564660000 endReason: finished duration: 60000 participantCount: 3 reactions: [] nextCursor: >- eyJ0IjoxNjk5NTY0NjAwMDAwLCJpZCI6IjY2MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwNCIsIm8iOiJkZXNjIn0= hasMore: true '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '404': $ref: '#/components/responses/NotFound' '500': $ref: '#/components/responses/InternalServerError' security: - bearerAuth: [] hmacSignature: [] - oauth2ClientCredentials: - message:read components: parameters: XSignature: name: X-Signature in: header required: false description: > 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. schema: type: string pattern: ^[a-f0-9]{64}$ example: a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6 XTimestamp: name: X-Timestamp in: header required: false description: > 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. schema: type: integer format: int64 example: 1699564800000 schemas: TopicMessagesResponse: type: object properties: messages: type: array items: $ref: '#/components/schemas/MessageItem' description: Array of message objects nextCursor: type: string description: >- Cursor for the next page. Pass this value to the `cursor` parameter to get the next page. example: >- eyJ0IjoxNjk5NTY0NzAwMDAwLCJpZCI6IjY2MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMiIsIm8iOiJkZXNjIn0= hasMore: type: boolean description: Whether there are more messages to fetch example: true MessageItem: type: object properties: id: type: string format: uuid description: The message ID example: 660e8400-e29b-41d4-a716-446655440001 topicId: type: string format: uuid description: The topic ID where the message was sent example: 550e8400-e29b-41d4-a716-446655440000 senderId: type: string description: The sender's member ID example: 550e8400-e29b-41d4-a716-446655440001 senderName: type: string description: The sender's display name example: Alice Johnson senderType: type: string enum: - user - bot - system description: The type of sender example: user type: type: string enum: - text - image - file - video - audio - location - task - contact - poll - call - admin description: > The message type. - `text`: Regular text message - `image`, `file`, `video`, `audio`: Message with a file attachment - `location`: Shared location - `task`: Task snapshot - `contact`: Shared contact - `poll`: Poll - `call`: Audio/video call snapshot - `admin`: System/administrative message (also carries `isSystem: true`) example: text text: type: string description: > The raw message text content (may be empty for non-text types). Mention tokens are preserved as `<@profileId>` (including bot profile IDs like `<@b@...>`). example: Hello team! truncated: type: boolean description: Always false; history returns the full stored message text. example: false createdAt: type: integer format: int64 description: Unix timestamp in milliseconds when the message was created example: 1699564800000 updatedAt: type: integer format: int64 description: Unix timestamp in milliseconds when the message was last updated example: 1699564800000 isEdited: type: boolean description: Whether the message has been edited example: false isSystem: type: boolean description: Whether this is a system message example: false replyCount: type: integer description: Number of replies to this message (if it's a thread parent) example: 0 parentId: type: string format: uuid description: ID of the message being replied to (for threaded replies) externalId: type: string description: > Your own correlation ID, echoed back only to the bot that set it (scoped per bot, so one bot never sees another's IDs). attachments: type: array items: type: string description: >- IDs of all attachments associated with the message, including file-backed and structured attachments. attachmentDetails: type: array items: $ref: '#/components/schemas/WebhookAttachment' description: > Details for file-backed attachments (image/file/video/audio). Each `url` is signed and expires after 60 minutes. Structured attachment details are returned in the top-level `poll`, `task`, `contact`, `location`, and `call` fields. mentions: type: array items: type: string description: Mentioned profile IDs. mentionDetails: type: array items: $ref: '#/components/schemas/MessageMention' description: >- Mentioned profiles as `{id, name}` objects, in the same order as `mentions`. reactions: type: array items: $ref: '#/components/schemas/MessageReaction' description: Array of reactions to the message mentionedProfiles: type: array items: type: string description: Mentioned profile IDs. links: type: array description: Links parsed from message text widgets. items: type: object properties: url: type: string format: uri text: type: string poll: description: Poll details when the message contains a poll. allOf: - $ref: '#/components/schemas/WebhookPoll' task: description: Task snapshot when the message contains a task. allOf: - $ref: '#/components/schemas/WebhookTask' contact: description: Contact details when the message contains a shared contact. allOf: - $ref: '#/components/schemas/WebhookContact' location: description: Location details when the message contains a shared location. allOf: - $ref: '#/components/schemas/WebhookLocation' call: description: Audio/video call snapshot when the message contains a call. allOf: - $ref: '#/components/schemas/WebhookCall' WebhookAttachment: type: object description: > File attachment with download URL. URLs are signed and expire after 60 minutes. Download files promptly after receiving the webhook. properties: id: type: string description: The attachment ID type: type: string enum: - image - file - video - audio description: The attachment type name: type: string description: The original file name example: document.pdf mimeType: type: string description: > Stored MIME type when known. Giphy GIFs are looping MP4s and use `video/mp4` with `type: video`. example: video/mp4 searchQuery: type: string description: > Giphy picker search text or GIF title, when the client stored one. Omitted when empty. Present on GIF attachments so consumers can treat it as the sender's intended reaction even if the clip is hard to interpret. example: this is fine maxLength: 100 url: type: string format: uri description: | Signed URL to download the attachment. **Important:** URLs expire after 60 minutes. example: https://storage.zenzap.co/attachments/...?token=...&expires=... transcription: $ref: '#/components/schemas/WebhookTranscription' example: id: 550e8400-e29b-41d4-a716-446655440088 type: audio name: voice-note.mp3 url: https://storage.zenzap.co/attachments/... transcription: status: Done text: Hey team, just a quick update on the project... MessageMention: type: object properties: id: type: string description: The mentioned profile ID example: 550e8400-e29b-41d4-a716-446655440001 name: type: string description: Display name used for the mention text example: Alice Johnson MessageReaction: type: object properties: emoji: type: string description: The emoji used for the reaction example: 👍 count: type: integer description: Number of users who reacted with this emoji example: 3 userIds: type: array items: type: string description: IDs of users who reacted (if includeReactionUsers is true) example: - 550e8400-e29b-41d4-a716-446655440001 WebhookPoll: type: object description: Poll data properties: id: type: string description: The poll (attachment) ID example: 770e8400-e29b-41d4-a716-446655440010 title: type: string description: Poll question example: Lunch spot? subtitle: type: string description: Optional secondary line selectionType: type: string enum: - single - multiple description: Whether voters may pick one option or several anonymous: type: boolean description: Whether votes are anonymous status: type: string enum: - active - closed description: Current poll status expiresAt: type: integer format: int64 description: Expiry as Unix timestamp in milliseconds (optional) options: type: array description: The poll options items: type: object properties: id: type: string description: Option ID (use when casting a vote) example: opt-1 text: type: string description: Option label example: Tacos WebhookTask: type: object description: > Task snapshot sent when a task is created, updated, or its status changes. The `action` field indicates what triggered this snapshot. properties: id: type: string description: The task ID action: type: string enum: - Added - Updated - Deleted - MarkedAsDone - MarkedAsOpened - Replied description: | What triggered this task snapshot: - `Added`: Task was created - `Updated`: Task details were changed - `Deleted`: Task was removed - `MarkedAsDone`: Task was completed - `MarkedAsOpened`: Task was reopened - `Replied`: Comment was added to task title: type: string description: Task title example: Review documentation text: type: string description: Task description example: Please review the API docs by Friday status: type: string enum: - Open - Done description: Current task status assignee: type: string description: User ID of the assignee example: 550e8400-e29b-41d4-a716-446655440001 dueDate: type: integer format: int64 description: Due date as Unix timestamp in milliseconds example: 1699651200000 isDueDateTimeSelected: type: boolean description: Whether a specific time was selected for the due date parentId: type: string description: Parent task ID (for subtasks) subItemsCount: type: integer description: Number of subtasks example: 3 WebhookContact: type: object description: Shared contact information properties: name: type: string description: Contact name example: John Doe phoneNumbers: type: array items: type: string description: Phone numbers example: - '+1234567890' emails: type: array items: type: string description: Email addresses example: - john@example.com role: type: string description: Job title or role example: Engineer location: type: string description: Location or office example: San Francisco linkedIn: type: string description: LinkedIn profile URL example: https://linkedin.com/in/johndoe profileId: type: string description: Zenzap profile ID if the contact is a Zenzap user example: 550e8400-e29b-41d4-a716-446655440001 WebhookLocation: type: object description: Shared location data properties: latitude: type: string description: Latitude coordinate example: '37.7749' longitude: type: string description: Longitude coordinate example: '-122.4194' name: type: string description: Location name (optional) example: San Francisco Office address: type: string description: Street address (optional) example: 123 Market St, San Francisco, CA WebhookCall: type: object description: > Audio/video call snapshot. The inline fields (`id`, `initiatorId`, `callType`) come from the message; live-state fields (`status`, `startedAt`, `endedAt`, `endReason`, `duration`, `participantCount`) are present only when the call record resolves. properties: id: type: string description: The call ID initiatorId: type: string description: Profile ID of whoever started the call example: 550e8400-e29b-41d4-a716-446655440001 callType: type: string enum: - audio - video description: Whether the call is audio- or video-first status: type: string enum: - initiating - calling - active - ended - cancelled description: Current call status startedAt: type: integer format: int64 description: When the call started, as Unix timestamp in milliseconds endedAt: type: integer format: int64 description: When the call ended, as Unix timestamp in milliseconds endReason: type: string enum: - caller_not_joined - caller_cancelled - no_one_answered - finished - max_duration - last_participant description: Why the call ended duration: type: integer format: int64 description: >- Call duration in milliseconds (`endedAt - startedAt`), when both are known participantCount: type: integer format: int64 description: Number of profiles that actually joined the call WebhookTranscription: type: object description: > Transcription data for audio attachments (voice messages). **Transcription flow:** 1. `message.created` arrives with `transcription.status: "Pending"` 2. `message.updated` arrives when transcription completes with `status: "Done"` and `text` populated properties: status: type: string enum: - Pending - Started - Done - Failed description: | Transcription status: - `Pending`: Queued for transcription - `Started`: Transcription in progress - `Done`: Transcription complete, `text` field populated - `Failed`: Transcription failed text: type: string description: The transcribed text (only present when status is "Done") example: Hey team, just a quick update on the project... responses: BadRequest: description: Bad request - invalid input content: text/plain: schema: type: string example: text is required Unauthorized: description: Unauthorized - invalid or missing API token content: text/plain: schema: type: string example: unauthorized NotFound: description: Resource not found content: text/plain: schema: type: string example: Topic not found InternalServerError: description: Internal server error content: text/plain: schema: type: string example: internal server error securitySchemes: bearerAuth: type: http scheme: bearer description: > Bearer token for the request. Two flavors: - **Static API key** — pass your API key (the value returned as `apiKey` when the bot was created). Must be paired with `X-Signature` + `X-Timestamp` (the `hmacSignature` scheme). - **OAuth access token** — pass the JWT returned by `POST /oauth/token`. No signature headers are required. hmacSignature: type: apiKey in: header name: X-Signature description: > HMAC-SHA256 signature for request verification. Required **only** when authenticating with a static API key. Omit when using an OAuth access token. oauth2ClientCredentials: type: oauth2 description: > OAuth 2.0 `client_credentials` grant for API-key bots. Use the `clientId` and `clientSecret` returned when the bot was created (or rotated) to mint short-lived access tokens. See [Authentication](/api-reference/authentication) for details. Access tokens are bearer JWTs and expire after 1 hour. There is no refresh token — re-mint with the client credentials when the token expires. flows: clientCredentials: tokenUrl: https://api.zenzap.co/oauth/token scopes: channel:list: List topics the bot belongs to channel:read: Read topic metadata channel:write: Create/update topics and manage members message:read: Read messages message:send: Send messages message:write: Edit / delete / mark-delivered / mark-read messages reaction:write: Add and remove reactions on messages task:read: Read tasks task:write: Create / update / delete tasks poll:write: Create polls and cast / retract votes member:read: List organization members updates:read: Long-poll for outbound events org_unit:read: List org units and read their members org_unit:write: Add and remove org unit members label:read: List organization labels label:write: Create organization labels ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.