### Static API Key GET Request in Python

Source: https://docs.zenzap.co/api-reference/authentication

Example of signing and sending a GET request using the URI path.

```python
import hmac
import hashlib
import time
import requests

def get_topic(topic_id: str) -> dict:
    uri_path = f"/v2/topics/{topic_id}"
    timestamp = int(time.time() * 1000)

    signature_payload = f"{timestamp}.{uri_path}"
    signature = hmac.new(
        API_SECRET.encode(),
        signature_payload.encode(),
        hashlib.sha256,
    ).hexdigest()

    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "X-Signature": signature,
        "X-Timestamp": str(timestamp),
    }

    response = requests.get(f"{BASE_URL}/v2/topics/{topic_id}", headers=headers)
    response.raise_for_status()
    return response.json()
```

--------------------------------

### HMAC Signature Calculation for GET Requests

Source: https://docs.zenzap.co/api-reference/long-polling/get-updates-long-polling

Example demonstrating the payload and header structure for a GET request signature.

```text
timestamp = 1699564800000

payload = "1699564800000./v2/members?limit=10"

signature = HMAC-SHA256(secret, payload)

X-Signature: hex(signature)

X-Timestamp: 1699564800000
```

--------------------------------

### MessageMention Schema Examples

Source: https://docs.zenzap.co/api-reference/long-polling/get-updates-long-polling

Example values for profile ID and display name fields.

```yaml
id: 550e8400-e29b-41d4-a716-446655440001
name: Alice Johnson
```

--------------------------------

### WebhookLocation Schema Examples

Source: https://docs.zenzap.co/api-reference/long-polling/get-updates-long-polling

Example values for location coordinates and address details.

```yaml
latitude: '37.7749'
longitude: '-122.4194'
name: San Francisco Office
address: 123 Market St, San Francisco, CA
```

--------------------------------

### Request Payload Examples

Source: https://docs.zenzap.co/guides/agentic-onboarding

Examples for creating an organization with or without a company logo.

```json
{
  "companyName": "Acme Corp",
  "humanEmail": "founder@acme.com",
  "companySize": 50,
  "industry": "Software",
  "botName": "Acme Assistant"
}
```

```bash
curl -X POST https://api.zenzap.co/v2/agentic/organization/create \
  -F 'filePart=@logo.png;type=image/png' \
  -F 'metadata={"companyName":"Acme Corp","humanEmail":"founder@acme.com","companySize":50,"industry":"Software","botName":"Acme Assistant"};type=application/json'
```

--------------------------------

### HMAC Signature Calculation Examples

Source: https://docs.zenzap.co/api-reference/messages/mark-a-message-as-delivered

Examples showing how to calculate the X-Signature header for different request types.

```text
timestamp = 1699564800000  
payload = "1699564800000./v2/members?limit=10"  
signature = HMAC-SHA256(secret, payload)  
X-Signature: hex(signature)  
X-Timestamp: 1699564800000
```

```text
timestamp = 1699564800000  
payload = '1699564800000.{"topicId":"123","text":"Hello"}'  
signature = HMAC-SHA256(secret, payload)  
X-Signature: hex(signature)  
X-Timestamp: 1699564800000
```

--------------------------------

### Get Current Member Response Example

Source: https://docs.zenzap.co/api-reference/members/get-current-member

Example JSON response returned by the /v2/members/me endpoint.

```json
{
  "id": "b@660e8400-e29b-41d4-a716-446655440003",
  "name": "API Bot",
  "email": "bot@example.com",
  "phone": "",
  "createdAt": 1699564800000,
  "updatedAt": 1699564800000,
  "status": "Active"
}
```

--------------------------------

### Organization Creation Response Example

Source: https://docs.zenzap.co/api-reference/agentic/create-organization

Example response payload returned upon successful organization creation.

```json
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
```

--------------------------------

### List Organization Labels Response Example

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/list-organization-labels

Example response body for the GET /v2/organization/labels endpoint.

```json
{
  "labels": [
    {
      "id": "ef38388f-4cd0-46a7-9935-bac86dbc442b",
      "name": "Priority"
    },
    {
      "id": "28cc608e-50ca-47df-97d6-ed411c6cb84e",
      "name": "Sales"
    }
  ]
}
```

--------------------------------

### X-Timestamp Example

Source: https://docs.zenzap.co/api-reference/messages/mark-a-message-as-delivered

Example of the Unix timestamp in milliseconds.

```text
1699564800000
```

--------------------------------

