React клиент#

Бета-версия

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

examples/react в репозитории библиотеки — это рабочий софтфон и эталонная реализация для библиотеки: всё, что описано в документации, там применено в работающем виде. С этого примера и стоит начинать. Попробовать его, не устанавливая, можно на voip.green-api.com.

Чтобы воспользоваться примером, нужно получить ID инстанса и токен в личном кабинете; для тестирования подойдёт бесплатный тариф «Разработчик». Инстанс должен быть уже авторизован по QR-коду — библиотека занимается только звонками.

Что умеет пример#

Авторизация по idInstance и apiTokenInstance, сохраняется между перезагрузками страницы.
Набор по номеру телефона — с выбором страны и форматированием по ходу ввода — либо по идентификатору @lid, когда номера собеседника нет.
Контакты с аватарками и поиском: показаны оба адреса собеседника, звонок прямо из строки.
Входящие звонки: окно с аватаркой и именем звонящего, приём и отклонение.
Экран звонка: с кем идёт разговор, сколько он длится, индикаторы уровня звука в обе стороны, отключение микрофона, отбой.
Звуки вызова: гудки дозвона и рингтон входящего — они синтезируются, звуковых файлов в проекте нет.
Состояние соединения, включая переподключение прямо посреди звонка.

1. Скачивание примера#

Для установки примера необходимо скачать код из github репозитория.

Скачайте архив или воспользуйтесь командной строкой:

git clone https://github.com/green-api/whatsapp-api-calls-client-js.git

2. Запуск клиента#

В командной строке перейдите в папку примера и установите зависимости:

cd whatsapp-api-calls-client-js/examples/react  
npm install  
npm run dev

npm install достаточно выполнять один раз при первой установке.

Vite напечатает адрес, на котором поднялся сервер разработки — откройте его в браузере.

Для остановки сервера нажмите Ctrl + C и затем нажмите кнопку Y.

3. Заполнение необходимых данных для авторизации#

При первом запуске пример открывается формой входа Sign in.

Необходимые данные находятся в вашем личном кабинете GREEN-API:

API URL — адрес API вашего инстанса, например https://1234.api.green-api.com
Instance ID — идентификатор инстанса (idInstance)
API token — токен инстанса (apiTokenInstance)

Заполните поля и нажмите Sign in. Введённые данные пример сохраняет, поэтому после перезагрузки страницы входить заново не нужно.

Для выхода из инстанса откройте профиль — значок в правом верхнем углу страницы.

В окне профиля видно состояние инстанса (authorized), его номер, устройство и кнопка Log out для выхода.

4. Приём входящих звонков#

После входа приложение начинает принимать входящие звонки.

О входящем звонке сообщает плашка Incoming call с именем или номером звонящего: зелёная кнопка принимает вызов, красная — отклоняет.

Браузер может спросить разрешение на использование вашего микрофона, для передачи голоса. Необходимо разрешить это действие.

После принятия открывается экран звонка: состояние In call, таймер разговора, индикаторы уровня звука — свой (YOU) и собеседника (PEER), кнопка отключения микрофона и красная кнопка отбоя.

Известные проблемы и методы их устранения

При отклонении звонка вызов по-прежнему будет поступать на телефон, что не является ошибкой, а особенностью. Одно из решений данной проблемы - ответить на звонок и сразу сбростить, в этом случае звонок на телефон прекратится.

Из-за нестабильности технологии voip вы можете не увидеть уведомление о входящем звонке в окне браузера.

5. Выполнение исходящих звонков#

Наберите номер абонента на клавиатуре слева — код страны выбирается в списке рядом с полем Phone number — либо найдите собеседника в справочнике контактов справа и позвоните прямо из строки. Затем нажмите зелёную кнопку вызова.

Дальше открывается экран звонка. Пока идёт дозвон, на нём состояние Ringing..., а когда собеседник ответит — In call. Там же таймер, индикаторы уровня звука, отключение микрофона и отбой.

Если звонок не состоялся, убедитесь, что соединение установлено — вверху страницы для этого есть индикатор Connected, — и что в консоли разработчика нет ошибок.

На некоторых телефонах необходимо, чтобы WhatsApp* был запущен фоновым процессом для приёма входящих звонков.

Как устроен пример#

Что смотреть в первую очередь, в порядке прохождения звонка:

Файл	Что в нём
`src/voip/index.ts`	Единственные клиент и соединение на всё приложение, а также последние потоки и статус связи — чтобы компонент, смонтированный позже, их всё-таки нашёл
`src/hooks/useCallsConnection.ts`	То же соединение в виде состояния React
`src/components/softphone.tsx`	Набор: страна или `@lid`, форматирование, клавиатура
`src/common/address.ts`	Модель адреса — номер и `@lid` это альтернативы, и набирается ровно один из них
`src/components/incoming-call.tsx`	Окно входящего звонка
`src/pages/call.tsx`	Экран звонка: собеседник, таймер, индикаторы, отключение микрофона, отбой
`src/hooks/useVoip.ts`	Потоки и проигрывающие их аудиоэлементы, связанные в обе стороны
`src/voip/ringing.ts`	Гудки дозвона и рингтон

Три вещи, которые легко сделать неправильно#

Они не очевидны по API, и каждая ошибка тихая — ничего не падает, просто не работает.

Сначала сигнализация, потом звук. dial() или accept() должны завершиться до startAudioBridge(): предложение о передаче звука, не относящееся ни к какому звонку, сервер отклоняет.
Звук поднимается раньше, чем появляется экран звонка. К моменту, когда аудиоэлементы отрисованы, события local-stream-ready и remote-stream-ready уже отработали. Поэтому пример запоминает потоки, а не только подписывается на события — иначе звонок будет беззвучным. То же и со статусом связи: подписка после уже случившегося connect оставила бы приложение с надписью «нет связи» при полностью живом соединении.
Отключение микрофона локальное, и его надо восстанавливать. Трек из local-stream-ready — тот самый, что передаётся собеседнику, поэтому track.enabled = false и есть то, что он перестаёт слышать. После обрыва соединения посреди звонка библиотека поднимает звук заново с новым микрофоном и сам звонок не завершает, поэтому отключение нужно перенести на новый трек — иначе экран продолжит утверждать то, чего уже нет.

Подробнее об этом — в разделах Передача звука и Как создать исходящий вызов.

Сторонние библиотеки#

У самой библиотеки зависимостей времени выполнения нет. React-клиент использует React, Redux Toolkit, React Router, Ant Design, иконки MUI и libphonenumber-js.