canonical: https://jentic.com/apis/connectycubecom/connectycube

# Connectycubecom ConnectyCube API

Jentic publishes the only available OpenAPI specification for ConnectyCube API, keeping it validated and agent-ready. ConnectyCube is a backend-as-a-service for chat, voice, and video features in mobile and web apps. The API exposes 39 endpoints covering session creation and destruction, user registration and search, chat dialogs (one-to-one, group, public), messages with reactions and read receipts, file blob storage, and push notifications. Authentication uses a session token in the CB-Token header that is obtained from POST /session and reused for subsequent calls.

## For AI agents

Create chat dialogs, send messages, manage users, and trigger push notifications via ConnectyCube. Useful for agents that automate in-app messaging, moderation, or chat history exports.

## Scope

Does not handle real-time XMPP socket transport, voice/video media servers, or end-user identity providers - use for ConnectyCube REST chat, user, and storage operations only.

## Capabilities

- Open and close ConnectyCube sessions and reuse the CB-Token for subsequent calls
- Register a new app user and update or delete an existing user record
- Create one-to-one, group, or public chat dialogs and add or remove administrators
- Send chat messages, mark them as read or delivered, and add emoji reactions
- Search across dialogs and messages for moderation or compliance review
- Upload file blobs and attach them to messages or user profiles
- Toggle and check push notification preferences per dialog

## Use cases

### In-App Chat Moderation

Run an agent that scans new chat messages for policy violations and acts on them. The agent calls GET `/chat/search` or GET `/chat/Message` on a polling cadence, applies a classifier, and uses DELETE `/chat/Message/{message_id}` to remove violations or PUT `/chat/Dialog/{dialog_id}/admins` to escalate. ConnectyCube's session token model lets the moderation agent run as a privileged service user separate from end-user sessions.

Example prompt: Poll GET `/chat/search` every 60 seconds for new messages matching a deny list, and call DELETE `/chat/Message/{message_id}` for each match.

### Server-Initiated System Notifications

Send system messages from a backend job into a user's existing chat dialog without disrupting their conversation. The agent calls POST `/chat/Message/system` with the dialog ID and the system payload, optionally followed by a push notification trigger. This pattern is useful for order-status updates, trip alerts, or any backend event that should appear in the user's existing chat thread.

Example prompt: Call POST `/chat/Message/system` with dialog_id 5f... and a JSON payload describing an order_shipped event.

### User Lifecycle Sync to ConnectyCube

Keep ConnectyCube users in sync with an external authentication source. On signup, the agent calls POST /users to register the user. On profile changes, it calls PUT `/users/{user_id}.` On account deletion, it calls DELETE `/users/external/{external_id}` so the cleanup is keyed by the external identifier rather than the ConnectyCube ID. This avoids ghost users left in chat after offboarding.

Example prompt: On a deletion event for external_id user_8675, call DELETE `/users/external/user_8675` to remove the corresponding ConnectyCube user.

### AI Agent Chat Operations via Jentic

Wire ConnectyCube management into an AI assistant for support engineers. The agent searches Jentic for send a connectycube chat message, loads the matching operation schema, and executes it with the session token isolated in your Jentic One instance. The same wrapper covers user lookup, dialog management, and message search.

Example prompt: Through Jentic, search send a connectycube chat message, load the POST `/chat/Message` schema, and execute it for dialog 5f... with the message body.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/session` | Create a new session and obtain a CB-Token |
| POST | `/users` | Register a new user |
| POST | `/chat/Dialog` | Create a new chat dialog |
| POST | `/chat/Message` | Send a chat message |
| POST | `/chat/Message/system` | Send a system message into a dialog |
| GET | `/chat/search` | Search messages and dialogs |
| POST | `/blobs` | Create a file blob record |

## Key resources

- **Authentication** — Session creation, retrieval, and destruction via POST/GET/DELETE /session
- **Users** — Register, list, update, and delete users by ConnectyCube ID or external ID
- **Chat** — Create and manage one-to-one, group, and public chat dialogs and their occupants
- **Messages** — Send, update, delete messages; add reactions; track read/delivered state
- **Storage** — Upload and list file blobs that can be attached to messages or profiles
- **Push Notifications** — Toggle and check push notification preferences per dialog

## Why Jentic

- **Setup:** Wiring ConnectyCube by hand means creating a session to obtain a CB-Token, sending it on every request, and handling the chat, user, and blob operations yourself. Through Jentic you install once, import the ConnectyCube API from the API Directory, store the application credentials once, and your agent calls it.
- **Permission scoping:** ConnectyCube identifies its chat dialogs and messages in the request body rather than the URL path, so you limit the agent to the operations it needs, such as creating a dialog or sending a message, and it can call nothing outside that set. Operations you leave out, such as posting system messages or uploading blobs, remain unavailable to the agent.
- **Credential handling:** Your ConnectyCube application credentials and session token are stored once, encrypted, by your own Jentic One instance and injected at execution time. They never enter the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'create a chat dialog' or 'send a chat message', and Jentic returns the matching ConnectyCube operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Sendbird API** — Sendbird is a chat and messaging platform with mature SDKs and moderation features
- **PubNub API** — PubNub is a real-time messaging and presence platform
- **Stream Chat API** — Stream Chat offers chat, activity feeds, and moderation as a service

## FAQ

### Why is there no official OpenAPI spec for ConnectyCube API?

ConnectyCube documents its REST API as Markdown reference pages but does not publish an OpenAPI 3 specification. Jentic generates and maintains this spec so that AI agents and developers can call ConnectyCube API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### What authentication does the ConnectyCube API use?

It uses a session token returned from POST /session, which must be passed in the CB-Token header on subsequent requests. The session call accepts an application_id and authentication_key/secret pair (or user credentials for user sessions). Through Jentic the secrets and resulting token are kept in the vault and never enter the agent's prompt.

### Can I send chat messages directly via the REST API?

Yes. POST `/chat/Message` sends a message into a dialog. Real-time delivery to connected clients still happens over the ConnectyCube XMPP-style socket, but REST is appropriate for server-initiated messages and offline scenarios.

### How do I send a system message into an existing dialog?

Call POST `/chat/Message/system` with the dialog_id and your custom payload. System messages are delivered with a special class so client SDKs can render them as system events rather than user messages.

### Can I delete a user across all integrations using their external ID?

Yes. DELETE `/users/external/{external_id}` removes the user using the external identifier you originally registered them under. This is the right path when your source of truth is your own auth system rather than the ConnectyCube user ID.

### How do I send a chat message through Jentic?

Run pip install jentic, then await client.search('send a connectycube chat message'), load the matching operation schema, and execute it. The underlying call is POST `/chat/Message` with the dialog_id and message body you supply at runtime.

### Can I limit what my agent is allowed to do with the ConnectyCube API?

Yes. Because you run Jentic One yourself, your own rules decide which ConnectyCube operations and credentials the agent may use, so you can allow just the calls it needs, such as creating a dialog with POST `/chat/Dialog` or sending a message with POST `/chat/Message.` Since ConnectyCube identifies dialogs and messages in the request body rather than the URL path, the agent can act only within the operations you enable and nothing beyond that set. Operations you leave out, such as posting system messages with POST `/chat/Message/system` or uploading file blobs with POST /blobs, stay unavailable to the agent.