### Topic Response Example

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/get-topic-by-external-id

Example JSON response body for a successful topic retrieval.

```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Project Updates",
  "description": "Discussion for project milestones",
  "memberIds": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002",
    "b@660e8400-e29b-41d4-a716-446655440003"
  ]
}
```

--------------------------------

### Start the agent bot

Source: https://docs.zenzap.co/guides/build-your-own-agent

Execute the bot script to initiate the connection.

```bash
python bot.py
```

--------------------------------

### Create Topic JSON Request Examples

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/create-a-topic

Examples of JSON request bodies for creating a basic topic and a topic with a description and external ID.

```json
name: Project Updates
members:
  - 550e8400-e29b-41d4-a716-446655440001
  - 550e8400-e29b-41d4-a716-446655440002
```

```json
name: Marketing Campaign
description: Discussion for Q4 marketing campaign
members:
  - 550e8400-e29b-41d4-a716-446655440001
  - 550e8400-e29b-41d4-a716-446655440002
  - 550e8400-e29b-41d4-a716-446655440003
externalId: campaign-q4-2024
```

--------------------------------

### Organization Creation Request Example

Source: https://docs.zenzap.co/api-reference/agentic/create-organization

Example payload for the AgenticOrganizationCreateRequest schema.

```json
example:
  companyName: Acme Corp
  humanEmail: founder@acme.com
  companySize: 50
  industry: Software
  botName: Acme Assistant
```

--------------------------------

### TaskCreateRequest Schema Example

Source: https://docs.zenzap.co/api-reference/tasks/create-a-task

Example structure for the request body when creating a new task.

```json
{
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Review documentation",
  "description": "Review and update all API documentation",
  "assignee": "550e8400-e29b-41d4-a716-446655440001",
  "dueDate": 1699564800000,
  "externalId": "jira-PROJ-123"
}
```

--------------------------------

### Attachment Schema Example

Source: https://docs.zenzap.co/api-reference/long-polling/get-updates-long-polling

Example object representing a file attachment with metadata and a signed download URL.

```yaml
id: att_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...
```

--------------------------------

### Install Zenzap plugin for OpenClaw

Source: https://docs.zenzap.co/integrations/openclaw

Run this command in the terminal on your OpenClaw machine to install the required Zenzap plugin.

```bash
openclaw plugins install @zenzap-co/openclaw-plugin
```

--------------------------------

### File Upload Request Example

Source: https://docs.zenzap.co/api-reference/messages/send-a-message

Example of a multipart/form-data request for uploading files with associated metadata.

```multipart/form-data
metaPart:
  channelID: 550e8400-e29b-41d4-a716-446655440000
  caption: Quarterly report
  externalId: report-2026-q1
  compressImage: false
filePart: (binary)
```

--------------------------------

### Create Message Request Examples

Source: https://docs.zenzap.co/api-reference/messages/send-a-message

Examples of JSON payloads for creating messages, including basic text, external IDs, and mentions.

```json
topicId: 550e8400-e29b-41d4-a716-446655440000
text: Hello from my integration!
```

```json
topicId: 550e8400-e29b-41d4-a716-446655440000
text: 'Status update: Build completed successfully'
externalId: build-12345
```

```json
topicId: 550e8400-e29b-41d4-a716-446655440000
text: >-
  Hi <@550e8400-e29b-41d4-a716-446655440001>, can you review
  this?
```

--------------------------------

### External ID Parameter Example

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/get-topic-by-external-id

Example value for the externalId path parameter.

```json
project-alpha
```

--------------------------------

### Initialize Project Environment

Source: https://docs.zenzap.co/guides/build-your-own-agent

Commands to create a project directory, set up a virtual environment, and install necessary dependencies.

```bash
mkdir zenzap-agent && cd zenzap-agent
python -m venv venv && source venv/bin/activate
pip install requests python-dotenv openai
```

--------------------------------

### Topics List Response Example

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/list-topics

Example JSON response structure returned by the listTopics endpoint.

