ADVISOR mode, or both. Manage these numbers for each client account in Calling setup → Developer setup → Call listeners. Your dialer still decides which signed-in users may request monitoring; an approved destination does not grant a Salesforce user access to a call.
This setup uses the signed-in owner’s Trackly session and the session’s active account. It does not accept a Voice Calls API key. Select the client account before viewing or changing its supervisors. Trackly does not approve the people your account owner chooses. The account must have Voice Calls access.
Grant enforcement is enabled by account. When enabled, Monitor a Call requires a current grant for the resolved phone number and requested MONITOR or ADVISOR role. Creating a phone agent or giving someone a voice_calls.write key does not grant monitoring authority. A grant does not start or answer a call.
MONITOR is listen-only. On Trackly-managed calls, ADVISOR coaches the retained agent leg. Hosted calls accept ADVISOR but do not guarantee directed coaching of that agent. Neither mode offers barge or an in-call role change.
List saved numbers
GET /api/voice-calls/setup/monitor-grants returns {items, nextCursor, enforced} for the active account. enforced: true means new listener calls require the saved destination and role; false means the list is saved but does not yet restrict calls for this account. Your dialer must still decide who may request monitoring. Each item has id, number, roles, revision, and updatedAt. A revoked entry remains visible with roles: []. Results are sorted by phone number.
The optional limit query parameter defaults to 20 and accepts 1–100. Pass a returned nextCursor as cursor to read the next page. To read the current state of one number, use number with its exact E.164 value instead of cursor. Do not reuse a cursor after switching accounts.
Approve or revoke a number
PUT /api/voice-calls/setup/monitor-grants replaces one number’s roles and returns its id, number, roles, revision, updatedAt, and eventId. Send JSON with these fields:
For example, an owner can approve a number for listening:
PUT for the same number with a new requestId, that revision, and "roles": []. When enforcement is active, Trackly checks again before an unsubmitted attempt; a revocation observed then blocks it. A saved pending monitor leg can be returned on replay before its control checks the new grant state and cancels. A change after the final check can race with submission. Revocation does not end a supervisor already connected to a call or authorize a second attempt after an uncertain outcome. It retains the earlier change records.
A successful change returns 200 with the saved number and revision:
requestId returns the original change result, even if another owner has since changed that number. After an uncertain retry, read the number with GET before treating its roles or revision as current.