o2g-node-sdk 2.5.5 → 2.5.6

package/dist/types/services/o2g-telephony.d.ts

@@ -14,13 +14,12 @@ import { DeviceState } from '../types/telephony/device/device-state';
 import { PilotTransferQueryParameters } from '../types/telephony/call/ccd/pilot-transfer-query-param';
 import { CallProfile } from '../types/telephony/call/ccd/call-profile';
 /**
- * The TelephonyService allows a user to initiate a call and to activate
+ * The TelephonyService allows a user to initiate calls and activate
  * any kind of OmniPCX Enterprise telephony services.
  * <p>
- * Using this service requires having a <b>TELEPHONY_ADVANCED</b> license,
- * except for the 3 basic services
- * {@link basicMakeCall}, {@link basicAnswerCall} and {@link basicDropMe} that are available without any
- * license.
+ * Using this service requires a <b>TELEPHONY_ADVANCED</b> license, except for
+ * the three basic services {@link basicMakeCall}, {@link basicAnswerCall} and
+ * {@link basicDropMe}, which are available without any license.
  */
 export declare class Telephony extends EventEmitter {
     #private;
@@ -60,46 +59,53 @@ export declare class Telephony extends EventEmitter {
      */
     static readonly ON_DYNAMIC_STATE_CHANGED = "OnDynamicStateChanged";
     /**
-     * Initiates a call from the specified device to the specified called number.
+     * Initiates a basic call from the specified device to the specified called number.
+     * <p>
+     * This method does not require a license.
      * <p>
      * If the session is opened by a user, the device phone number must be one of
      * the user's devices.
      * <p>
-     * If `autoAnswer` is set to `false`, the `deviceId` is called before launching
-     * the call to the callee; otherwise the callee is called immediately.
+     * If `autoAnswer` is set to `false`, the user's device is called first before
+     * placing the call to the callee; otherwise the callee is called immediately.
      *
-     * @param deviceId   the device phone number for which the call is made
-     * @param callee     the called number
-     * @param autoAnswer automatic answer on make call
+     * @param deviceId   the device phone number used to place the call
+     * @param callee     the called phone number
+     * @param autoAnswer if `true`, the callee is called immediately; if `false`,
+     *                   the user's device is called first before placing the call to the callee
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     basicMakeCall(deviceId: string, callee: string, autoAnswer?: boolean): Promise<boolean>;
     /**
      * Answers an incoming ringing call on the specified device.
      * <p>
+     * This method does not require a license.
+     * <p>
      * If the session is opened by a user, the device phone number must be one of
      * the user's devices.
      *
-     * @param deviceId the device phone number
+     * @param deviceId the device phone number on which to answer
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     basicAnswerCall(deviceId: string): Promise<boolean>;
     /**
-     * Exits from the call for the specified user.
+     * Exits from the current call for the specified user.
      * <p>
-     * If the session has been opened for a user, the `loginName` parameter is
-     * ignored, but it is mandatory if the session has been opened by an
-     * administrator.
+     * This method does not require a license.
      * <p>
      * If the call is a single call, it is released; if it is a conference, the call
      * carries on without the user.
+     * <p>
+     * If the session has been opened for a user, the `loginName` parameter is
+     * ignored, but it is mandatory if the session has been opened by an
+     * administrator.
      *
      * @param loginName the login name for whom the drop is done
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     basicDropMe(loginName?: string | null): Promise<boolean>;
     /**
-     * Retrieves the calls in progress for the specified user.
+     * Retrieves the calls currently in progress for the specified user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -107,18 +113,19 @@ export declare class Telephony extends EventEmitter {
      *
      * @param loginName the login name
      * @returns the list of active {@link Call} objects on success; `null` otherwise.
+     * @see getCall
      */
     getCalls(loginName?: string | null): Promise<Call[] | null>;
     /**
-     * Returns the call specified by the call reference for the specified user.
+     * Returns the call identified by the specified reference for the specified user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
-     * @param callRef   the call reference
+     * @param callRef   the unique call reference
      * @param loginName the login name
-     * @returns the {@link Call} on success; `null` otherwise.
+     * @returns the {@link Call} on success; `null` if not found.
      */
     getCall(callRef: string, loginName?: string | null): Promise<Call | null>;
     /**
@@ -129,131 +136,113 @@ export declare class Telephony extends EventEmitter {
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      * <p>
-     * If `autoAnswer` is set to `false`, the `deviceId` is called before launching
-     * the call to the callee; otherwise the callee is called immediately.
+     * If `autoAnswer` is set to `false`, the user's device is called first before
+     * placing the call to the callee; otherwise the callee is called immediately.
      *
-     * @param deviceId   the device phone number for which the call is made
-     * @param callee     the called number
-     * @param autoAnswer automatic answer on make call
+     * @param deviceId   the device phone number from which the call is placed; if the
+     *                   session is opened by a user, this must be one of the user's devices
+     * @param callee     the called phone number
+     * @param autoAnswer if `true`, the callee is called immediately; if `false`,
+     *                   the user's device is called first before placing the call to the callee
      * @param loginName  the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     makeCall(deviceId: string, callee: string, autoAnswer?: boolean, loginName?: string | null): Promise<boolean>;
     /**
-     * Initiates a new call to another user (the callee), using the specified device and options.
+     * Initiates a call from the specified device to the specified called number,
+     * with extended options.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      * <p>
-     * First, the call server initiates a call on the user's `deviceId`. Then when the
-     * call is answered the call server starts the call to the `callee`, and an
-     * {@link ON_CALL_CREATED} event is raised.
+     * If `autoAnswer` is set to `false`, the user's device is called first before
+     * placing the call to the callee; otherwise the callee is called immediately.
      * <p>
-     * If `inhibitProgressTone` is `true`, the progress tone is inhibited on the outbound call.
-     * <p>
-     * The `callingNumber` can be used to present a different calling number on the public
-     * network in order to hide the real calling extension number.
-     *
-     *  * @example
-     * ```typescript
-     * // Simple call with auto-answer
-     * await O2G.telephony.makeCallEx("1234", "5678");
-     *
-     * // Call with progress tone inhibited and a different calling number
-     * await O2G.telephony.makeCallEx("1234", "5678", true, true, null, "9000");
+     * The `callingNumber` can be used to present a different calling number on the
+     * public network in order to mask the real calling extension number.
      *
-     * // Call with correlator data to carry application context
-     * const correlatorData = new CorrelatorData("transactionId=abc123");
-     * await O2G.telephony.makeCallEx("1234", "5678", true, false, correlatorData);
-     *
-     * // Administrator making a call on behalf of a user
-     * await O2G.telephony.makeCallEx("1234", "5678", true, false, null, null, "jdoe");
-     * ```
-     *
-     * @param deviceId            the device phone number for which the call is made
-     * @param callee              the called number
-     * @param autoAnswer          automatic answer on make call
-     * @param inhibitProgressTone allows to inhibit the progress tone on the current external call
-     * @param correlatorData      correlator data to add to the call
-     * @param callingNumber       calling number to present to the public network
+     * @param deviceId            the device phone number from which the call is placed; if the
+     *                            session is opened by a user, this must be one of the user's devices
+     * @param callee              the called phone number
+     * @param autoAnswer          if `true`, the callee is called immediately; if `false`,
+     *                            the user's device is called first before placing the call to the callee
+     * @param inhibitProgressTone `true` to inhibit the progress tone on the outbound call
+     * @param correlatorData      correlator data to attach to the call
+     * @param callingNumber       optional calling number to present to the public network, used to mask
+     *                            the real calling extension number
      * @param loginName           the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     makeCallEx(deviceId: string, callee: string, autoAnswer?: boolean, inhibitProgressTone?: boolean, correlatorData?: CorrelatorData | null, callingNumber?: string | null, loginName?: string | null): Promise<boolean>;
     /**
-     * Initiates a new private call to another user (the callee), using a PIN code and an optional secret code.
+     * Initiates a private call to the specified callee, identified by a PIN code.
+     * <p>
+     * A private call allows the user to flag a call as personal rather than
+     * professional, enabling specific charging processing.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
-     * <p>
-     * The private call service allows a user to specify that an external call is personal
-     * rather than professional. The charging for this type of call can then be given
-     * specific processing.
-     * <p>
-     * First, the call server initiates a call on the user's `deviceId`. Then when the
-     * call is answered the call server starts the call to the `callee`, and an
-     * {@link ON_CALL_CREATED} event is raised.
      *
-     * @param deviceId   the device phone number for which the call is made
-     * @param callee     the called number
-     * @param pin        the PIN code to identify the caller
+     * @param deviceId   the device phone number from which the call is placed; if the
+     *                   session is opened by a user, this must be one of the user's devices
+     * @param callee     the called phone number
+     * @param pin        the PIN code identifying the caller
      * @param secretCode the optional secret code used to confirm the PIN code
      * @param loginName  the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     makePrivateCall(deviceId: string, callee: string, pin: string, secretCode?: string | null, loginName?: string | null): Promise<boolean>;
     /**
-     * Initiates a new business call to another user (the callee), using the specified business code.
+     * Initiates a business call to the specified callee, charged to the specified
+     * cost center.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
-     * <p>
-     * First, the call server initiates a call on the user's `deviceId`. Then when the
-     * call is answered the call server starts the call to the `callee`, and an
-     * {@link ON_CALL_CREATED} event is raised.
      *
-     * @param deviceId     the device phone number for which the call is made
-     * @param callee       the called number
-     * @param businessCode the cost center on which the call will be charged
+     * @param deviceId     the device phone number from which the call is placed; if the
+     *                     session is opened by a user, this must be one of the user's devices
+     * @param callee       the called phone number
+     * @param businessCode the cost center code to charge the call to
      * @param loginName    the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     makeBusinessCall(deviceId: string, callee: string, businessCode: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Initiates a call from a CCD agent to a supervisor.
+     * Initiates a call from a CCD agent to their supervisor.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
-     * <p>
-     * First, the call server initiates a call on the agent's `deviceId`. Then when
-     * the call is answered the call server calls the supervisor, and an
-     * {@link ON_CALL_CREATED} event is raised.
      *
-     * @param deviceId   the device phone number for which the call is made
-     * @param autoAnswer automatic answer on make call
+     * @param deviceId   the device phone number from which the call is placed; if the
+     *                   session is opened by a user, this must be one of the user's devices
+     * @param autoAnswer if `true`, the supervisor is called immediately; if `false`,
+     *                   the agent's device is called first
      * @param loginName  the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     makeSupervisorCall(deviceId: string, autoAnswer?: boolean, loginName?: string | null): Promise<boolean>;
     /**
-     * Initiates an enquiry call from a CCD agent to a pilot or a RSI point.
+     * Initiates a supervised transfer enquiry call from a CCD agent to a pilot or
+     * a RSI point.
+     * <p>
+     * The CCD pilot or the RSI point performs call distribution to select an agent
+     * that will be alerted. The `callProfile` is mandatory when the
+     * <em>Advanced Call Routing</em> distribution strategy is configured.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
-     * <p>
-     * The CCD pilot or the RSI point performs a call distribution to select an agent
-     * that will be alerted by this call. The `callProfile` is mandatory in case of
-     * "Advanced Call Routing" call distribution strategy.
      *
-     * @param deviceId       the device phone number for which the call is made
-     * @param pilot          the called CCD pilot or RSI point number
-     * @param correlatorData correlator data to add to the call
-     * @param callProfile    the call profile associated to this call
+     * @param deviceId       the device phone number from which the call is placed; if the
+     *                       session is opened by a user, this must be one of the user's devices
+     * @param pilot          the CCD pilot or RSI point number to call
+     * @param correlatorData optional correlator data to attach to the call
+     * @param callProfile    the call profile associated to this call; mandatory when the
+     *                       <em>Advanced Call Routing</em> distribution strategy is in use
      * @param loginName      the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
@@ -261,33 +250,37 @@ export declare class Telephony extends EventEmitter {
     /**
      * Initiates a local call to a CCD pilot or a RSI point.
      * <p>
+     * The CCD pilot or the RSI point performs call distribution to select an agent
+     * that will be alerted. The `callProfile` is mandatory when the
+     * <em>Advanced Call Routing</em> distribution strategy is configured.
+     * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
-     * <p>
-     * The CCD pilot or the RSI point performs a call distribution to select an agent
-     * that will be alerted by this call. The `callProfile` is mandatory in case of
-     * "Advanced Call Routing" call distribution strategy.
      *
-     * @param deviceId       the device phone number for which the call is made
-     * @param pilot          the called CCD pilot or RSI point number
-     * @param autoAnswer     automatic answer on make call
-     * @param correlatorData correlator data to add to the call
-     * @param callProfile    the call profile associated to this call
+     * @param deviceId       the device phone number from which the call is placed; if the
+     *                       session is opened by a user, this must be one of the user's devices
+     * @param pilot          the CCD pilot or RSI point number to call
+     * @param autoAnswer     if `true`, the pilot is called immediately; if `false`,
+     *                       the user's device is called first
+     * @param correlatorData optional correlator data to attach to the call
+     * @param callProfile    the call profile associated to this call; mandatory when the
+     *                       <em>Advanced Call Routing</em> distribution strategy is in use
      * @param loginName      the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     makePilotOrRSICall(deviceId: string, pilot: string, autoAnswer?: boolean, correlatorData?: CorrelatorData | null, callProfile?: CallProfile | null, loginName?: string | null): Promise<boolean | null>;
     /**
-     * Hangs up an active call; all parties are released.
+     * Releases the specified call; all parties are disconnected.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
-     * @param callRef   the call reference to hang up
+     * @param callRef   the call reference
      * @param loginName the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see dropme
      */
     release(callRef: string, loginName?: string | null): Promise<boolean>;
     /**
@@ -297,8 +290,8 @@ export declare class Telephony extends EventEmitter {
      * If the session is opened by a user, the device phone number must be one of
      * the user's devices.
      *
-     * @param callRef  the call reference of the call on hold
-     * @param deviceId the device phone number for which the operation is done
+     * @param callRef  the call reference of the active call
+     * @param deviceId the device phone number for which the operation is performed
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     alternate(callRef: string, deviceId: string): Promise<boolean>;
@@ -313,7 +306,7 @@ export declare class Telephony extends EventEmitter {
      * checking the capabilities of the involved leg (answer capability on the leg).
      *
      * @param callRef  the call reference of the ringing call
-     * @param deviceId the device phone number for which the operation is done
+     * @param deviceId the device phone number for which the operation is performed
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     answer(callRef: string, deviceId: string): Promise<boolean>;
@@ -321,32 +314,32 @@ export declare class Telephony extends EventEmitter {
      * Attaches the specified correlator data to the specified call.
      * <p>
      * This is used by the application to provide application-related information
-     * (limited to 32 bytes). In general, it is used to give information concerning
-     * a previously established call to the party of a second call.
+     * (limited to 32 bytes). In general, it is used to convey context from a
+     * previously established call to the party of a second call.
      *
      * @param callRef        the call reference
-     * @param deviceId       the device phone number for which the operation is done
+     * @param deviceId       the device phone number for which the operation is performed;
+     *                       if the session is opened by a user, this must be one of the user's devices
      * @param correlatorData the correlator data to attach
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     attachData(callRef: string, deviceId: string, correlatorData: CorrelatorData): Promise<boolean>;
     /**
-     * Transfers the active call to another user, without keeping control of the call.
+     * Transfers the active call to another party without keeping control of the call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param callRef    the reference of the active call
-     * @param transferTo the phone number to which the call is transferred
-     * @param anonymous  if `true`, the call will be transferred anonymously
+     * @param transferTo the phone number to transfer the call to
+     * @param anonymous  if `true`, the call is transferred anonymously
      * @param loginName  the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     blindTransfer(callRef: string, transferTo: string, anonymous?: boolean, loginName?: string | null): Promise<boolean>;
     /**
-     * Requests a callback on the call specified by the call reference for the
-     * specified user.
+     * Requests a callback on the specified call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -358,8 +351,7 @@ export declare class Telephony extends EventEmitter {
      */
     callback(callRef: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Returns the legs involved in the call specified by the call reference for the
-     * specified user.
+     * Returns the legs associated to the specified call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -368,11 +360,11 @@ export declare class Telephony extends EventEmitter {
      * @param callRef   the call reference
      * @param loginName the login name
      * @returns the list of {@link Leg} objects on success; `null` otherwise.
+     * @see getLeg
      */
     getLegs(callRef: string, loginName?: string | null): Promise<Leg[] | null>;
     /**
-     * Returns the leg specified by its id, involved in the call specified by the
-     * call reference for the specified user.
+     * Returns the specified leg of the specified call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -381,18 +373,19 @@ export declare class Telephony extends EventEmitter {
      * @param callRef   the call reference
      * @param legId     the leg identifier
      * @param loginName the login name
-     * @returns the {@link Leg} on success; `null` otherwise.
+     * @returns the {@link Leg} with the given identifier on success; `null` if not found.
+     * @see getLegs
      */
     getLeg(callRef: string, legId: string, loginName?: string | null): Promise<Leg | null>;
     /**
-     * Exits from the call specified by its reference for the specified user.
+     * Exits from the specified call for the specified user.
+     * <p>
+     * If the call is a single call, it is released; if it is a conference, the call
+     * carries on without the user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
-     * <p>
-     * If the call is a single call, it is released; if it is a conference, the call
-     * carries on without the user.
      *
      * @param callRef   the call reference
      * @param loginName the login name for whom the drop is done
@@ -400,22 +393,22 @@ export declare class Telephony extends EventEmitter {
      */
     dropme(callRef: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Puts on hold the call specified by its reference, on the specified device,
-     * for the specified user.
+     * Puts the specified call on hold on the specified device.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param callRef   the call reference
-     * @param deviceId  the device phone number from which the call is put on hold
+     * @param deviceId  the device phone number from which the hold is requested; if the
+     *                  session is opened by a user, this must be one of the user's devices
      * @param loginName the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see retrieve
      */
     hold(callRef: string, deviceId: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Makes a 3-party conference with a specified active call and a specified held
-     * call for the specified user.
+     * Creates a 3-party conference from the specified active call and a held call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -428,8 +421,7 @@ export declare class Telephony extends EventEmitter {
      */
     merge(callRef: string, heldCallRef: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Redirects an outgoing ringing call specified by its reference to the voice
-     * mail of the called user.
+     * Redirects an outgoing ringing call to the voice mail of the called user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -441,7 +433,11 @@ export declare class Telephony extends EventEmitter {
      */
     overflowToVoiceMail(callRef: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Gets the telephonic state and capabilities for the specified user.
+     * Returns a snapshot of the current telephonic state for the specified user.
+     * <p>
+     * This method performs a synchronous REST query. For an event-driven approach,
+     * use {@link requestSnapshot} instead, which raises an {@link ON_TELEPHONY_STATE}
+     * event asynchronously.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -449,25 +445,28 @@ export declare class Telephony extends EventEmitter {
      *
      * @param loginName the login name
      * @returns the {@link TelephonicState} on success; `null` otherwise.
+     * @see requestSnapshot
      */
     getState(loginName?: string | null): Promise<TelephonicState | null>;
     /**
-     * Parks the specified active call to a target device.
+     * Parks the specified active call on a target device.
      * <p>
-     * If the device is not provided, the call will be parked on the current device.
+     * If `parkTo` is not provided, the call is parked on the current device.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param callRef   the active call reference
-     * @param parkTo    the target device, or `null` to park on the current device
+     * @param parkTo    the target device extension number, or `null` to park on the
+     *                  current device
      * @param loginName the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see unPark
      */
     park(callRef: string, parkTo?: string | null, loginName?: string | null): Promise<boolean>;
     /**
-     * Returns the list of participants in the specified call.
+     * Returns the participants of the specified call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -476,10 +475,11 @@ export declare class Telephony extends EventEmitter {
      * @param callRef   the call reference
      * @param loginName the login name
      * @returns the list of {@link Participant} objects on success; `null` otherwise.
+     * @see getParticipant
      */
     getParticipants(callRef: string, loginName?: string | null): Promise<Participant[] | null>;
     /**
-     * Returns the specified participant in the specified call.
+     * Returns the specified participant of the specified call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -488,7 +488,8 @@ export declare class Telephony extends EventEmitter {
      * @param callRef       the call reference
      * @param participantId the participant identifier
      * @param loginName     the login name
-     * @returns the {@link Participant} on success; `null` otherwise.
+     * @returns the {@link Participant} with the given identifier on success; `null` if not found.
+     * @see getParticipants
      */
     getParticipant(callRef: string, participantId: string, loginName?: string | null): Promise<Participant | null>;
     /**
@@ -508,22 +509,22 @@ export declare class Telephony extends EventEmitter {
      */
     dropParticipant(callRef: string, participantId: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Releases the current call (active or ringing) to retrieve a previously put on
-     * hold call, cancelling a consultation call.
+     * Releases the current call to retrieve a previously held call (cancels a consultation call).
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param callRef        the held call reference
-     * @param deviceId       the device phone number for which the operation is done
+     * @param deviceId       the device phone number for which the operation is performed; if the
+     *                       session is opened by a user, this must be one of the user's devices
      * @param enquiryCallRef the reference of the enquiry call to cancel
      * @param loginName      the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     reconnect(callRef: string, deviceId: string, enquiryCallRef: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Starts, stops, pauses or resumes the recording of the specified call.
+     * Starts, stops, pauses, or resumes the recording of the specified call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -536,8 +537,7 @@ export declare class Telephony extends EventEmitter {
      */
     doRecordAction(callRef: string, action: RecordingAction, loginName?: string | null): Promise<boolean>;
     /**
-     * Redirects an incoming ringing call to another user or number, instead of
-     * responding to it.
+     * Redirects an incoming ringing call to another number or to voice mail.
      * <p>
      * If `redirectTo` is equal to `"VOICEMAIL"`, the incoming ringing call is
      * redirected to the user's voice mail.
@@ -547,8 +547,9 @@ export declare class Telephony extends EventEmitter {
      * administrator.
      *
      * @param callRef    the incoming ringing call reference
-     * @param redirectTo the phone number of the redirection, or `"VOICEMAIL"`
-     * @param anonymous  if `true`, the call will be redirected anonymously
+     * @param redirectTo the phone number of the redirection, or `"VOICEMAIL"` to redirect
+     *                   to the user's voice mail
+     * @param anonymous  if `true`, the redirect is anonymous and the caller identity is hidden
      * @param loginName  the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
@@ -556,38 +557,43 @@ export declare class Telephony extends EventEmitter {
     /**
      * Retrieves a call that has been previously put on hold.
      * <p>
-     * This method will return `false` if it is invoked from a session opened
-     * by an administrator.
+     * If the session has been opened for a user, the `loginName` parameter is
+     * ignored, but it is mandatory if the session has been opened by an
+     * administrator.
      *
-     * @param callRef  the held call reference
-     * @param deviceId the device phone number for which the operation is done
+     * @param callRef   the held call reference
+     * @param deviceId  the device phone number for which the operation is performed; if the
+     *                  session is opened by a user, this must be one of the user's devices
+     * @param loginName the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see hold
      */
     retrieve(callRef: string, deviceId: string, loginName?: string | null): Promise<boolean>;
     /**
      * Sends DTMF codes on the specified active call.
      *
      * @param callRef  the active call reference
-     * @param deviceId the device phone number for which the operation is done
+     * @param deviceId the device phone number for which the operation is performed; if the
+     *                 session is opened by a user, this must be one of the user's devices
      * @param number   the DTMF codes to send
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     sendDtmf(callRef: string, deviceId: string, number: string): Promise<boolean>;
     /**
-     * Sends the account info for the specified call, on the specified device.
+     * Sends the transaction code for the specified call on the specified device.
      * <p>
-     * This operation is used by a CCD agent to send the transaction code at the end
-     * of the call. The string value must comply with the transaction code accepted
-     * by OXE (numerical values only).
+     * Used by a CCD agent to send the transaction code at the end of a call.
+     * The value must comply with the OmniPCX Enterprise transaction code format
+     * (numeric values only).
      *
      * @param callRef     the call reference
      * @param deviceId    the device phone number for which the operation is done
-     * @param accountInfo the transaction code
+     * @param accountInfo the transaction code (numeric values only)
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     sendAccountInfo(callRef: string, deviceId: string, accountInfo: string): Promise<boolean>;
     /**
-     * Transfers a specified active call to a specified held call for the specified user.
+     * Transfers the specified active call to the specified held call.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -600,7 +606,7 @@ export declare class Telephony extends EventEmitter {
      */
     transfer(callRef: string, heldCallRef: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Logs the specified user on a specified desk sharing set.
+     * Logs the specified user onto a desk sharing set.
      * <p>
      * The user must be configured as a desk sharing user.
      * <p>
@@ -608,14 +614,14 @@ export declare class Telephony extends EventEmitter {
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
-     * @param dssDeviceNumber the desk sharing set phone number
+     * @param dssDeviceNumber the desk sharing set phone number to log on to
      * @param loginName       the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
      * @see deskSharingLogOff
      */
     deskSharingLogOn(dssDeviceNumber: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Logs off the specified user from the desk sharing set.
+     * Logs the specified user off from their desk sharing set.
      * <p>
      * The user must be configured as a desk sharing user.
      * <p>
@@ -629,7 +635,7 @@ export declare class Telephony extends EventEmitter {
      */
     deskSharingLogOff(loginName?: string | null): Promise<boolean>;
     /**
-     * Gets the states of all devices of the specified user.
+     * Returns the operational state of all devices belonging to the specified user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -637,68 +643,76 @@ export declare class Telephony extends EventEmitter {
      *
      * @param loginName the login name
      * @returns the list of {@link DeviceState} objects on success; `null` otherwise.
+     * @see getDeviceState
      */
     getDevicesState(loginName?: string | null): Promise<DeviceState[] | null>;
     /**
-     * Gets the state of the specified device of the specified user.
+     * Returns the operational state of the specified device.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
-     * @param deviceId  the device phone number for which the operation is done
+     * @param deviceId  the device phone number
      * @param loginName the login name
-     * @returns the {@link DeviceState} on success; `null` otherwise.
+     * @returns the {@link DeviceState} for the requested device on success; `null` on error
+     *          or if the device does not belong to the user.
+     * @see getDevicesState
      */
     getDeviceState(deviceId: string, loginName?: string | null): Promise<DeviceState | null>;
     /**
-     * Picks up the specified incoming call for another user.
+     * Picks up an incoming call ringing on another user's device.
      *
-     * @param deviceId         the device phone number for which the operation is done
-     * @param otherCallRef     the reference of the call to pick up (on the remote user)
+     * @param deviceId         the device phone number from which the pickup is performed;
+     *                         if the session is opened by a user, this must be one of the user's devices
+     * @param otherCallRef     the reference of the call to pick up on the remote user
      * @param otherPhoneNumber the phone number on which the call is ringing
-     * @param autoAnswer       if `true`, automatically answers the call after the pickup
+     * @param autoAnswer       if `true`, the call is automatically answered after pickup
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     pickUp(deviceId: string, otherCallRef: string, otherPhoneNumber: string, autoAnswer?: boolean): Promise<boolean>;
     /**
-     * Performs an intrusion in the active call of a called user.
+     * Intrudes into the active call of a busy user.
+     * <p>
+     * Intrusion requires that the current device is in releasing state while calling
+     * a user who is engaged in a call, and that both the current device and the
+     * engaged users have the intrusion capability configured.
      * <p>
-     * No parameter is required to invoke the intrusion: it only depends on the
-     * current intrusion capability of the current device. It is based on the fact
-     * that the current device must be in releasing state while calling a user which
-     * is in a busy call with another user, the current device has the intrusion
-     * capability, and the 2 users engaged in the call have the capability to allow
-     * intrusion.
+     * Available from O2G 2.4.
      *
-     * @param deviceId the device from which the intrusion is requested
+     * @param deviceId the device phone number from which the intrusion is initiated
      * @returns `true` if the operation succeeded; `false` otherwise.
      * @since O2G 2.4
      */
     intrusion(deviceId: string): Promise<boolean>;
     /**
-     * Unparks a call from a target device.
+     * Unparks a previously parked call onto the specified device.
      *
-     * @param deviceId    the device from which the unpark request is made
-     * @param heldCallRef the reference of the held call to unpark
+     * @param deviceId    the device from which the unpark is requested
+     * @param heldCallRef the reference of the parked call
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see park
      */
     unPark(deviceId: string, heldCallRef: string): Promise<boolean>;
     /**
-     * Retrieves the hunting group status of the specified user.
+     * Returns the hunting group login status of the specified user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param loginName the login name
-     * @returns the {@link HuntingGroupStatus} on success; `null` otherwise.
+     * @returns the {@link HuntingGroupStatus} indicating whether the user is logged into
+     *          their hunting group on success; `null` otherwise.
+     * @see huntingGroupLogOn
+     * @see huntingGroupLogOff
      */
     getHuntingGroupStatus(loginName?: string | null): Promise<HuntingGroupStatus | null>;
     /**
-     * Logs on the specified user in their current hunting group.
+     * Logs the specified user into their current hunting group.
      * <p>
      * The user must be configured as a member of a hunting group.
+     * Has no effect and returns `true` if the user is already logged in.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -710,9 +724,10 @@ export declare class Telephony extends EventEmitter {
      */
     huntingGroupLogOn(loginName?: string | null): Promise<boolean>;
     /**
-     * Logs off the specified user from their current hunting group.
+     * Logs the specified user off from their current hunting group.
      * <p>
      * The user must be configured as a member of a hunting group.
+     * Has no effect and returns `true` if the user is already logged off.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -724,7 +739,7 @@ export declare class Telephony extends EventEmitter {
      */
     huntingGroupLogOff(loginName?: string | null): Promise<boolean>;
     /**
-     * Sets the specified user as a member of a hunting group.
+     * Adds the specified user as a member of an existing hunting group.
      * <p>
      * The request will fail if the hunting group does not exist. If the user
      * already belongs to the group, nothing is done and `true` is returned.
@@ -740,7 +755,7 @@ export declare class Telephony extends EventEmitter {
      */
     addMeToHuntingGroup(hgNumber: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Removes the specified user from a hunting group.
+     * Removes the specified user from an existing hunting group.
      * <p>
      * The request will fail if the hunting group does not exist. If the user does
      * not belong to the group, nothing is done and `true` is returned.
@@ -756,29 +771,36 @@ export declare class Telephony extends EventEmitter {
      */
     removeMeFromHuntingGroup(hgNumber: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Gets the list of hunting groups on the OXE node the specified user belongs to.
+     * Returns the hunting groups available on the OmniPCX Enterprise node the
+     * specified user belongs to.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param loginName the login name
-     * @returns the {@link HuntingGroups} on success; `null` otherwise.
+     * @returns the {@link HuntingGroups} listing available hunting groups and the user's
+     *          current membership on success; `null` otherwise.
+     * @see getHuntingGroupStatus
+     * @see addMeToHuntingGroup
+     * @see removeMeFromHuntingGroup
      */
     queryHuntingGroups(loginName?: string | null): Promise<HuntingGroups | null>;
     /**
-     * Returns the list of callback requests for the specified user.
+     * Returns the pending callback requests for the specified user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param loginName the login name
-     * @returns the list of {@link Callback} objects on success; `null` otherwise.
+     * @returns the list of pending {@link Callback} objects on success; `null` otherwise.
+     * @see deleteCallbacks
+     * @see deleteCallback
      */
     getCallbacks(loginName?: string | null): Promise<Callback[] | null>;
     /**
-     * Deletes all callback requests for the specified user.
+     * Deletes all pending callback requests for the specified user.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
@@ -786,108 +808,117 @@ export declare class Telephony extends EventEmitter {
      *
      * @param loginName the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see getCallbacks
      */
     deleteCallbacks(loginName?: string | null): Promise<boolean>;
     /**
-     * Deletes the specified callback request for the specified user.
+     * Deletes the specified callback request.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
-     * @param callbackId the callback identifier
+     * @param callbackId the callback identifier as returned by {@link getCallbacks}
      * @param loginName  the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see getCallbacks
+     * @see deleteCallbacks
      */
     deleteCallback(callbackId: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Returns the current new mini message for the specified user.
-     * <p>
-     * As soon as a message is read, it is erased from OXE and cannot be read again.
-     * Messages are retrieved in Last In First Out order.
+     * Returns the next unread mini message for the specified user.
      * <p>
-     * This method will return `null` if all messages have been retrieved.
+     * Messages are consumed on read — once retrieved, a message is deleted from the
+     * OXE and cannot be read again. Messages are returned in Last In First Out order.
+     * Returns `null` when there are no more unread messages.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param loginName the login name
-     * @returns the {@link MiniMessage} on success; `null` otherwise.
+     * @returns the {@link MiniMessage} on success; `null` if there are no unread
+     *          messages or on error.
      */
     getMiniMessage(loginName?: string | null): Promise<MiniMessage | null>;
     /**
-     * Sends the specified mini message to the specified recipient.
+     * Sends a mini message to the specified recipient.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
-     * @param recipient the phone number of the mini message recipient
-     * @param message   the mini message text
+     * @param recipient the phone number of the message recipient
+     * @param message   the message text
      * @param loginName the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see getMiniMessage
      */
     sendMiniMessage(recipient: string, message: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Requests a callback from an idle device of the specified user.
+     * Requests a callback from an idle device.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
-     * @param callee    the phone number of the called party for which a callback is requested
+     * @param callee    the phone number of the party to request a callback from
      * @param loginName the login name
      * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see getCallbacks
+     * @see deleteCallbacks
      */
     requestCallback(callee: string, loginName?: string | null): Promise<boolean>;
     /**
-     * Asks a snapshot event on the specified user.
+     * Requests a snapshot event to receive the current telephonic state via an
+     * {@link ON_TELEPHONY_STATE} event.
+     * <p>
+     * The resulting event will contain the full {@link TelephonicState} including
+     * active calls and device capabilities. If a second request is issued while the
+     * first is still in progress, it has no effect.
      * <p>
-     * The {@link ON_TELEPHONY_STATE} event will contain the {@link TelephonicState}
-     * (calls and device capabilities). If a second request is asked while the
-     * previous one is still in progress, it has no effect.
+     * If an administrator calls this with a `null` `loginName`, the snapshot is
+     * requested for all users, which may take time depending on the number of users.
      * <p>
      * If the session has been opened for a user, the `loginName` parameter is
      * ignored, but it is mandatory if the session has been opened by an
      * administrator.
      *
      * @param loginName the login name
-     * @returns `true` if the request was successfully submitted; `false` otherwise.
+     * @returns `true` if the operation succeeded; `false` otherwise.
+     * @see getState
      */
     requestSnapshot(loginName?: string | null): Promise<boolean>;
     /**
-     * Toggles the microphone or interphony state on the specified device.
-     * <p>
-     * This action acts as a flip/flop and has the same effect as pressing the key:
+     * Toggles interphony or hands-free mode on the specified device.
      * <ul>
-     * <li>activates or deactivates the microphone if the device has an outgoing or established call</li>
+     * <li>activates or deactivates the microphone if the device has an active call</li>
      * <li>activates or deactivates the interphony if the device is idle</li>
      * <li>has no effect if the device is ringing on an incoming call</li>
      * </ul>
      * <p>
-     * This operation is done in blind mode: no state event is provided on the push,
-     * but when the device returns to idle after a call, the microphone comes back to
-     * the active state.
+     * This operation is done in blind mode: no state event is raised on the push,
+     * but when the device returns to idle after a call, the microphone comes back
+     * to the active state.
      *
-     * @param deviceId the device phone number for which the operation is done
+     * @param deviceId the device phone number for which the operation is performed
      * @returns `true` if the operation succeeded; `false` otherwise.
      */
     toggleInterphony(deviceId: string): Promise<boolean>;
     /**
-     * Query the specified CCD pilot information.
-     * <p>
-     * This method is used to get various information on the CCD pilot routing
-     * capabilities.
+     * Returns transfer possibilities for the specified CCD pilot.
      * <p>
-     * This method will return `null` if it is invoked from a session opened
-     * by an administrator.
+     * If the session has been opened for a user, the `loginName` parameter is
+     * ignored, but it is mandatory if the session has been opened by an
+     * administrator.
      *
-     * @param nodeId                  the PCX Enterprise node id
-     * @param pilotNumber             the pilot number
-     * @param pilotTransferQueryParam optional call profile context parameters
+     * @param nodeId                  the OmniPCX Enterprise node ID
+     * @param pilotNumber             the CCD pilot directory number
+     * @param pilotTransferQueryParam optional query criteria to filter results by agent number,
+     *                                priority transfer, supervised transfer, or call profile
      * @param loginName               the login name
-     * @returns the {@link PilotInfo} on success; `null` otherwise.
+     * @returns the {@link PilotInfo} describing the pilot's queue state and transfer possibilities
+     *          on success; `null` otherwise.
      * @since 2.7
      */
     getPilotInfo(nodeId: number, pilotNumber: string, pilotTransferQueryParam?: PilotTransferQueryParameters | null, loginName?: string | null): Promise<PilotInfo | null>;