```json
topics:
  - id: 550e8400-e29b-41d4-a716-446655440000
    name: Project Updates
    description: Discussion for project milestones
    type: topic
    properties: []
    members:
      - 550e8400-e29b-41d4-a716-446655440001
      - 550e8400-e29b-41d4-a716-446655440002
      - b@660e8400-e29b-41d4-a716-446655440003
    createdAt: 1699564800000
    updatedAt: 1699564800000
    externalId: project-alpha
  - id: 550e8400-e29b-41d4-a716-446655440010
    name: Company Announcements
    type: topic
    properties:
      - announcement
    members:
      - 550e8400-e29b-41d4-a716-446655440001
      - b@660e8400-e29b-41d4-a716-446655440003
    createdAt: 1699564900000
    updatedAt: 1699564900000
  - id: 550e8400-e29b-41d4-a716-446655440020
    name: John Doe
    type: dm
    properties: []
    members:
      - 550e8400-e29b-41d4-a716-446655440001
      - b@660e8400-e29b-41d4-a716-446655440003
    createdAt: 1699565000000
    updatedAt: 1699565000000
nextCursor: >-
  eyJ0IjoxNjk5NTY1MDAwMDAwLCJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAyMCJ9.abc123
hasMore: true
```

--------------------------------

### Create Topic Response Example

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/create-a-topic

The structure of a successful 201 response after creating a topic.

```json
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
```

--------------------------------

### X-Signature Pattern Example

Source: https://docs.zenzap.co/api-reference/messages/mark-a-message-as-delivered

Example of a valid hex-encoded HMAC-SHA256 signature.

```text
"a3d5f8e7c2b1d4f6a8e9c7b5d3f1a2e4b6c8d0f2e4a6b8c0d2e4f6a8b0c2d4e6"
```

--------------------------------

### Initialize Main Loop

Source: https://docs.zenzap.co/guides/build-your-own-agent

Configures environment variables, verifies bot identity and channel access, and starts the long-polling loop with signal handling for graceful shutdown.

```python
def main() -> None:
    load_dotenv()

    bot_api_key = os.getenv("BOT_API_KEY")
    bot_secret = os.getenv("BOT_SECRET")
    control_channel_id = os.getenv("CONTROL_CHANNEL_ID")
    openai_api_key = os.getenv("OPENAI_API_KEY")
    api_base_url = os.getenv("API_BASE_URL", "https://api.zenzap.co")
    openai_model = os.getenv("OPENAI_MODEL", "gpt-4o")

    for name, value in [
        ("BOT_API_KEY", bot_api_key),
        ("BOT_SECRET", bot_secret),
        ("CONTROL_CHANNEL_ID", control_channel_id),
        ("OPENAI_API_KEY", openai_api_key),
    ]:
        if not value:
            print(f"Missing required environment variable: {name}")
            sys.exit(1)

    zenzap = ZenzapClient(bot_api_key, bot_secret, api_base_url)
    openai_client = OpenAI(api_key=openai_api_key)

    # Verify the bot identity
    me_resp = zenzap.get_current_member()
    if not me_resp.success:
        print(f"Failed to fetch bot identity: {me_resp.data}")
        sys.exit(1)

    bot_member_id = me_resp.data["id"]
    bot_name = me_resp.data.get("name", "Bot")

    # Verify the control channel is accessible
    control_topic_resp = zenzap.get_topic(control_channel_id)
    if not control_topic_resp.success:
        print(f"Failed to fetch control channel: {control_topic_resp.data}")
        sys.exit(1)

    control_topic_name = control_topic_resp.data.get("name", control_channel_id)

    state = BotState(bot_member_id=bot_member_id)
    state.topic_name_cache[control_channel_id] = control_topic_name

    # Graceful shutdown
    def shutdown(signum, frame) -> None:
        state.running = False
        zenzap.send_message(control_channel_id, "🛑 Bot disconnecting...")
        sys.exit(0)

    signal.signal(signal.SIGINT, shutdown)
    signal.signal(signal.SIGTERM, shutdown)

    zenzap.send_message(
        control_channel_id,
        f"Agent connected successfully, this is the control channel #{control_topic_name}",
    )
    print(f"{bot_name} connected. Listening for messages...")

    # Long-polling loop
    while state.running:
        resp = zenzap.get_updates(offset=state.next_offset, poll_timeout=30)

        if not resp.success:
            if resp.status == 409:
                state.next_offset = None
            else:
                print(f"Poll error ({resp.status}): {resp.data}")
                time.sleep(2)
            continue

        state.next_offset = resp.data.get("nextOffset", state.next_offset)

        for update in resp.data.get("updates", []):
            handle_update(state, zenzap, openai_client, openai_model, DEFAULT_SYSTEM_PROMPT, update)


if __name__ == "__main__":
    main()
```

--------------------------------

### Python HMAC Request Signing Example

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/get-topic-by-external-id

Example implementation of creating a topic with HMAC-SHA256 signature and replay protection using the requests library.

