Teams & Users

Roles and membership

Roles are assigned at the company level (admin/manager/agent) via Spatie permissions in teams mode — one user can belong to multiple companies with different roles in each.

Invitations

The public, unauthenticated invitation-resolution steps (resolve/context/intent) are out of scope for this reference — see the invitations guide.

Current user

The current-user block (GET /me) returns the profile together with the caller's roles and permissions in the active company — the starting point for service-token consumers; companion endpoints update the profile, availability status, and active company (switching company returns the profile with the new company's roles and permissions).

The availability status (PUT /v1/me/availability) accepts exactly three writable values: online, away, offline (busy is a system-derived state and cannot be set through this endpoint).

Active company

The active company is stored in a single server-side field, current_company_id, on your account: it is shared across all of your sessions and API tokens (it is not scoped to an individual token), and company-scoped lists (for example GET /v1/conversations) and realtime channel authorization follow it.

So if the same user switches company in another tab, app, or token, every context follows — an embedded chat may suddenly show another company's conversations, and subscriptions to the previous (no-longer-active) company's channels start returning 403. Keep the company you read from and subscribe to in sync with current_company_id.

Notification preferences

GET /v1/me/notification-preferences returns a snapshot with four blocks: channels — boolean master switches per delivery channel (mail, push, whatsapp; a missing key defaults to true), categories — an object per notification category with enabled/label/controllable fields, plus push_triggers and quiet_hours (see below). The transactional category (verification codes, invitations, password resets) is always controllable: false and enabled: true — it cannot be turned off; the remaining categories (onboarding, trial, billing, win_back, engagement) can each be toggled independently.

PUT /v1/me/notification-preferences — a partial update (merge, not replace): send only the channels.*/categories.*/push_triggers.*/quiet_hours.* keys you are changing — every other key, including the other blocks entirely, keeps its current value. channels.whatsapp = false is the only way for a user to opt out of the WhatsApp channel for billing notifications (payment reminders, suspension notices, etc.) — this opt-out is required by Meta's policy for WhatsApp templates and must be honored by the sender.

Both endpoints also carry push_triggers — a per-push-type object of boolean switches: chat_message_new, conversation_assigned, call_missed, call_incoming, company_unassigned. All default to enabled except company_unassigned (a push about a conversation in the company having no assignee — opt-in so it does not flood every operator at once). call_incoming is effectively always delivered regardless of its stored value — an incoming call is a system notification that cannot be suppressed.

quiet_hours is a do-not-disturb window: { "enabled": bool, "start": "HH:MM"|null, "end": "HH:MM"|null }, defaulting to enabled: false with start/end as null. While the window is active, non-critical push notifications (e.g. conversation_assigned) are suppressed — except call_incoming, which quiet hours never affect. The time is interpreted in the user's timezone (users.timezone); if start is greater than end, the window is treated as overnight (wraps past midnight, e.g. 22:00–08:00).

Phone number verification

The profile phone number (users.phone) can be verified with a code delivered over WhatsApp: POST /v1/me/phone/send-otp sends a 6-digit code and POST /v1/me/phone/verify with a {"code": "123456"} body checks it. A verified number is reflected by the phone_verified field in GET /v1/me and is the address used for WhatsApp copies of billing notifications. Changing the number via POST /v1/me clears the verification.

send-otp does not accept a number in the request body — the code always goes to the saved profile number, so save the number first and request the code afterwards. A 200 response carries the masked phone and expires_in (code lifetime in seconds, currently 600). Possible errors: 422 — no number set, or it fails the E.164 format check; 429 — send/verify rate limits exceeded; 409 (verify only) — the number changed between sending and verifying, request a new code; 502 — the message could not be delivered; 503 — the platform-wide daily code-sending budget is exhausted.

Both endpoints are available to session authentication and mobile tokens only. Service accounts, client API tokens, and embed tokens receive 403 — verifying a number stays an action performed by a real user.

