Перейти к содержанию

callsRtc#

Бета-версия

Функциональность находится в режиме бета-версии. Функции могут быть изменены, а также могут работать нестабильно. В будущем за функционал может взиматься дополнительная плата.
Подключение к функционалу можно запросить через техподдержку GREEN-API

callsRtc — это WebSocket-соединение, через которое проходит всё, что связано со звонком, кроме команд:

  • сервер сообщает, что происходит со звонком: пошёл дозвон, поступил входящий вызов, разговор начался, звонок завершён;
  • приложение и сервер договариваются о передаче звука по технологии WebRTC.

Соединение нужно открыть до того, как вы вызовете любой метод звонков, и держать открытым всё время звонка. Методы callsDial, callsAccept, callsReject и callsHangUp возвращают 200 OK. Что происходит со звонком дальше, видно лишь по сообщениям в этом соединении.

Подключение#

Для получения сообщений о звонках требуется установить websocket-соединение по адресу:

WSS 
{{apiUrl}}/waInstance{{idInstance}}/callsRtc/{{apiTokenInstance}}

Адрес совпадает с адресом остальных методов, меняется только схема: вместо https указывается wss.

Для получения параметров websocket-соединения apiUrl, idInstance и apiTokenInstance обратитесь к разделу Перед началом работы.

Примечание

Сразу после подключения сервер присылает текущее состояние звонка, а затем присылает его при каждом изменении. Поэтому приложение, перезапущенное посреди звонка, узнаёт верное состояние без дополнительных запросов.
Если соединение оборвалось, его нужно установить заново: звонок на сервере при этом не завершается. А вот передача звука прерывается — вместе с соединением сервер разбирает аудиомост, поэтому после переподключения звук требуется поднять заново, отправив новое предложение о передаче звука.

Формат сообщений#

Сообщения передаются в формате JSON. В каждом сообщении есть поле type, а остальные поля зависят от его значения: помимо type в сообщении идёт не больше одного поля с данными, а у некоторых сообщений его нет вовсе. Наборы сообщений в двух направлениях разные — единого формата для обеих сторон нет.

Сообщения от сервера#

Параметр Тип Описание
type string Тип сообщения. Принимает значения state, answer, ice-candidate, error
state object Состояние звонка. Приходит только при type = state. Состав полей описан в разделе Состояние звонка
answer object Ответ сервера на предложение о передаче звука в формате WebRTC. Приходит только при type = answer. Передайте его в WebRTC как есть, разбирать содержимое не требуется
candidate object Вариант сетевого маршрута для передачи звука в формате WebRTC (ICE-кандидат). Приходит только при type = ice-candidate. Передайте его в WebRTC как есть
message string Текст ошибки. Приходит только при type = error. Перечень значений — в разделе Ошибки

Сообщения от приложения#

Параметр Тип Описание
type string Тип сообщения. Принимает значения offer, ice-candidate, stop
offer object Предложение о передаче звука в формате WebRTC. Отправляется при type = offer. Предложение всегда формирует приложение, сервер отвечает на него сообщением с типом answer — в том числе и при входящем вызове
candidate object Вариант сетевого маршрута для передачи звука в формате WebRTC (ICE-кандидат). Отправляется при type = ice-candidate

Сообщение с типом stop отправляется без дополнительных полей — {"type": "stop"} — и означает, что приложение больше не передаёт звук.

Состояние звонка#

Объект state описывает, что сейчас происходит со звонком.

Параметр Тип Описание
state string Состояние звонка. Принимает значения:
idle — звонка нет
inc-call — поступил входящий вызов
out-call — идёт дозвон по исходящему вызову
on-call — разговор идёт
info object Данные о вызове и собеседнике. Приходит в состояниях inc-call, out-call и on-call
reason string Причина завершения звонка. Приходит только в сообщении о переходе в состояние idle и только если сервер её назвал

Объект info#

Параметр Тип Описание
id string Идентификатор вызова
wid string Идентификатор собеседника, например 79001234567@c.us или 120650379300963@lid
name string Имя собеседника из его профиля WhatsApp. Приходит пустым, если имени в профиле нет; при звонке с идентификатора lid его обычно нет. В этом случае имя можно найти самостоятельно методом GetContacts, сравнив wid с полями id и newChatId контактов

Причины завершения#

Значение поля reason — это слово сервера о том, почему звонок закончился. Известные значения:

Значение Описание
hangup Трубку положили
timeout Истекло время ожидания
accepted_elsewhere Вызов приняли на другом устройстве того же аккаунта, например на телефоне
rejected_elsewhere Вызов отклонили на другом устройстве того же аккаунта
no-media Звук не пошёл
connect-timeout Не удалось установить соединение за отведённое время
instance-gone Инстанс стал недоступен
rejected:<причина> Вызов отклонён, после двоеточия сервер указывает причину

Перечень открытый: если пришло значение, которого нет в таблице, покажите его как есть, а не отбрасывайте.

Ошибки#

Об ошибке сервер сообщает сообщением с типом error, текст ошибки — в поле message.

{
    "type": "error",
    "message": "no active call"
}
Значение message Описание
no active call Предложение о передаче звука отправлено, когда звонка нет. Сначала дождитесь завершения метода callsDial или callsAccept, и только потом отправляйте сообщение с типом offer

Отдельно от сообщений об ошибках сервер может закрыть соединение. Код закрытия показывает, стоит ли подключаться заново:

Код закрытия Описание
С 4000 по 4999 Сервер отказал: звонки не подключены на инстансе либо отключены на стороне сервера. Подключаться заново бесполезно — причину нужно устранить, а затем открыть новое соединение
Остальные коды Обрыв связи. Соединение следует установить заново; идущий звонок при этом на сервере сохраняется, а звук потребуется поднять заново

Примеры сообщений#

Начался дозвон по исходящему вызову:

{
    "type": "state",
    "state": {
        "state": "out-call"
    }
}

Звонок завершён, потому что положили трубку:

{
    "type": "state",
    "state": {
        "state": "idle",
        "reason": "hangup"
    }
}

Приложение сообщает, что больше не передаёт звук:

{
    "type": "stop"
}