```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()
```

--------------------------------

### Python OAuth End-to-End Implementation

Source: https://docs.zenzap.co/api-reference/authentication

Complete example showing how to exchange credentials for a token and use it to send a message.

```python
import os
import requests

BASE_URL = "https://api.zenzap.co"
CLIENT_ID = os.environ["ZENZAP_CLIENT_ID"]
CLIENT_SECRET = os.environ["ZENZAP_CLIENT_SECRET"]


def get_access_token() -> str:
    """Exchange client credentials for a short-lived bearer token."""
    resp = requests.post(
        f"{BASE_URL}/oauth/token",
        data={
            "grant_type": "client_credentials",
            "client_id": CLIENT_ID,
            "client_secret": CLIENT_SECRET,
            "scope": "channel:list message:send",
        },
    )
    resp.raise_for_status()
    return resp.json()["access_token"]


def send_message(token: str, topic_id: str, text: str) -> dict:
    resp = requests.post(
        f"{BASE_URL}/v2/messages",
        headers={"Authorization": f"Bearer {token}"},
        json={"topicId": topic_id, "text": text},
    )
    resp.raise_for_status()
    return resp.json()


if __name__ == "__main__":
    token = get_access_token()
    send_message(token, "550e8400-e29b-41d4-a716-446655440000", "Hello from OAuth!")
```

--------------------------------

### OAuth Token Request Examples

Source: https://docs.zenzap.co/api-reference/oauth/issue-an-oauth-access-token

Examples of request bodies for obtaining an OAuth token, including standard credentials, down-scoped requests, and HTTP Basic Auth usage.

```json
grant_type: client_credentials
client_id: b@660e8400-e29b-41d4-a716-446655440003
client_secret: very-long-random-secret
```

```json
grant_type: client_credentials
client_id: b@660e8400-e29b-41d4-a716-446655440003
client_secret: very-long-random-secret
scope: channel:list message:send
```

```json
grant_type: client_credentials
```

--------------------------------

### OAuth Error Response Examples

Source: https://docs.zenzap.co/api-reference/oauth/issue-an-oauth-access-token

Examples of error responses for invalid requests or authentication failures.

```json
error: unsupported_grant_type
error_description: unsupported grant_type
```

```json
error: invalid_grant
error_description: invalid client credentials or scopes
```

```json
error: invalid_client
error_description: missing client_secret
```

--------------------------------

### POST /v2/agentic/organization/create

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/set-or-update-a-topic-cover-image

Creates an organization, installs a bot, and invites a human user in a single request.

```APIDOC
## POST /v2/agentic/organization/create

### Description
Programmatically sets up a Zenzap organization. This endpoint does not require authentication.

### Method
POST

### Endpoint
/v2/agentic/organization/create
```

--------------------------------

### Update Topic Request Body Examples

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/update-a-topic

Examples of JSON payloads for updating a topic's name, description, or both.

```json
{
  "name": "New Project Name"
}
```

```json
{
  "description": "Updated description for the project"
}
```

```json
{
  "name": "Renamed Project",
  "description": "New description for the renamed project"
}
```

--------------------------------

### Poll Creation Request Example

Source: https://docs.zenzap.co/api-reference/polls/create-a-poll

Example JSON payload for creating a new poll within a specific topic.

```json
topicId: 550e8400-e29b-41d4-a716-446655440000
question: Which release should we prioritize?
options:
  - Bug fixes
  - New features
  - Performance improvements
selectionType: single
```

--------------------------------

### Poll Vote Success Response Example

Source: https://docs.zenzap.co/api-reference/polls/vote-on-a-poll

Example of the successful response returned after a vote is recorded.

```json
id: >-
  770e8400-e29b-41d4-a716-446655440099_a1b2c3_b@f951b968-bf80-4ee6-bbbe-6ca338f57fc6
attachmentId: 770e8400-e29b-41d4-a716-446655440099
optionId: a1b2c3
createdAt: 1699564800000
```

--------------------------------

### Configure Zenzap authentication

Source: https://docs.zenzap.co/integrations/openclaw

Initiate the setup process to authenticate the OpenClaw machine with your Zenzap account using a token.

```bash
openclaw zenzap setup
```

--------------------------------

### Static API Key POST Request in Python

Source: https://docs.zenzap.co/api-reference/authentication

Example of signing and sending a POST request with a JSON body.

