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

Field	Type	Constraints
companyName	string	Required. Max 100 chars.
humanEmail	string	Required. Valid email.
companySize	int	Required. Positive integer (> 0).
industry	string	Required. Non-empty.
botName	string	Required. Non-empty.

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-..." }
  ]
}

Field	Usage
organizationId	UUID of the new org.
botProfileId	Your bot identity (b@<uuid>). Use as senderId filter when polling.
channelId	Your control channel (same as Control Topic ID credential).
humanProfileId	Invited human's profile ID. Use to identify them once they join.
credentials	API Key for Bearer auth, API Secret for HMAC-SHA256 signing (store securely), Control Topic ID.

Error Codes

Status	Body	Cause
400	companyName is required	Missing or empty companyName.
400	companyName exceeds max length	Over 100 characters.
400	invalid humanEmail	Invalid email address.
400	companySize must be a positive integer	Zero or negative.
400	industry is required	Missing or empty.
400	botName is required	Missing or empty.
400	Unable to create organization	Conflict (e.g. email/domain already in use).
429	(empty)	Rate limit exceeded.

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@.