В отличие от двух моих предыдущих сообщений, речь идет не о веб-сайте, который я создал, а об API, о котором я узнал во время Hacktoberfest.

Если вы не знаете, что такое Хактоберфест, то в этом месяце, как вы уже догадались, в октябре мы отмечаем долгое празднование открытого исходного кода. Несмотря на то, что я начал поздно, это, вероятно, было одним из лучших впечатлений, которые у меня были до сих пор. Взаимодействие с сообществом в Discord, присоединение к ним на стримах Twitch и многое другое. Одним из спонсоров Хактоберфеста выступила компания Vonage. Компания, о которой я никогда раньше не слышал, но у нее, вероятно, одни из самых приятных и крутых сотрудников, разработчиков и сообщества. К сожалению, в октябре мне не удалось опробовать их продукт, хотя я и хотел.

Vonage - компания, которая создает множество коммуникационных API. Коммуникационный API позволяет вам легко добавлять сообщения или видеоконференцсвязь в свои приложения или упростить настройку двухфакторной аутентификации и сервисов, которые требуют от вас взаимодействия с помощью SMS, WhatsApp, Messenger и т. Д.

Через полторы недели после окончания Хактоберфеста я наконец нашел время, чтобы опробовать их API. Их веб-сайт, включая их документацию, вероятно, имеет лучший пользовательский интерфейс и лучший пользовательский интерфейс на любом веб-сайте, который я посещал, это просто так! У них также есть много хороших руководств на их сайте, но я все равно пишу это.

Что мы будем строить

Если вы думали, что мы собираемся создать какого-нибудь крутого бота, в котором задействована обработка естественного языка, извините, что разочаровал вас, потому что все, что мы будем делать, - это создавать простой веб-перехватчик, который отвечает «привет», когда вы говорите «привет» ! » в WhatsApp, Facebook Messenger или любых других сервисах, поддерживаемых API сообщений, и протестируйте его с помощью так называемого ngrok. Мы будем создавать приложение, используя node и express.

Создать учетную запись Vonage

Прежде чем писать какой-либо код, нам нужно создать учетную запись на Vonage. Для этого вы регистрируетесь на странице https://dashboard.nexmo.com/sign-up, кредитная карта не требуется. Вы также получаете кредит на 2 евро, но не волнуйтесь, сегодня мы не потратим ни одного из этих кредитов.

Но прежде чем мы начнем, что такое Vonage Messages API?

API сообщений позволяет отправлять и в некоторых случаях получать сообщения через SMS, MMS, Facebook Messenger, Viber и WhatsApp.

Создание веб-перехватчиков

Что такое веб-перехватчики? Короче говоря, веб-перехватчики - это обратные вызовы событий, которые происходят в каком-то другом приложении или другой части того же приложения. Веб-перехватчик срабатывает всякий раз, когда происходит определенное событие или действие. В нашем случае веб-перехватчик, который мы будем создавать, будет запускаться Vonage всякий раз, когда сообщение отправляется на соответствующую платформу, которую мы выбираем. Сейчас это может показаться запутанным, но потерпите меня до конца.

Начальная настройка

Давайте создадим папку с именем hello-vonage и запустим в ней npm init -y, поскольку мы будем использовать узел. Как только это будет сделано, давайте установим expressиbody-parse промежуточное ПО, чтобы легко прочитать текст запроса, запустив npm install express body-parser. При желании вы также можете использовать Typescript, но в данном случае это не имеет большого значения.

После того, как у нас все установлено, мы можем продолжить и настроить наше экспресс-приложение, создав app.js с помощью приведенного ниже кода.

Сам веб-перехватчик

API сообщений Vonage требует, чтобы мы открыли два веб-перехватчика, один как обратный вызов для любых полученных сообщений или веб-перехватчика входящего сообщения, а другой, который является обратным вызовом для обновлений статуса отправленного сообщения или веб-перехватчика статуса сообщения. Пример того, когда вызывается веб-перехватчик состояния сообщения, - это когда сообщение, которое вы отправили с помощью API, доставляется пользователю или читается им.