```python
import json
import hmac
import hashlib
import time
import requests

def create_topic(name: str, members: list[str]) -> dict:
    body = {"name": name, "members": members}
    body_json = json.dumps(body, separators=(",", ":"))
    timestamp = int(time.time() * 1000)

    signature_payload = f"{timestamp}.{body_json}"
    signature = hmac.new(
        API_SECRET.encode(),
        signature_payload.encode(),
        hashlib.sha256,
    ).hexdigest()

    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()
```

--------------------------------

### Create Message Response Example

Source: https://docs.zenzap.co/api-reference/messages/send-a-message

Successful response structure for a created text message.

```json
id: 660e8400-e29b-41d4-a716-446655440001
topicId: 550e8400-e29b-41d4-a716-446655440000
createdAt: 1699564800000
```

--------------------------------

### GET /v2/topics

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/list-topics

Get a paginated list of all topics and direct messages where your API key bot is a member. Results are sorted by creation date (newest first).

```APIDOC
## GET /v2/topics

### Description
Get a paginated list of all topics and direct messages where your API key bot is a member. Results are sorted by creation date (newest first).

### Method
GET

### Endpoint
/v2/topics

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of results to return. Default is 50, maximum is 100.
```

--------------------------------

### OpenAPI Event Payload Example

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/get-topic-by-external-id

A generic structure for webhook event payloads.

```json
{
        "id": "evt_550e8400-e29b-41d4-a716-446655440099",
        "type": "message.created",
        "eventVersion": 1,
        "timestamp": 1699564800000,
        "data": { ... }
      }
```

--------------------------------

### HMAC signature calculation in Python

Source: https://docs.zenzap.co/api-reference/oauth/issue-an-oauth-access-token

Example implementation for signing requests to ensure replay protection.

```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."""
```

--------------------------------

### OAuth Token Response Example

Source: https://docs.zenzap.co/api-reference/oauth/issue-an-oauth-access-token

Successful response containing the JWT access token and metadata.

```json
access_token: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
token_type: Bearer
expires_in: 3600
scope: channel:list message:send
```

--------------------------------

### Task Update Request Examples

Source: https://docs.zenzap.co/api-reference/tasks/update-a-task

JSON payloads for common task update operations.

```json
{
  "topicId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "Done"
}
```

```json
{
  "name": "Review webhook integration docs",
  "assignee": "550e8400-e29b-41d4-a716-446655440001",
  "description": "Update docs with long polling + multipart examples"
}
```

```json
{
  "dueDate": 1699564800000
}
```

--------------------------------

### Make an authenticated API request

Source: https://docs.zenzap.co/api-reference/members/list-members

Example of constructing headers with HMAC signatures for a POST request to the Zenzap API.

```python
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()
```

--------------------------------

### POST Topic Request

Source: https://docs.zenzap.co/api-reference/tasks/delete-a-task

Example of sending a POST request to the topics endpoint using the requests library.

```python
response = requests.post(f"{BASE_URL}/v2/topics", headers=headers, data=body_json)
response.raise_for_status()
return response.json()
```

--------------------------------

### Error response examples

Source: https://docs.zenzap.co/api-reference/messages/mark-a-message-as-delivered

Common error messages returned by the API.

```json
"text is required"
```

```json
"unauthorized"
```

```json
"internal server error"
```

--------------------------------

### GET /topics

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/list-topics

Retrieves a list of topics available to the authenticated user or bot.

```APIDOC
## GET /topics

### Description
Returns a list of topics, which can include group chats, channels, or direct messages. The response is paginated.

### Method
GET

### Endpoint
/topics

### Response
#### Success Response (200)
- **topics** (array) - Array of topic objects
- **nextCursor** (string) - Cursor for the next page. Omitted when there are no more results.
- **hasMore** (boolean) - Whether there are more topics available.

#### Response Example
{
  "topics": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Project Updates",
      "description": "Discussion for project milestones",
      "type": "topic",
      "properties": [],
      "members": ["550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002"],
      "labels": ["ef38388f-4cd0-46a7-9935-bac86dbc442b"],
      "createdAt": 1699564800000,
      "updatedAt": 1699564800000,
      "externalId": "project-alpha"
    }
  ],
  "hasMore": false
}
```

--------------------------------

### API Response Examples

Source: https://docs.zenzap.co/api-reference/messages/add-a-reaction-to-a-message

JSON response bodies for successful requests and various error scenarios.

```json
{
  "id": "990e8400-e29b-41d4-a716-446655440005",
  "messageId": "660e8400-e29b-41d4-a716-446655440001",
  "reaction": "👍",
  "createdAt": 1699564800000
}
```

