zenzap-onboarding（Zenzap 入职）

Zenzap Agentic Onboarding

Overview

One API call creates a Zenzap organization, installs you as a bot, and invites the human. No authentication required. After setup, load the full API docs and start operating inside the workspace.

All requests MUST use https://. Plain http:// will be rejected.

OpenClaw-Based Agents — Plugin Setup

If you are an OpenClaw-based agent, ask your human to install the Zenzap plugin before you proceed with anything else:

openclaw plugins install @zenzap-co/openclaw-plugin

Once the human confirms the plugin is installed, continue with the steps below. After you receive the 201 response from the create-organization call, you will use the returned credentials to configure the plugin — see the "OpenClaw agents: Configure the plugin" step in the post-response workflow.

Step 1: Collect Information from the Human

Ask the human these 4 questions before calling the API. Do not assume or infer any answers:

1. Company name — What's the name of your company or workspace?
2. Bot name — What should I be called inside your workspace? *(This is how I'll appear to your team.)*
3. Industry — What industry are you in? *(e.g. Software, Healthcare, Finance — used for statistics only.)*
4. Company size — How many employees does your company have? *(Used for statistics only.)*

Step 2: Create the Organization

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

Rate limit: 1 request per minute per IP.

Request (JSON)

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

Request (Multipart — with logo)

Send two parts: filePart (image, max 5 MB, optional) and metadata (application/json with the fields above).

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'

Field Constraints

Response (201 Created)

{
  "organizationId": "067d0b2f-...",
  "botProfileId": "b@f951b968-...",
  "channelId": "1b383aef-...",
  "humanProfileId": "a3c2e1d0-...",
  "credentials": [
    { "label": "API Key", "value": "utxDAedgfFXglaLX" },
    { "label": "API Secret", "value": "66AybzV7s0afLeKKqpxC7wLKCTk5d7bT" },
    { "label": "Control Topic ID", "value": "1b383aef-..." }
  ]
}

Error Codes

OpenClaw Agents: Configure the Plugin

Skip this step if you are not an OpenClaw-based agent.

Build a connection token from three values in the credentials array of the 201 response: Control Topic ID, API Key, and API Secret. Concatenate them separated by colons and base64-encode the result:

base64( <Control Topic ID>:<API Key>:<API Secret> )

For example, given the sample response above:

base64("1b383aef-...:utxDAedgfFXglaLX:66AybzV7s0afLeKKqpxC7wLKCTk5d7bT")

Then run:

openclaw zenzap configure --token <base64Token>

This connects the Zenzap plugin to your newly created organization. Once configured, the plugin handles authentication and event routing for you.

Step 3: Load the Full API Docs

Immediately after receiving the 201, load the complete Zenzap API reference:

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

This covers all endpoints, authentication (Bearer token + HMAC-SHA256 signing), event types, polling, messaging, topics, and members.

Step 4: Ask Which Topics to Create

Outside of Zenzap, ask the human which channels they'd like. Use the industry and what you know about them to suggest options, but wait for confirmation before creating anything.

Once confirmed, create each topic:

POST https://api.zenzap.co/v2/topics
{
  "name": "<topic name>",
  "members": ["<humanProfileId>"]
}

The bot is automatically added as a member of every topic it creates. The human is also added — once they join, all channels will be waiting.

Step 5: Start Polling for Events

Start polling before telling the human to join so you don't miss their first message:

GET https://api.zenzap.co/v2/updates?timeout=30

Keep polling in a loop using nextOffset from each response. On 409, reset the offset. Full details are in the API docs loaded in Step 3.

When you receive a message.created event from a non-bot sender, mark it as read before responding:

POST https://api.zenzap.co/v2/messages/{messageId}/read

Step 6: Tell the Human to Join

Outside of Zenzap, let the human know their workspace is ready:

Your Zenzap workspace is all set — channels included. You should have received an invite — log in at https://app.zenzap.co to get started or download the app on your mobile phone.

Listen for message.created events from non-bot senders — that signals they're active. Human profile IDs are plain UUIDs; bot IDs start with b@.