Create a session
Create a new session record for the caller's organization.
Behavior: session starts unpaired. Set start to true to begin pairing immediately; pairing then proceeds asynchronously.
Requires manage capability. Unknown or invalid request data returns validation_error (400). Auth errors are unauthorized (401) and forbidden (403).
Returns 201 Created with the new session. This endpoint is not idempotent.
Send Authorization: Bearer <token>. The token can be a login JWT from the frontend or an api-key for a script. JWT access comes from the person's organization role. Api-key access comes from the permissions saved on the key.
In: header
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
If true, mark incoming messages as read automatically.
falseHow many days of chat history to import when the phone is linked. The phone sends the history it still has; older messages are skipped. 0 turns the import off. Omit to use the deployment default (30 days unless the operator changed it). Values above the deployment maximum are rejected.
int640 <= value30Optional human-friendly session label.
"Sales line"If true, send typing indicator while a message is sent from this session.
trueIf true, begin QR pairing immediately. If false, create the session in stopped/unpaired state and pair later.
trueResponse Body
application/json
application/json
curl -X POST "https://example.com/api/v1/sessions" \ -H "Content-Type: application/json" \ -d '{}'{ "autoRead": false, "createdAt": 1719662400000, "createdByUserId": "user_01J9DEF...", "gatewayId": "gw-sg-1", "historySyncDays": 30, "id": "01J9ZX8K2QHV0M3T6R7P4N5W8C", "isAdminSession": false, "label": "Support line", "lastConnectedAt": 1719662400000, "organizationId": "org_01J9ABC...", "phoneNumber": "6281234567890", "presenceTyping": true, "ratePerHour": 600, "ratePerMin": 20, "status": "working", "updatedAt": 1719662400000, "waJid": "6281234567890@s.whatsapp.net", "waLid": "205227043110953@lid"}{ "error": { "code": "not_found", "details": { "property1": null, "property2": null }, "message": "session not found" }}