```json
{
  "id": "990e8400-e29b-41d4-a716-446655440005",
  "messageId": "660e8400-e29b-41d4-a716-446655440001",
  "reaction": "👍",
  "createdAt": 1699564800000
}
```

```json
"text is required"
```

```json
"unauthorized"
```

```json
"forbidden"
```

```json
"Topic not found"
```

```json
"internal server error"
```

--------------------------------

### POST /onboarding

Source: https://docs.zenzap.co/guides/agentic-onboarding

Initializes a new organization and agent bot, returning credentials and profile identifiers.

```APIDOC
## POST /onboarding

### Description
Creates a new organization and provisions an agent bot. This process requires company details and an initial human user email.

### Method
POST

### Endpoint
/onboarding

### Parameters
#### Request Body
- **companyName** (string) - Required - Display name of the organization (Max 100 characters).
- **humanEmail** (string) - Required - The human user who will receive an invite and become the org's first member.
- **companySize** (int) - Required - Number of employees (Positive integer > 0).
- **industry** (string) - Required - Free-text industry description.
- **botName** (string) - Required - Display name for the agent bot installed in the organization.

### Response
#### Success Response (201)
- **organizationId** (string) - UUID of the newly created organization.
- **botProfileId** (string) - The bot's identity (format: b@<uuid>).
- **channelId** (string) - The bot's control channel.
- **humanProfileId** (string) - The pending profile ID of the invited human.
- **credentials** (array) - API Key, API Secret, and Control Topic ID.

### Response 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" }
  ]
}
```

--------------------------------

### Authentication Error Response

Source: https://docs.zenzap.co/api-reference/authentication

Example JSON response returned when client credentials or scopes are invalid.

```json
{
  "error": "invalid_grant",
  "error_description": "invalid client credentials or scopes"
}
```

--------------------------------

### Python HMAC Signature Implementation

Source: https://docs.zenzap.co/api-reference/agentic/create-organization

Example implementation for signing requests to the Zenzap API using HMAC-SHA256.

```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=(",", ":"))
```

--------------------------------

### API Credential Data Structure

Source: https://docs.zenzap.co/api-reference/agentic/create-organization

Example structure for bot API credentials including label and value fields.

```yaml
label:
  type: string
  example: API Key
value:
  type: string
  example: utxDAedgfFXglaLX
```

--------------------------------

### POST /v2/agentic/organization/create

Source: https://docs.zenzap.co/guides/agentic-onboarding

Creates a new Zenzap organization, installs a bot, and invites a human user. Supports both standard JSON payloads and multipart requests for including a company logo.

```APIDOC
## POST /v2/agentic/organization/create

### Description
Allows an external AI agent to bootstrap a complete Zenzap workspace in one request, including organization creation, bot installation, and user invitation.

### Method
POST

### Endpoint
https://api.zenzap.co/v2/agentic/organization/create

### Request Body
- **companyName** (string) - Required - The name of the company.
- **humanEmail** (string) - Required - The email address of the human user to invite.
- **companySize** (integer) - Required - The number of employees in the company.
- **industry** (string) - Required - The industry sector of the company.
- **botName** (string) - Required - The name of the bot to be installed.

### Multipart Request
- **filePart** (file) - Optional - Company logo image (Max 5 MB).
- **metadata** (application/json) - Required - JSON object containing the request body fields.

### Request Example
{
  "companyName": "Acme Corp",
  "humanEmail": "founder@acme.com",
  "companySize": 50,
  "industry": "Software",
  "botName": "Acme Assistant"
}
```

--------------------------------

### Error Response Examples

Source: https://docs.zenzap.co/api-reference/messages/edit-a-message

Standard error responses returned when a request fails validation or authentication.

```yaml
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
    Forbidden:
      description: Forbidden - you do not have permission to perform this action
      content:
        text/plain:
          schema:
            type: string
          example: forbidden
    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
```

--------------------------------

### GET /tasks

Source: https://docs.zenzap.co/api-reference/tasks/list-tasks

Retrieves a list of tasks based on optional query parameters for filtering and pagination.