Сначала входящий веб-перехватчик.

Здесь мы указываем, что входящий веб-перехватчик находится на webhooks/inbound и обрабатывается функцией handleInbound. А пока давайте просто console.log тело запроса. API сообщений Vonage также требует, чтобы мы всегда отправляли 200 каждый раз, когда запрос отправляется веб-перехватчикам, и это именно то, что мы делаем.

Далее статус webhook.

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

На данный момент вашему app.js должно понравиться что-то вроде этого

Чтобы протестировать наши веб-перехватчики, мы будем использовать два инструмента, а именно песочницу Vonage и еще один инструмент под названием ngrok.

Тестирование с ngrok

Чтобы протестировать наши веб-перехватчики, он должен быть доступен через URL-адрес для Vonage, и единственный способ сделать это - открыть доступ к нашему серверу узла в Интернет. Но мы не можем просто подключить наш компьютер к Интернету, не так ли? Здесь на помощь приходит инструмент под названием ngrok. Ngrok генерирует одноразовый общедоступный URL-адрес и направляет этот URL-адрес на порт на вашем локальном сервере.

Чтобы начать работу, перейдите на https://ngrok.com и создайте учетную запись. После создания учетной записи вы должны быть перенаправлены на панель управления, откуда должны быть показаны инструкции по установке и настройке ngrok (это, вероятно, займет 2–3 минуты).

Хорошо, теперь, когда мы настроили ngrok, давайте запустим наш сервер узла, выполнив node app.js, и запустим ngrok, запустив ngrok http 3000. Эта команда просто сообщает ngrok, что нужно создать URL-адрес и направить его на порт 3000 на localhost. Ngrok должен сгенерировать и отобразить общедоступный URL-адрес, который должен выглядеть примерно как https://asdfas23as.ngrok.io. Он может показать вам два разных URL-адреса, один с http и один https, вы можете использовать любой, поскольку это только для тестирования, но я предлагаю вам в любом случае использовать https URL.

Это означает, что мы можем получить доступ к http://localhost:3000/webhooks/inbound из https://1f34b279009.ngrok.io/webhooks/inbound. Я знаю, это круто, правда ?!

Создание песочницы

Песочница - это просто место для тестирования нашего приложения. В данном случае это WhatsApp, Facebook Messenger или Viber. Мы просто сделаем песочницу в WhatsApp, потому что я не использую другие, но процесс должен быть таким же, если вы хотите попробовать их.

Чтобы создать песочницу, перейдите в Панель управления Vonage в раздел Сообщения и отправка и щелкните песочницу. В разделе WhatsApp нажмите Добавить в песочницу.

Помните, что маршрут для ловушки входящего сообщения - /webhooks/inbound, а для ловушки статуса - /webhooks/status. Прокрутите вниз и вы увидите раздел под названием Webhooks. В текстовом поле рядом с Inbound введите URL https://<your-ngrok-generated-url>/webhooks/inbound и в поле Status https://<your-ngrok-generated-url>/webhooks/status. Нажмите «Сохранить веб-перехватчики», и мы должны быть готовы к тестированию нашего приложения.

Вы должны увидеть инструкции в разделе WhatsApp о том, как начать работу с песочницей. Идите вперед и отправьте сообщение на номер, указанный в разделе, и следите за окном терминала, в котором работает ваше приложение узла. Вы должны получить ответ примерно так

{
  message_uuid: 'asdfasfd-asdf-adsf-adfs-asdfasdfasd',
  from: { type: 'whatsapp', number: '00000000000' },
  to: { type: 'whatsapp', number: '000000000000' },
  message: { content: { type: 'text', text: 'Hi' } },
  timestamp: '2020-11-14T19:48:24.688Z'
}

Вы можете продолжить и изучить все свойства, которые находятся в теле запроса.

Примечание. Каждый раз, когда вы перезапускаете ngrok, создается новый URL. Поэтому не забудьте обновить URL-адрес Webhooks на странице песочницы.

