> For the complete documentation index, see [llms.txt](https://bogdanov-inc.gitbook.io/webrtc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bogdanov-inc.gitbook.io/webrtc/rukovodstvo-polzovatelya/metody-api.md).
# Методы API
Для использования некоторых функций телефона предусмотрены методы API для работы с ним. Они выводятся в глобальную область видимости в переменную **OKTELLPhone** (или **window****.OKTELLPhone**)
{% hint style="info" %}
Стоит иметь в виду, что для инициализации телефона требуется некоторое время. Поэтому обращение к его методам до момента полной инициализации страницы может привести к ошибке. Для корректной работы, желательно пользоваться методом **onInit** (добавлен в версии 2.0.7) для определения статуса завершения инициализации / установки необходимых параметров софтфона.
{% endhint %}
####
#### \[noGUIMode] Режим сокращённого интерфейса
Для интеграции с **CRM** системами **WebRTC** телефон имеет режим запуска с "урезанной" визуальной частью. В этом режиме отсутствует номеранабиратель и некоторые другие элементы управления, отображается только текущий статус и активные сессии.
Включение/отключение режима:
```javascript
OKTELLPhone.noGUIMode(true); // значение false - отключает режим
```
####
#### \[authorize] Авторизация пользователя
Метод **authorize** позволяет выполнить авторизацию пользователя на sip-сервере. Требуемые входящие параметры: ***username, password, domain, server,*** например:
```javascript
const user = {
username: "testuser",
password: "testpassword",
domain: "devel-connector.cloud.oktell.studio",
server: "cloud.oktell.studio",
};
```
Для непосредственной авторизации, необходимо вызвать метод **authorize** следующим образом:
```javascript
const authButton = document.getElementById("auth");
authButton.addEventListener("click", () => {
try {
OKTELLPhone.authorize(user);
} catch (error) {
console.error(error);
}
});
```
####
#### \[getActiveCallId] Получение callid активного звонка
На данный момент в телефоне предусмотрен сценарий лишь с одним одновременно активным звонком. Если звонков несколько, то все звонки кроме активного находятся в состоянии hold. При смене этого состояния в одном из таких звонков, остальные автоматически переводятся в состояние hold. Таким образом мы получаем возможность запросить от телефона **callid** его текущего активного звонка. Для этого реализован следующий метод:
```javascript
const activeCallId = OKTELLPhone.getActiveCallId();
// метод вернёт строковое значение callid активного звонка, при его наличии
```
#### \[callNumber] Исходящий вызов
Метод **callNumber** используется для совершения исходящего вызова на конкретный номер.
```javascript
const callButton = document.getElementById("call");
const number = "267"
callButton.addEventListener("click", () => {
try {
OKTELLPhone.callNumber(number);
} catch (error) {
console.error(error);
}
});
```
#### \[answer] Ответ на входящий вызов
Метод **answer** используется для приема входящего вызова. Необходимо в качестве параметра метода указать **callid** звонка полученного от внешней системы.
```javascript
const answerButton = document.getElementById("answer");
answerButton.addEventListener("click", () => {
try {
OKTELLPhone.answer(callid);
} catch (error) {
console.error(error);
}
});
```
{% hint style="info" %}
В случае, если метод вызывается без callid, то телефон выполнит поиск по текущим активным сессиям, и проверит, если какая-либо из них ожидает ответа. Если подходящая сессия будет найдена, то телефон ответит на данный вызов автоматически.
{% endhint %}
#### \[endCall] Отбой активного звонка
Метод **endCall** используется для отбоя активного вызова. Необходимо в качестве параметра метода указать **callid** звонка.
```javascript
const endCall = async (callid: string) => {
if (!callid) return false;
const Call: RTCSession | undefined = getSessionById(callid);
if (Call) {
Call.terminate();
return true;
}
return false;
};
```
{% hint style="info" %}
id Активного звонка можно получить, используя метод getActiveCallId
{% endhint %}
#### \[holdToggle] Перевод звонка в удержание
Для управления состоянием hold звонка реализован метод **holdToggle**:
```javascript
const holdButton = document.getElementById("hold");
holdButton.addEventListener("click", async () => {
try {
const holdState = await OKTELLPhone.holdToggle(callid);
/*
в holdState вернётся значение вида { local: true, remote: false }
отражающее состояние локального/удалённого удержания на момент после
выполнения текущего метода
*/
} catch (error) {
console.error(error);
}
});
```
#### \[refer] Перевод звонка на другого пользователя
Для управления функционалом перевода звонка реализован метод **refer**:
"слепой" перевод - необходимо указать ID сессии, с пользователем, которого необходимо перевести и номер абонента, на которого необходимо перевести звонок:
```javascript
const referButton = document.getElementById("refer");
referButton.addEventListener("click", async () => {
try {
const fromID = OKTELLPhone.getActiveCallId();
const toNumber = "260";
OKTELLPhone.refer({ fromID: fromID, toNumber: toNumber });
} catch (error) {
console.error(error);
}
});
```
Также возможно перевести звонок на пользователя, с которым уже существует активная сессия:
```javascript
const referButton = document.getElementById("refer");
referButton.addEventListener("click", async () => {
try {
const fromID = OKTELLPhone.getActiveCallId();
const toID = *ID сессии с пользователем, на которого необходимо перевести звонок*;
OKTELLPhone.refer({ fromID: fromID, toID: toID });
} catch (error) {
console.error(error);
}
});
```
{% hint style="info" %}
Стоит принимать во внимание, что метод **getActiveCallId**() возвращает **id** сессии, которая в данный момент находится в ***unhold*** состоянии. Рассмотрим на примере:
Исходный пользователь **А**. Выполнено соединение с пользователем **Б**. Необходимо перевести пользователя **Б** на пользователя **В**. Выполняем звонок абоненту **В**. При этом после соединения с **В**, **getActiveCallId**() вернёт **id** сессии **А**** -** **В**. В таком случае в параметр **toID** имеет смысл передать **id** сессии **А**** - ****Б**. Либо снять с ***hold*** звонок **А**** - ****Б**, и в **toID** передать уже **id** из **А**** - ****В**. В обоих случаях выполнится соединение пользователей **Б** и **В**, но будет различаться последовательность запросов и пользователь, которому будет предложено подтвердить перевод.
{% endhint %}
#### \[dnd] Режим "Не беспокоить" / DnD
Для случаев, когда требуется на время перестать принимать входящие вызовы, предусмотрен метод **dnd.** При активации режима, на все входящие *INVITE* запросы будет отравлен ответ с **480** кодом.
```javascript
const dndButton = document.getElementById("dnd");
dndButton.addEventListener("click", async () => {
try {
OKTELLPhone.dnd(true);
} catch (error) {
console.error(error);
}
});
```
#### \[muteToggle] Управление отключением микрофона / камеры
Для возможности деактивировать микрофон или камеру предусмотрен метод **muteToggle**:
```javascript
const muteButton = document.getElementById("mute-microphone");
muteButton.addEventListener("click", async () => {
try {
OKTELLPhone.muteToggle(callid, "audio");
/*
метод работает в режиме "переключения", т.е. если на момент его активации
микрофон/камера были отключены, то они будут активированы, и наоборот.
если необходимо выключить/включить передачу изображения с собственной камеры
вместо "audio" нужно указать "video"
*/
} catch (error) {
console.error(error);
}
});
```
#### \[setCodecSettings, getCodecSettings, getSupportedCodecs] Управление аудио / видео кодеками
Для возможности управления приоритетом и типами используемых в звонках кодеков, предусмотрены методы **setCodecSettings**, **getCodecSettings**, **getSupportedCodecs**.
Подробнее о кодеках браузера можно ознакомиться в соответствующей [документации](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpTransceiver/setCodecPreferences). Следует принять во внимание, что приоритет кодеков будет установлен согласно их позиции в массиве: чем выше расположен элемент кодека, тем выше будет его приоритет при определении кодека в звонке.
{% hint style="info" %} **Важно**: при звонке, если кодеки, установленные пользователем **А**, не будут иметь "пересечений" с кодеками пользователя **Б**, то возможен сценарий одностороннего отсутствия потока данных соответствующего типа (аудио или видео). Поэтому не рекомендуется отключать кодеки полностью, более безопасным вариантом будет просто установка более высокого приоритета требуемым кодекам.
{% endhint %}
```javascript
const setCodecsButton = document.getElementById("set-codecs");
setCodecsButton .addEventListener("click", async () => {
try {
const audioCodecs = [
{
channels: 2,
clockRate: 48000,
mimeType: "audio/opus",
sdpFmtpLine: "minptime=10;useinbandfec=1",
},
{
channels: 2,
clockRate: 48000,
mimeType: "audio/red",
sdpFmtpLine: "111/111",
},
{ channels: 1, clockRate: 8000, mimeType: "audio/G722" }
];
const currentCodecs = OKTELLPhone.setCodecSettings({ audio: audioCodecs });
/*
метод возвращает текущие установленные пользователем кодеки
*/
} catch (error) {
console.error(error);
}
});
```
Метод **getCodecSettings** предназначен для получения текущих установленных кодеков пользователя. Метод **getSupportedCodecs** - для получения всех кодеков, поддерживаемых текущим браузером. Оба метода возвращают идентичный объект вида:
```javascript
const allCodecs = OKTELLPhone.getSupportedCodecs();
/*
{
audio: [
{
channels: 2,
clockRate: 48000,
mimeType: "audio/opus",
sdpFmtpLine: "minptime=10;useinbandfec=1",
},
{
channels: 2,
clockRate: 48000,
mimeType: "audio/red",
sdpFmtpLine: "111/111",
}
],
video: [
{clockRate: 90000, mimeType: 'video/VP9', sdpFmtpLine: 'profile-id=0'},
{clockRate: 90000, mimeType: 'video/VP8'},
{clockRate: 90000, mimeType: 'video/AV1'}
],
}
*/
```
#### \[setCallHistory] Установка истории вызовов
Поскольку один и тот же SIP пользователь может быть использован для звонков на разных доменах, имеет смысл оставить функционал хранения истории звонков за конкретным доменом. Для вывода списка звонков в данном случае предусмотрен метод **setCallHistory** для "внешней" установки истории вызовов. Метод принимает массив записей следующего вида:
```javascript
const setHistoryButton = document.getElementById("set-history");
setHistoryButton.addEventListener("click", async () => {
try {
const data = await apiRequest("/some/api/url/callhistory");
/*
data == [
{
call_to: {
displayname: "Алексей Попович",
username: "sipUser20",
number: "204",
avatar_url: "", // ссылка на изображение аватара пользователя при наличии
},
call_from: {
displayname: "Илья Муромец",
username: "sipUser23",
number: "208",
avatar_url: "",
},
call_start: "2022-05-23T20:15",
call_end: "2022-05-23T20:30",
},
{
call_to: {
displayname: "Змей Тугарин",
username: "sipUser13",
number: "231",
avatar_url: "",
},
call_from: {
displayname: "Константин Бессметрный",
username: "sipUser71",
number: "230",
avatar_url: "",
},
call_start: "2022-05-23T13:15",
call_end: "2022-05-23T14:30",
}
];
*/
OKTELLPhone.setCallHistory(data);
} catch (error) {
console.error(error);
}
});
```
После корректной установки истории вызовов, справа от поля ввода номера появится соответствующий UI элемент с возможностью посмотреть историю вызовов, и совершить тот или звонок повторно, при необходимости. Также при вводе номера в поле ввода будут выводится подсказки с номерами, присутствующими в истории звонков и подходящими к введённым значением.
#### \[setAutoUnhold] Активация режима autoUnhold
Для ситуаций, когда есть необходимость вернуть звонок с удержания после отклонённого запроса на перевод, предусмотрена данная опция. Для управления данной настройкой создан метод **setAutoUnhold**.
```javascript
OKTELLPhone.setAutoUnhold(true);
```
#### \[getUserSettings] Получение списка текущих активных настроек пользователя
Предусмотрен метод **getUserSettings** возвращающий текущие установленные пользователем настройки телефона. Например:
```javascript
const settings = OKTELLPhone.getUserSettings();
if (settings && settings.autoUnhold) {
// необходимые логические операции
}
```
#### \[logout] Сброс авторизации (Логаут)
Метод предназначен для выхода из текущего SIP-аккаунта пользователя. После выполнения выхода будет отображён стандартный интерфейс формы авторизации.
```javascript
const logoutButton = document.getElementById("sip-logout");
logoutButton.addEventListener("click", () => {
OKTELLPhone.logout();
});
```
#### \[onInit] Callback метод инициации приложения
Метод вызывается после успешной инициализации апплета **OKTELLPhone**. Метод возможно задать сразу после подключения скрипта приложения.
```html
```