```APIDOC
## GET /tasks

### Description
Retrieves a list of tasks. Supports filtering by topic, status, and assignee, as well as pagination using cursors.

### Method
GET

### Endpoint
/tasks

### Parameters
#### Query Parameters
- **topicId** (string) - Optional - Filter tasks by topic ID
- **status** (string) - Optional - Filter by task status (Open, Done)
- **assignee** (string) - Optional - Filter by assignee profile ID
- **limit** (integer) - Optional - Maximum tasks to return (default 50, max 100)
- **cursor** (string) - Optional - Opaque cursor from a previous nextCursor value.

#### Header Parameters
- **X-Signature** (string) - Optional - HMAC signature for authentication (required for static API keys)
- **X-Timestamp** (string) - Optional - Unix timestamp in milliseconds for replay protection

### Response
#### Success Response (200)
- **TaskListResponse** (object) - The list of tasks retrieved successfully
```

--------------------------------

### Load API Documentation

Source: https://docs.zenzap.co/guides/agentic-onboarding

URL to load the full Zenzap API reference into the agent's context.

```text
https://docs.zenzap.co/llms-full.txt
```

--------------------------------

### HMAC Signature Calculation in Python

Source: https://docs.zenzap.co/api-reference/messages/send-a-message

Example implementation for generating the required HMAC-SHA256 signature for API requests.

```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
```

--------------------------------

### Message event with attachments

Source: https://docs.zenzap.co/api-reference/long-polling

Example of a message event payload including an audio attachment with transcription status.

```json
{
  "eventType": "message.created",
  "data": {
    "message": {
      "type": "audio",
      "attachments": [
        {
          "id": "att_550e8400-e29b-41d4-a716-446655440088",
          "type": "audio",
          "name": "voice-note.mp3",
          "url": "https://storage.zenzap.co/attachments/...?token=...&expires=...",
          "transcription": {
            "status": "Pending"
          }
        }
      ]
    }
  }
}
```

--------------------------------

### GET /v2/topics

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/list-topics

Fetches a paginated list of topics and direct messages where the API key bot is a member.

```APIDOC
## GET /v2/topics

### Description
Get a paginated list of all topics and direct messages where your API key bot is a member. Results are sorted by creation date (newest first).

### Method
GET

### Endpoint
/v2/topics

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The number of results to return. Default is 50, max is 100.
- **cursor** (string) - Optional - Opaque cursor from the previous response (nextCursor) to fetch the next page.
```

--------------------------------

### GET /topics

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/list-topics

Retrieves a list of topics and direct messages. Supports pagination using a cursor and limit parameters.

```APIDOC
## GET /topics

### Description
Retrieves a list of topics and direct messages. Supports pagination using a cursor and limit parameters.

### Method
GET

### Endpoint
/topics

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of topics to return (default: 50, max: 100)
- **cursor** (string) - Optional - Opaque cursor from a previous `nextCursor` value.

### Response
#### Success Response (200)
- **topics** (array) - List of topic objects
- **nextCursor** (string) - Opaque cursor for the next page
- **hasMore** (boolean) - Indicates if more results are available

#### Response Example
{
  "topics": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Project Updates",
      "description": "Discussion for project milestones",
      "type": "topic",
      "properties": [],
      "members": [
        "550e8400-e29b-41d4-a716-446655440001",
        "550e8400-e29b-41d4-a716-446655440002",
        "b@660e8400-e29b-41d4-a716-446655440003"
      ],
      "createdAt": 1699564800000,
      "updatedAt": 1699564800000,
      "externalId": "project-alpha"
    }
  ],
  "nextCursor": "eyJ0IjoxNjk5NTY1MDAwMDAwLCJpZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAyMCJ9.abc123",
  "hasMore": true
}
```

--------------------------------

### Create Organization Endpoint

Source: https://docs.zenzap.co/guides/agentic-onboarding

The base URL for the agentic onboarding process.

```http
POST https://api.zenzap.co/v2/agentic/organization/create
```

--------------------------------

### Response structure for GET /v2/updates

Source: https://docs.zenzap.co/api-reference/long-polling

The response contains a list of updates and a nextOffset cursor for subsequent requests.

```json
{
  "updates": [
    {
      "updateId": "AAAAAAABAAAAAAAAAAABAA==",
      "eventType": "message.created",
      "createdAt": 1699564800000,
      "data": {
        "message": {
          "id": "660e8400-e29b-41d4-a716-446655440001",
          "topicId": "550e8400-e29b-41d4-a716-446655440000",
          "senderId": "550e8400-e29b-41d4-a716-446655440001",
          "senderType": "user",
          "senderName": "Alice Johnson",
          "type": "text",
          "text": "Hello team!",
          "createdAt": 1699564800000
        },
        "truncated": false
      }
    }
  ],
  "nextOffset": "AAAAAAABAAAAAAAAAAABAA=="
}
```