Отправка ответа

Наконец-то пришло время отправить ответ. Мы отправим POST-запрос с использованием axios в Vonage Messages API, чтобы отправить ответ на текстовое сообщение, только что полученное нашим веб-перехватчиком.

Настроить аутентификацию

Прежде чем мы продолжим, Vonage необходимо знать, что это мы отправляем запрос к их API, и для этого нам необходимо предоставить учетные данные. По соображениям безопасности и в качестве наилучшей практики учетные данные никогда не следует напрямую вставлять в код. Мы будем хранить учетные данные в переменных среды в файле .env.

// .env
VONAGE_NUMBER=<your-vonage-number>
VONAGE_API_KEY=<your-vonage-api-key>
VONAGE_API_SECRET=<your-vonage-api-secret>

Вы можете получить свой ключ API и секрет API из Панели управления Vonage, а Vonage Number - это номер вашей песочницы, который вы можете найти в разделе WhatsApp по адресу https://dashboard.nexmo.com/messages/sandbox.

Dotenv - это библиотека, которая читает .env файл и делает его доступным для узлового приложения. Чтобы установить dotenv, сначала установите его, запустив npm install dotenv, а затем добавьте require("dotenv").config() в начало app.js. Доступ к переменным среды в узле осуществляется с помощью process.env. Теперь мы можем получить доступ к нашему ключу API в узле с помощью process.env.VONAGE_API_KEY и секрету API с помощью process.env.VONAGE_API_SECRET.

Axios

Мы будем использовать axios, чтобы упростить отправку запросов к Messages API. Для начала сначала установите axios, запустив npm install axios. Затем давайте создадим функцию, которая принимает число, которое принимает номер для отправки сообщения и само сообщение в качестве аргументов, и отправляет запрос в API с соответствующими параметрами.

  • https://messages-sandbox.nexmo.com/v0.1/messages - это URL-адрес, по которому мы можем отправлять запросы к Messages API.
  • Второй параметр принимает объект Javascript, который отправляется как тело запроса. Здесь мы указываем информацию, необходимую API сообщений для отправки сообщения.
    * В разделе from параметр type - это платформа, на которую отправлено сообщение, а число - это номер, который использует песочница. Это тот же номер, который вы использовали при отправке сообщения.
    * Раздел "Кому" содержит информацию о получателе сообщения, в данном случае это человек, который отправил сообщение в песочнице.
    * Под полем В разделе message мы указываем информацию о содержании самого сообщения. Тип сообщения будет текстовым, поскольку мы собираемся отправить просто текстовое сообщение.
  • Третий параметр в axios - дополнительные параметры. Мы можем напрямую предоставить наши учетные данные с помощью параметра auth. Имя пользователя и пароль будут ключом Vonage API, т. Е. process.env.VONAGE_API_KEY, и секретом API Vonage, т. Е. process.env.VONAGE_API_SECRET соответственно.

Отправить ответ

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

Все, что мы делаем, это получаем номер пользователя, отправившего сообщение, и его содержание, а также проверяем, написано ли сообщение привет и отправлено ли сообщение обратно на тот же номер.

Вот и все, готово! Вы можете перезапустить сервер узла (перезапускать ngrok не обязательно) и опробовать его на себе. Вы можете добавить любую логику, добавить любое количество операторов if, которые вам нравятся, и настроить ее по своему усмотрению.

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

В итоге наш app.js должен выглядеть примерно так.

Что дальше

  • Прямо сейчас наш веб-перехватчик открыт для всего Интернета. Нам нужен способ убедиться, что только API сообщений Vonage может получить доступ к конечной точке. Это достигается с помощью токенов JWT. Вы можете прочитать об этом подробнее на https://developer.nexmo.com/messages/concepts/signed-webhooks.
  • Попробуйте изменить функцию sendWhatsappMessage, чтобы можно было отправлять сообщения в Messenger, или даже включить другие типы сообщений, например о местоположении.
  • Изучите Документы Vonage и создайте что-нибудь потрясающее!