> ## 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. # Create organization > Allows an external AI agent to programmatically create a Zenzap organization, install a bot (the agent itself), and invite a human user — all in a single request. **Authentication:** None required. This endpoint is publicly accessible. **Rate limit:** 1 request per minute per IP. Supports two content types: - `application/json` — for requests without a logo - `multipart/form-data` — for requests that include a company logo (`filePart`) Once you receive the `201` response, use the returned `credentials` to authenticate all subsequent API calls. See [Authentication](/api-reference/authentication) for details. ## OpenAPI ````yaml /openapi.yaml post /v2/agentic/organization/create 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: 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` | ## Attachments & File Access Attachment URLs in webhook payloads are signed and **expire after 60 minutes**. Download files promptly after receiving the webhook. ```json { "id": "att_...", "type": "image", "name": "screenshot.png", "url": "https://storage.zenzap.co/attachments/...?token=...&expires=..." } ``` ## 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/agentic/organization/create: post: tags: - Agentic summary: Create organization description: > Allows an external AI agent to programmatically create a Zenzap organization, install a bot (the agent itself), and invite a human user — all in a single request. **Authentication:** None required. This endpoint is publicly accessible. **Rate limit:** 1 request per minute per IP. Supports two content types: - `application/json` — for requests without a logo - `multipart/form-data` — for requests that include a company logo (`filePart`) Once you receive the `201` response, use the returned `credentials` to authenticate all subsequent API calls. See [Authentication](/api-reference/authentication) for details. operationId: createAgenticOrganization requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgenticOrganizationCreateRequest' example: companyName: Acme Corp humanEmail: founder@acme.com companySize: 50 industry: Software botName: Acme Assistant multipart/form-data: schema: type: object properties: filePart: type: string format: binary description: Company logo image. Max 5 MB. Optional. metadata: $ref: '#/components/schemas/AgenticOrganizationCreateRequest' encoding: metadata: contentType: application/json responses: '201': description: Organization created successfully content: application/json: schema: $ref: '#/components/schemas/AgenticOrganizationCreateResponse' example: organizationId: 067d0b2f-1ee8-49f2-bb09-e2d964c8cf6b botProfileId: b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6 channelId: 1b383aef-15c2-44e2-b599-d1d40a8b286c humanProfileId: a3c2e1d0-9f8b-4e7a-b6c5-d4e3f2a1b0c9 credentials: - label: API Key value: utxDAedgfFXglaLX - label: API Secret value: 66AybzV7s0afLeKKqpxC7wLKCTk5d7bT - label: Control Topic ID value: 1b383aef-15c2-44e2-b599-d1d40a8b286c '400': description: Validation error content: application/json: schema: type: object properties: message: type: string examples: companyNameRequired: summary: Missing company name value: message: companyName is required companyNameTooLong: summary: Company name too long value: message: companyName exceeds max length invalidEmail: summary: Invalid email value: message: invalid humanEmail invalidCompanySize: summary: Invalid company size value: message: companySize must be a positive integer industryRequired: summary: Missing industry value: message: industry is required botNameRequired: summary: Missing bot name value: message: botName is required unableToCreate: summary: Conflict (email or domain already in use) value: message: Unable to create organization '429': description: Rate limit exceeded (1 request per minute per IP) security: [] components: schemas: AgenticOrganizationCreateRequest: type: object required: - companyName - humanEmail - companySize - industry - botName properties: companyName: type: string maxLength: 100 description: Display name of the organization. example: Acme Corp humanEmail: type: string format: email description: >- The human user who will receive an invite and become the org's first member. example: founder@acme.com companySize: type: integer minimum: 1 description: Number of employees. Mapped to a size range. example: 50 industry: type: string description: Free-text industry description (e.g. "Software", "Healthcare"). example: Software botName: type: string description: Display name for the agent bot installed in the organization. example: Acme Assistant AgenticOrganizationCreateResponse: type: object properties: organizationId: type: string format: uuid description: UUID of the newly created organization. example: 067d0b2f-1ee8-49f2-bb09-e2d964c8cf6b botProfileId: type: string description: >- The bot's identity (format `b@`). Use as `senderId` filter when polling. example: b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6 channelId: type: string format: uuid description: >- The bot's control channel ID (same as the `Control Topic ID` credential). example: 1b383aef-15c2-44e2-b599-d1d40a8b286c humanProfileId: type: string format: uuid description: >- The pending profile ID of the invited human. Use this to identify the human once they join. example: a3c2e1d0-9f8b-4e7a-b6c5-d4e3f2a1b0c9 credentials: type: array description: API credentials for the bot. Store the API Secret securely. items: type: object properties: label: type: string example: API Key value: type: string example: utxDAedgfFXglaLX 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 ````