--------------------------------

### Message event with mentions

Source: https://docs.zenzap.co/api-reference/long-polling

Example of a message event payload containing mention tokens and resolved mention objects.

```json
{
  "eventType": "message.created",
  "data": {
    "message": {
      "text": "Hi <@550e8400-e29b-41d4-a716-446655440001>, can you review this?",
      "mentionedProfiles": ["550e8400-e29b-41d4-a716-446655440001"],
      "mentions": [
        {
          "id": "550e8400-e29b-41d4-a716-446655440001",
          "name": "Alice Johnson"
        }
      ]
    }
  }
}
```

--------------------------------

### Implement Zenzap API Request Signing and HTTP Methods

Source: https://docs.zenzap.co/guides/build-your-own-agent

Provides private methods for HMAC-SHA256 request signing and wrappers for GET, POST, PATCH, and DELETE operations.

```python
    def _generate_signature(self, data: str, timestamp: str) -> str:
        return hmac.new(
            self.secret.encode("utf-8"),
            f"{timestamp}.{data}".encode("utf-8"),
            hashlib.sha256
        ).hexdigest()

    def _get_headers(self, signature: str, timestamp: str, include_content_type: bool = False) -> dict:
        headers = {
            "Authorization": f"Bearer {self.api_key}",
            "X-Signature": signature,
            "X-Timestamp": timestamp,
        }
        if include_content_type:
            headers["Content-Type"] = "application/json"
        return headers

    def _get(self, path: str) -> ApiResponse:
        timestamp = str(int(time.time() * 1000))
        signature = self._generate_signature(path, timestamp)
        url = f"{self.base_url}{path}"
        try:
            response = requests.get(
                url,
                headers=self._get_headers(signature, timestamp),
                timeout=self.timeout,
            )
            return ApiResponse.from_response(response)
        except requests.RequestException as exception:
            return ApiResponse.from_exception(exception)

    def _request_with_body(self, method: str, path: str, body: dict) -> ApiResponse:
        body_str = json.dumps(body, separators=(",", ":"))
        timestamp = str(int(time.time() * 1000))
        signature = self._generate_signature(body_str, timestamp)
        url = f"{self.base_url}{path}"
        try:
            response = requests.request(
                method,
                url,
                headers=self._get_headers(signature, timestamp, include_content_type=True),
                data=body_str,
                timeout=self.timeout,
            )
            return ApiResponse.from_response(response)
        except requests.RequestException as exception:
            return ApiResponse.from_exception(exception)

    def _post(self, path: str, body: dict) -> ApiResponse:
        return self._request_with_body("POST", path, body)

    def _patch(self, path: str, body: dict) -> ApiResponse:
        return self._request_with_body("PATCH", path, body)

    def _delete(self, path: str, body: dict) -> ApiResponse:
        return self._request_with_body("DELETE", path, body)
```

--------------------------------

### Voice Message Transcription Payload

Source: https://docs.zenzap.co/api-reference/webhook-events

Example of a message.updated event payload containing a completed audio transcription.

```json
{
  "type": "message.updated",
  "data": {
    "message": {
      "type": "audio",
      "attachments": [
        {
          "id": "att_...",
          "type": "audio",
          "name": "voice-note.mp3",
          "url": "https://storage.zenzap.co/...",
          "transcription": {
            "status": "Done",
            "text": "Hey team, just a quick update on the project..."
          }
        }
      ]
    }
  }
}
```

--------------------------------

### Poll Vote Request Example

Source: https://docs.zenzap.co/api-reference/polls/vote-on-a-poll

Example of the JSON request body required to cast a vote on a poll.

```json
optionId: a1b2c3
```

--------------------------------

### Create Topic with Cover Image Request

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/create-a-topic

Example of a multipart/form-data request including a metaPart JSON object and a binary filePart.

```json
metaPart:
  name: Project Updates
  members:
    - 550e8400-e29b-41d4-a716-446655440001
    - 550e8400-e29b-41d4-a716-446655440002
filePart: (binary image)
```

--------------------------------

### Create Organization Label Request and Response

Source: https://docs.zenzap.co/api-reference/topics-group-chatschannelsconversations/create-organization-label

Example request body and successful response for creating a new organization label.

```json
name: Priority
```

```json
id: ef38388f-4cd0-46a7-9935-bac86dbc442b
name: Priority
```