Operator telephony

Provisioning SIP telephony for an operator is the step that follows connecting a SIP channel (see the channel-connection guide, "SIP telephony (BYO trunk)" section). A company admin (the company_telephony.manage permission) enables telephony for a specific member via POST /v1/companies/current/members/{memberId}/telephony/enable, which provisions TWO SIP profiles at once: a browser profile agent-{id}-web (for the built-in WebRTC softphone in the AISAR apps, opaque password) and a native profile agent-{id} (for desk SIP phones and apps like Zoiper/MicroSIP/Linphone, typeable password). There is no separate toggle for the native profile — disable removes both profiles together.

The admin endpoints (companies/current/members/telephony*) are called with the company api_token, same as the rest of this group — a partner service account with the admin role (which unconditionally carries company_telephony.manage, see below) can provision operators programmatically. Self-service (/v1/softphone/*) is the opposite: those endpoints require the caller to BE that operator (session authentication or a mobile token — the same pattern as phone verification above), so a company api_token / service account gets 403 here — a service account never has a SIP profile of its own (member provisioning deliberately filters is_service_account = false). Partners also have a server-to-server way to enable telephony for operators without a user session — it is covered in the partner integration documentation.

company_telephony.manage is not a plan gate: since 2026-08-13, the admin role in ANY company unconditionally carries this permission (a backfill migration closed the gap for companies provisioned before the permission existed). The plan gate lives separately — the plan's telephony feature is required for an operator to actually USE calling (TelephonyAccess::availableTo), but not for an admin to manage operators, schemes and channels.

Both ways of reading the native profile's credentials — the admin's GET .../telephony/credentials and the operator's own GET /v1/softphone/external-credentials — go through the same builder (ExternalSipCredentialPresenter), so the response shape cannot drift apart: sip_username, sip_password, host, tcp_port (5060), tls_port (5061), default_transport: "TCP", codecs: ["opus", "PCMU", "PCMA"], media_encryption, registered (whether the SIP registration is live right now — a best-effort ARA check, treated as false on error) and provisioning_uri — a generic sip: URI (sip:user:pass@host:port;transport=tcp) for QR import into Zoiper / MicroSIP / Linphone / Grandstream Wave. Not usable with 3CX — its app only reads its own provisioning-QR format, so those fields must be entered by hand there. The browser (agent-{id}-web) password is opaque: the admin GET .../telephony/credentials never returns it — that endpoint only touches the native profile; POST .../telephony/reset-password (admin), by contrast, DOES return it — the response carries the freshly rotated browser profile's sip_username/sip_password (the same one-time-reveal principle as creating an API token), and silently rotates the native profile too without returning its new password in the same response — the operator sees their new native password via their own /softphone/external-credentials.

POST .../telephony/extension — the operator's internal extension, 3–4 digits (^\d{3,4}$), unique within the company; a blank value clears it. Requires telephony to already be enabled — otherwise 422.

Operator self-service (session/mobile token only): GET /v1/softphone/credentials — the operator's own browser credentials (consumed directly by the built-in WebRTC softphone, not meant for manual entry); POST /v1/softphone/reset-password — rotates them; GET /v1/softphone/external-credentials / POST /v1/softphone/external/reset-password — the same for the native profile, including the provisioning_uri for QR import; GET /v1/softphone/colleagues — telephony-enabled colleagues in the company (dialer directory) with extension and availability; POST /v1/softphone/internal-call — call a colleague by callee_user_id or internal extension; POST /v1/softphone/external-call — an outbound call over the company's SIP trunk to an external number, with an optional contact_id (resolved strictly within the company — a foreign/unknown id is 422, no silent fallback to number-based resolution). external-call shares the call-originate rate limit with POST /v1/calls/originate — 20 requests per minute per user; the same sip_outbound_gated behavior and IP-mode anti-abuse check as /calls/originate also apply here (see the Calls group).