Documentation / v1
Connect your integration.
User authentication and file transfers use HTTP. Messaging commands, queries, and events use WebSocket. The Go and web clients in the repository also implement key unwrapping and content decryption.
1. Set up access
- Open the console with your invitation and create your account. Keep your recovery code safe.
- Link a test number. Grant the history key only to accounts that should be able to read the history.
- For an integration with read access, generate a key pair with
wsctl service-key, register the public key using a service invitation, and grant access to the number. - Create a token with the required scope. Select the integration’s service account and configure its permissions per number.
The token is shown only once. Store it in your system’s secret storage. Do not put tokens in URLs, repositories, or public browser code.
2. Open the WebSocket
wss://api.wappie.thehappie.co/v1/wsThe first frame is hello. Use api_key for integrations or session for a user session. The server responds with welcome before any other commands.
{"t":"hello","r":"connect","p":{"api_key":"SEU_TOKEN"}}
{"t":"devices.list","r":"numbers","p":{}}
{"t":"subscribe","r":"events","p":{"live_only":true}}t identifies the command; r correlates the response; p contains the parameters. Use a different identifier for each request. Unsolicited events do not require r.
To retrieve events, use since_seq with the last processed sequence. Handle the frames replay.begin, replay.end and lag; if there is a delay or disconnection, resume from the last event acknowledged by your application.
| Operation | Commands | Requirement |
|---|---|---|
| Discover numbers | devices.list, device.info | Access to the number |
| Query messages | chats.list, chat.page, message.get, message.history | Read permission and granted key |
| Follow events | subscribe | Read access to subscribed numbers |
| Send | message.send, message.send.media, message.react, message.poll.create, message.send.location, message.event.create, chat.start | Sending |
| Manage device | device.start, device.stop, device.rename, device.mode, history.backfill, group.create, group.participants.update, group.leave | Management |
| Manage tokens | apikeys.list, apikeys.create, apikeys.revoke | Owner or administrator |
Complete reference of types, parameters, and responses (TypeScript) · Go contract
chat.start · group.create · group.participants.update · group.leave · message.poll.create →
message.send.media · forwarded · forwarding_score →
message.react · Unicode emoji →
Errors and reconnection
{"t":"error","r":"request-id","p":{"code":"not_authorized","message":"..."}}Revocation, expiration, or access changes may close the connection with code 1008. Refresh authentication and permissions before reconnecting. Use progressive delays between attempts, and do not automatically repeat sends whose outcome is unknown.
3. Use the HTTP endpoints
Base: https://api.wappie.thehappie.co. Authenticated operations receive Authorization: Bearer TOKEN. Management routes require a user session; an API key cannot manage users.
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/auth/challenge, /v1/auth/login | Get derivation parameters and start a session |
| POST | /v1/auth/signup | Create an account with an invitation and client-generated keys |
| GET | /v1/auth/me | Account and encrypted grants |
| GET | /v1/auth/workspaces | Identity’s workspaces |
| POST | /v1/auth/workspaces/session | New session in the workspace specified by tenant_id |
| POST | /v1/auth/workspaces/accept-invite | Accept an invite with an existing account |
| GET / PUT | /v1/auth/workspaces/members / members/{userID} | List and change role and status |
| POST | /v1/auth/workspaces/invites | Invitation with email and role |
| GET / PUT | /v1/auth/workspaces/devices/{deviceID}/permissions | Read, send, and management permissions |
| GET | /v1/auth/workspaces/capacity | Configured and occupied slots |
| GET | /v1/media/{uid} | Encrypted bytes of an authorized attachment |
| POST | /v1/upload?device=UUID&type=image | Prepare an attachment for sending; see the upload contract |
Management contracts, examples, and HTTP codes · Authentication and encryption client · Upload contract
4. Understand permissions
One identity can join multiple workspaces. Roles, numbers, permissions, and tokens belong to the workspace. Owners and administrators manage devices; this role alone does not grant access to conversations.
Reading requires permission and a granted key. Sending can be allowed without reading. Token scopes read, send and full are cumulative limits; when a token acts as a service account, that account’s independent permissions restrict access to each number.
Legacy tokens without a service account may access encrypted workspace content according to their scope. Prefer service accounts to restrict integrations by number. Removing a grant prevents new access, but does not erase keys or messages someone has already downloaded.
Self-hosting
The repository includes the Go server, CLI, Vue client, and PostgreSQL 18 instructions. Basic administration works without the commercial module. Official hosting uses four addresses; a self-hosted installation can serve the client and API from the same origin.
Open installation guide →API v1 · pilot