Что такое WhatsApp API?

Мессенджеры *Разработка под Android *API *CRM-системы * Приветствую! Нарисовалась у меня задача: нужно интегрировать в CRM систему мессенджеры, а то трудно анализировать работу менеджеров, когда они общаются с клиентами используя один общий «рабочий» телефон. И первым делом нужно было подключить WhatsApp, как один из самых популярных мессенджеров у нашей целевой аудитории.

Анализ ситуации…

Казалось, требуется всего лишь отправлять и принимать сообщения. А столько подводных камней…

1. Официальный API

Официального API в релизе тогда ещё не было. Но Facebook успел прислать ссылку на форму, для подключения официального API, находящегося в тестировании.

2. Сторонний сервис. Подключение через WhatsApp WEB

Рассматривал вариант «серого» способа, использование неофициального сервиса, который отправляет сообщения через WEB интерфейс, подключается сканированием QR кода. Но это зависимость от чужого API, в любой момент может всё отвалиться, да и передавать чужому сервису номера клиентов не хотелось. А ещё писать под чужой авторский API, да ещё который придётся переписывать, при переезде на другой сервис, тоже такое себе удовольствие. Ну и ещё требуется держать телефон включенным (хотя некоторые сервисы за доп плату решали эту проблему 🙂

3. Ручной режим

Посадить человека, пускай копипастит сообщения клиентам. Шутки шутками, а из этой идеи родилось решение!

Решение

Отправка сообщения

Есть такая программка для автоматизации действий под Android, называется Tasker, одна из первых подобных программ. Но я в ней не разобрался с первого раза… Поискал аналоги, наткнулся на программу Automagic. В ней события, действия и ветвления рисуются как блок схема. Оффтоп Передаю привет конструктору HiAsm, благодаря которому когда то научился понимать концепцию программирования. И вот в ней я то и придумал решение, root права нам не нужны. Получилось методом научного тыка нарисовать скрипт отправки сообщения, далее буду называть поток, так именуется каждый отдельный нарисованный алгоритм в данной программе. А теперь разберём его работу: Скриншот потока отправки сообщения в WhatsApp

1. Каждые 5 секунд периодичным таймером генерируется событие и передаётся следующему блоку.
2. Блок HTTP Request спрашивает у сервера, есть ли в очереди следующее сообщение, которое нужно отправить? Бэкенд написан на PHP.
3. Парсим ответ сервера JSON.
4. Если от сервера в ответе пришла метка, что нужно отправить сообщение, идём дальше.
5. Проверяем, включен ли экран устройства, если нет, отправляем уведомление, с целью разбудить телефон. Если же экран включен, и не выполняется другой поток, проверяющий статус, доставлено ли сообщение, то:
6. Генерируем ссылку и открываем её, что бы инициировать диалог с полученным от сервера номером телефона в WhatsApp’е
7. Самое интересное. Блок Control UI. В нём в виде кода реализована логика проверки успешности открытия чата (проверка регистрации в мессенджере), вставка текста в окно ввода и клацанье по кнопке Отправить. Код писал с мобильного, как заработал, больше не трогал

   sleep(2000);  // 2 секунды на запуск вацапа   sle = 200; ch_c = 0; ch = false; is_sended = false;   sleep(sle); ch = existsElementById("com.whatsapp:id/entry"); // Проверяем, появилась ли на экране кнопка отправить sleep(sle); if (ch == false) {   ch = existsElementById("com.whatsapp:id/entry"); // Снова проверяем   ch_c = ch_c + 1;   sleep(1500); }  if (ch == false) {   ch = existsElementById("com.whatsapp:id/entry");    ch_c = ch_c + 1;   sleep(5500); }  ch = existsElementById("com.whatsapp:id/entry"); sleep(sle); setText2ById("com.whatsapp:id/entry",text); // Вставляем сообщение sleep(sle);  clickById("com.whatsapp:id/send");  // Жмём кнопку отправить sleep(sle); back(); sleep(sle); back(); status = 2;  if(ch == true) {  // Если всё хорошо, запоминаем, для отправки на сервер   is_sended = true;   status = 1; } 

8. Отправляем результаты отправки сообщения на сервер.
9. Возвращаемся на домашний экран.

Приём сообщений

Принимать сообщения на много проще. Ставим событие на уведомление от мессенджера. Как только приходит уведомление, помечаем его прочитанным, и отправляем его на сервер как есть. Тот уже спарсит адресата и текст. Скриншот алгоритма приёма сообщений

Плюсы, минусы, доработка и планы

Основную функцию отправки сообщения алгоритм выполняет отлично. Так как не используется WEB интерфейс, схватить баню от мессенджера тут меньше рисков, как мне кажется. Арендовал слабенький виртуальный сервер, установил туда Android и перенёс всё. На отправку одного сообщения новому контакту уходит ~5 сек. Для проверки доставки и прочтения сообщения, разработал отдельный поток, но он в черновом варианте и иногда не срабатывает. Поэтому о нём позже. В данный момент не реализована функция приёма медиа сообщений (фото, аудио, вложения), но это можно выгружать из WhatsApp, используя кнопку поделиться сообщением в будущем. Чуть позже хочу сверху виртуальной машины, где запущен мессенджер, написать SIP транк, через который можно будет звонить через WhatsApp как через SIP ^.^ что может сэкономить расходы на связь. Ещё хочу делать скриншоты аватарок и отправлять их на сервер, для прикрепления миниатюры к контакту в CRM системе. Ну и вообще самое интересное: Данный способ обёртывания в API подойдёт почти для любого приложения под Android 🙂 Всё изначально разрабатывал и запускал на Android 9, xiaomi mi 9 se, root прав нет. UPD: Пример на Python3.8 в качестве бекенда доступен на GitHub, доработан алгоритм ловли уведомлений и код отправки из комментариев от Скрин из примера Только зарегистрированные пользователи могут участвовать в опросе. Войдите, пожалуйста. Если используете отправку из WhatsApp, то какой API? 31.03% Официальный API 18 29.31% Через WhatsApp WEB (QR код) 17 24.14% Отправляю вручную 14 15.52% Придумал своё 9 Проголосовали 58 пользователей. Воздержались 73 пользователя.

Что такое API Вотсап?

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

В мессенджере Ватсап Апи предоставляется возможность интеграции опции автоматической пересылки сообщений в программное обеспечение или сетевой ресурс. Официально разработчики мессенджера никакой поддержки в такой сфере и использовании программы в подобных целях не оказывают, даже выступают против стороннего программного обеспечения. Это объясняется стремлением обеспечить заявленный высокий уровень защищенности мессенджера и переписок.

Но в любом случае область таких разработок процветает и в сети есть множество программных средств для организации этого процесса. На текущий момент особой популярностью пользуется WhatsMate.

Встраивание Апи происходит не напрямую в приложении мессенджера, в при помощи серверов программных средств ВатсМэйт, которые представляют собой третье независимое лицо.  Для работы с инструментами Апи необходимо обладать специальными знаниями в программировании на популярных языках пхп и питон.

WhatsApp Business API

Базнес Ватсап апи предоставляет уникальную возможность для компаний разного уровня в целях коммуникации с клиентами на мировом уровне. Все связи защищены и используются только простые и надежные методы.

Возможности:

• Создание «Профиля компании», который будет содержать подробные сведения об организации, полезной для клиентов: шапку-фото, фактический адрес, описание, контактную информацию и адрес веб-сайта.
• Эффективная организация коммуникации с клиентами. Благодаря качественным инструментам для общения Вы можете оправлять данные в удобном для просмотра виде и месте, есть возможность отвечать на сомнения и вопросы покупателей, осуществлять всестороннюю поддержку.

API для разработки бота для Ватсап на php и python

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

Бот может работать круглосуточно и при этом ему не требуется платить заработную плату. Максимально быстро (в течение 2-3 минут) приходит автоматический ответ из чата компании, при условии, что проблема стандартизированная. В случае, когда вопрос охватывает сверх базового функционала опросника, то бот предложит перезвонить удобным способом: самостоятельно оператору по единому номеру или указать свой мобильный телефон и время. Все вопросы и ответы автоматически архивируются и благодаря этому можно контролировать работу, совершенствовать ответы, расширять функционал.

Весь размещенный контент не является официальными и не подтвержден разработчиками Ватсапа. Рекомендации и помощь по разным сферам решения вопроса есть в специальных профильных темах на ГитХаб.

Проекты на Github (дать несколько ссылок на темы с сайта github.com):

• com/tgalal/yowsup;
• ru/programming/php/whatsapp-api-the-library-works-with-messenger/;
• com/mgp25/Chat-API.

Whatsapp шлюз что это и список сервисов

Шлюз – это программное средство, которое помогает осуществлять отправку сообщений в приложении при помощи коммуникации Ватсап со сторонними ресурсами.

Для установки Апи требуется наличие шлюза, обеспечивающего взаимодействие приложения с внешними ресурсами. Делается это следующим образом:

• Разрабатывается базовая форма, предназначенная для заполнения пользователем, чтобы бот в дальнейшем мог обработать информацию.
• Необходимо предусмотреть обязательный ввод контактов, чтобы иметь возможность в дальнейшем связаться с клиентом.
• Можно осуществить одноразовую или регулярную рассылку.

Официальные ресурсы мессенджера не планируют публиковать руководство по настройке и использованию этих сервисов и организации взаимодействия.

Список популярных сервисов для создания бота:

• API Bot.
• chat-api.com.
• com.
• api-messenger.com.

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

Разработанный создателями как один из инструментов информационной поддержки бизнеса, WhatsApp API появился на рынке 1 августа 2018 г. Whatsapp сегодня — это приложение с 1,7 млрд активных пользователей в месяц. В день через мессенджер отправляется до 70 млрд сообщений. Доступ к такой аудитории и возможность встраивания массовых рассылок в любое программное обеспечение создают новые условия для продвижения бренда или компании.

В чем ценность «Ватсап АПИ» для бизнеса

Использование шлюза API, обеспечивающего взаимодействие с внешними ресурсами, позволяет:

• донести до клиентов сведения о компании: сфере ее деятельности, возможностях сервиса, адресе и контактных данных;
• организовать скоростную систему коммуникации;
• оперативно доносить до клиентов информацию;
• осуществлять поддержку по устранению проблем и вопросов, возникающих на любом этапе осуществления сделки (от предварительного знакомства до операций по оплате и доставке товара или услуги);
• создавать шаблоны для скоростной отправки HSM;
• отслеживать статистические данные для определения бизнес-результатов.

Показатель вовлеченности аудитории — почти 100% читаемость, в 40% случаев абоненты отвечают на присланные сообщения. Это создает условия, при которых бизнес сможет охватить максимально расширенную клиентскую базу.

Какой номер можно подключить

Для осуществления официальных уведомлений к каждому бизнес-аккаунту WhatsApp должен быть привязан один из двух номеров:

1. Городской, с кодом (например, +7(495), при подключении которого необходимо произвести звонок от «Ватсап» для настройки аккаунта.
2. Мобильный любого оператора (например, +7(928).

Бесплатные номера с кодировкой 8 (800) для подключения недоступны, т. к. без идентификационного кода страны не могут распознаваться системой. Не получится присоединить и уже использующийся номер телефона. Для интеграции API требуется аккаунт, который не был задействован ранее или не активировался в мессенджере последние 6 мес.

Как получить доступ к WhatsApp Business API

Для интеграции в мессенджер необходимо подать заявку с указанием целей использования API и предполагаемого количества сообщений в день. Подключение возможно только после одобрения WhatsApp, но пока сервис работает в тестовом режиме, к компаниям, претендующим на верификацию аккаунта, предъявляются крайне жесткие требования.

Шанс подключиться имеют только:

• большие компании и бренды, зарекомендовавшие себя на мировом уровне;
• платформы CRM, занимающиеся разработкой решений для бизнеса (в России таковыми являются Infobip, Nexmo, Zendesk). Textback, также имеющая в РФ официальные права на подключение API для WhatsApp, не делает этого напрямую, а пользуется услугами партнерских организаций.

Доступ возможен только после верификации (подтверждения) бизнес-аккаунта.

Могут ли заблокировать аккаунт

Блокировка аккаунта осуществляется сразу же, как только обнаруживается нарушение пользователем установленных разработчиками правил. Сюда относится рассылка рекламного контента и промо-сообщений. Политика руководителей «Ватсап» направлена против спама в информационном пространстве приложения, и это строго отслеживается администрацией и сервисом технической поддержки. Определяется нарушение по уровню пользовательских блокировок. Если он постоянно выше средне допустимого или резко подскакивает до пиковых значений, то это повод к проверке.

Агрессивность и навязчивость сервиса тоже могут трактоваться как скрытая реклама и привести к блокировке аккаунта. Кроме того, забанить могут и за обращение для интеграции API к неофициальным платформам. Использование продукта сторонней компании идет вразрез с правилами «Ватсапа», и уличенные в злоупотреблении автоматически наказываются.

Какие сообщения можно отправлять и что они могут содержать

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

Содержание HSM ограничивается рассылкой:

• триггерных и системных сообщений в чаты «Ватсапа»;
• уведомлений о ходе выполнения операции или активирования услуги;
• статусов доставки товара;
• сообщений об оплате;
• извещений о скидках, акциях и ожидаемых событиях в компании;
• напоминаний о записи на прием, бронировании и т.п.

Во всех случаях обязательно согласование шаблонов. Могут применяться такие переменные, как время, дата, форма чека оплаты, ее способы и т.д. Текст может подвергаться форматированию (классический шрифт, жирный, зачеркнутый, курсив).

Сколько сообщений в секунду можно отправлять

Существующий сегодня в «Ватсапе» лимит на отправку составляет 15 HSM в сек.

Сколько будут стоить рассылки

Использование Апи — услуга, требующая оплаты. Но пока ее стоимость не обозначена, а цены складываются из затрат на передачу сообщений (в каждой стране разные тарифы) и правил общения, принятых в «Ватсапе». Согласно им, если клиент обратился к компании первым, то она имеет коридор в 24 часа, в течение которых может отсылать интересующую информацию, отвечать на вопросы, оказывать техподдержку бесплатно. Если же инициатором диалога выступает бизнес-аккаунт — каждое SMS оплачивается в соответствии с существующими тарифами.

Прогнозы Reuters для России колеблются в пределах 0,3-5,6 руб. за одно HSM, что зависит от количества единовременно рассылаемых уведомлений. Возможно, на ценообразование будут влиять и еще какие-то факторы, но пока они не озвучены.

Как подписать клиента и отправить рассылку

Прежде чем отправлять потенциальным клиентам сообщения, бизнес-аккаунт обязан выполнить главное правило — получить официальное согласие пользователя на такое сотрудничество в «Ватсапе». Это указывается в оговоренной с представителями сервиса форме на сайте, в e-mail или SMS.

Рассылка может осуществляться по клиентам, обращавшимся в службу поддержки компании, но только в том случае, если в диалоге они дали на это свое согласие. Количество пользователей разрешается увеличивать с помощью SMS, писем на электронную почту и др. При этом WhatsApp допускается указывать в качестве информационного канала.

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

Как должна выглядеть подписка для пользователя

Форма, помимо личных и контактных пользовательских данных, интересующих компанию, обязательно должна иметь разъяснение, что получит клиент в результате подписки. Ему должна быть предоставлена возможность самому выбирать типы уведомлений, которые он хотел бы получать в «Ватсапе». А также в форме должна присутствовать информация о недопустимости рекламных акций и соответствии соглашения требованиям мессенджера.

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

Как разместить на сайте кнопку обратной связи через WhatsApp

Для упрощенного обращения пользователя в техподдержку «Ватсапа» рекомендуется на странице создать кнопку «Прямой связи». Это функция, которая в один клик позволяет создать ссылку, автоматически открывающую чат с нужным человеком. Она работает и на телефоне, и в WhatsApp Web. Иногда используется виджет, имеющий кнопку подписки на рассылку.

Отправка¶

Для отправки WhatsApp-сообщения необходимо вызвать POST /whatsapp/messages, передавая в теле параметры сообщения с указанием данных авторизации в заголовке.

Параметры запроса¶

Параметр	Тип данных	Описание
from	string
to	string	Номер телефона в международном формате (без +).
text (optional)	string
validity (optional)	integer
contentUrl (optional)	string	URL контента. Любой валидный URL со схемой HTTP или HTTPS.
contentName (optional)	string
contentType (optional)	string	MIME Type контента. Существующий MIME Type.
callbackUrl (optional)	string	URL, на который система будет отправлять уведомления об изменениях статуса сообщения. Любой валидный URL со схемой HTTP или HTTPS.
callbackData (optional)	string	Данные, которые будут указаны в коллбэке со статусом сообщения.
templateId (optional)	string	ID шаблона в системе поставщика.
templateParams (optional)	object	Набор параметров для заполнения по шаблону, где ключ – номер позиции значения. Пример: { "1": "value1", "2": "value2" } Внимание! В значении нельзя использовать: переносы строки, табуляцию и 4 пробела подряд.
languageCode (optional)	string	Код языка, по умолчанию EN.

MIME Type¶

Медиа	Расширения файлов	Ограничения размера	Комментарий
audio	16Mb	codecs=opus
document	любой валидный MIME Type	100 Mb
image	16 Mb	GIF-изображения будут автоматически преобразованы в MP4-видео на стороне WhatsApp.
video	5 Mb	Поддерживаются только H.264 и AAC видео-кодеки.
voice	auidio/ogg	.ogg	16 Mb

Пример запроса¶

 curl -X POST   -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ=='   -H 'Content-Type: application/json'   -d '{      "messages": [          {              "from": "MyCompany",             "to": "79034567890",             "text": "Code: 1234"         },         {           "from":"MyCompany",           "to":"79034567888",           "templateId": "account_activated",           "templateParams":{             "1": "+7(495) 646 00 54",             "2": "https://devino.online"           },           "languageCode": "ru",           "validity":86400,           "callbackUrl":"https://test_callback_url.site"         }             ] }' https://api.devino.online/whatsapp/messages 

Параметры ответа¶

Параметр	Тип данных	Описание
code	string	Указывает на результат обработки сообщения. 1. OK – успешно обработано. 2. REJECTED – произошла ошибка во время обработки запроса.
reasons (optional)	array[string, string]	Массив ошибок, произошедших во время обработки сообщения. Указывается только при "code": "REJECTED".
reasons.key	string	Код ошибки.
reasons.ref (optional)	string	Ссылка на параметр, в котором произошла ошибка.
messageId (optional)	string	ID сообщения. Указывается только при "code": "OK".
description (optional)	string	Описание ошибки. Указывается только при "code": "REJECTED".

Пример ответа¶

 {   "result": [   {   "code": "OK",   "messageId": "3482512350952730368"   },   {   "code": "OK",   "messageId": "3482512350952730369"   }   ]  }  

Коды ошибок¶

Key	Ref	Описание
billing.error	Необходима оплата.
forbidden	Отправка запрещена.
unknown	Неизвестная ошибка.
invalid	messages[i].to	Неправильно указан номер телефона.
invalid	messages[i].validity	Неправильно указан срок жизни сообщения.
invalid	messages[i].callbackUrl	Неправильно указан URL.
invalid	messages[i].contentUrl	Неправильно указан URL контента.
invalid	messages[i].contentType	Неправильно указан тип контента.
invalid	messages[i].from	Неправильно указан отправитель.
invalid	messages[i].languageCode	Неправильно указан код языка.
length.too.long	messages[i].to	Превышена максимальная длина номера телефона.
length.too.long	messages[i].text	Превышена максимальная длина текста сообщения.
length.too.long	messages[i].languageCode	Слишком длинный код языка.
length.too.short	messages[i].contentName	Слишком короткое название контента.
length.too.short	messages[i].languageCode	Слишком короткий код языка.
must.be.not.null	messages[i].to	Получатель не указан.
must.be.not.null	messages	Массив messages не может быть пустым.
must.be.not.null	messages[i].from	Отправитель не указан.
must.be.not.null	messages[i]	Поле текста и контента не указано.
not.available	messages[i].from	Некорректный адрес отправителя.
too.many.messages	messages	Превышен максимальный размер массива messages.

Webhooks¶

Получение статуса¶

Для получения статусов WhatsApp-сообщений необходимо при отсылке сообщения методом POST /whatsapp/messages указать параметр callbackUrl.

Параметры¶

Параметр	Тип данных	Описание
messageId	long	ID сообщения.
ts	long	Время получения статуса (timestamp) в миллисекундах.
status	string	Статус сообщения.
errorCode	integer	Код ошибки.
ip	string	IP-адрес пользователя.
browser	string	Браузера пользователя.
os	string	Операционная система пользователя.
userAgent	string	Заголовок запроса User-Agent.
options	string	Данные, которые были указаны в callbackData при отправке запроса.

Пример¶

 [   {   "messageId": 1,   "ts": 0,   "status": "DELIVERED",   "errorCode": 0,   "ip": "127.0.0.1",   "browser": "string",   "os": "string",   "userAgent": "string",   "options": "string"   }  ]  

Коды ошибок¶

Код	Описание
2000	Не определен оператор получателя.
2001	Отклонено как спам.
2002-2004	Ошибка тарификации.
2005	Недостаточно средств.
2006-2008	Ошибка тарификации.
2009	Отклонено как дубликат.
2010, 2011	Исткело время жизни.
2012	Ошибка тарификации.
2017	Отклонено как спам.
2300	Превышен лимит длины текста сообщения.
2301	За короткий промежуток времени было отправлено слишком много сообщений. Повторите отправку.
2302	Отклонено как спам.
2303	Указанный MIME Type не поддерживается или изображение слишком большое (более или равно 5 МБ).
2304	Превышен лимит длины текста сообщения.
2305	Пользователь не использовал или более не использует WhatsApp.
2307	Возникает при попытке отправить сообщение на номер телефона бизнес-аккаунта, с которого производится отправка.
2308	Количество указанных параметров шаблона не соответствует их ожидаемому количеству.
2309, 2310	Шаблон не существует для указанного языка или локали.
2311	Превышение длины параметра шаблона.
2312	Сообщение отправлено вне диалога и без указания шаблона.
2313	Неизвестная ошибка.

Получение входящих сообщений¶

Внимание

Для получения входящих WhatsApp-сообщений необходимо:

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

Параметры¶

Параметр	Тип данных	Описание
incomingMessageId	long	ID сообщения.
to	string	Адрес получателя.
from	string	Адрес отправителя.
ts	long	Время получения сообщения (timestamp) в миллисекундах.
text (optional)	string	Текст сообщения.
contentUrl (optional)	string	URL контента в сообщении.
contentType (optional)	string	Тип контента в сообщении.
contentName (optional)	string	Имя контента в сообщении.
profileName (optional)	string	Имя профиля отправителя.
whatsAppGeoLocation (optional)	WhatsAppGeolocation	Геопозиция, отправленная пользователем.
whatsAppContacts (optional)	List[WhatsAppContact]	Список контактов, отправленных пользователем.

WhatsAppGeolocation¶

Информация

Входящие сообщения с текущими геоданными в настоящее время не поддерживаются.

Параметр	Тип данных	Описание
latitude	double	Широта.
longitude	double	Долгота.
address	string	Адрес, по которому находится пользователь.
addressName	string	Название адреса пользователя.
addressurl	string	URL, откуда пользователь получил свои геоданные.

WhatsAppContact¶

Информация

Все элемены array (массивов) имеют тип данных string.

Параметр	Тип данных	Описание
addresses	array	Полные адреса контакта. Каждый адрес может содержать поля street, city, state, zip, country, countryCode и type.
birthday	string	День рождения контакта в формате YYYY-MM-DD.
emails	array	Email-адреса. Каждый адрес может содержать email и type.
contactName	array	Полное имя контакта. Каждый объект contactName может содержать поля firstName, middleName, lastName, formattedName, namePrefix и nameSuffix.
contactCompany	array	Информация о месте работы контакта. Каждый объект может содержать поля company, department и title.
phones	array	Номера телефонов контакта. Каждый объект может содержать поля phone, waId и type.
urls	array	URL контакта. Каждый объект может содержать поля url и type.

Пример¶

 {   "incomingMessageId": 0,   "to": "str",   "from": "str",   "text": "str",   "contentUrl": "str",   "contentType": "str",   "contentName": "str",   "profileName": "str",   "ts": 0  }  

API (программный интерфейс приложения) позволяет выполнять некоторые функции программы не нажимая кнопки, не вводя тексты, а отправляя специальные запросы к программе и получать на них ответы. Используя API можно делать автоматические рассылки сообщений из других программ, получать тексты и статусы сообщений, добавлять и обновлять контакты.

Далее описаны имеющиеся функции. Персональный токен (код) для подключения к API указан в разделе Настройки, доступный пользователям с ролью Администратор

👉 Отправка сообщений

Используйте GET-запрос, где номер телефона в международном формате (79001234567 и тп, но может содержать пробелы, скобки, тире и др) и текст в кодировке UTF-8 (может включать ссылки, смайлы). Для переноса текста на новую строку используйте в сообщении символы – %0A

При отправке по API нескольких сообщений, они выстраиваются в очередь отправки с интервалом от 5 до 12 сек (в случайном порядке) между сообщениями. Для тестовых аккаунтов есть ограничение – не более 30 отправленных сообщений по API в день.

Запрос GET: https://wamm.chat/api2/msg_to/токен/?phone=номер-телефона&text=текст-сообщения

Ответ при успехе: JSON: {"err":0,"msg_id":1хххххх}, где msg_id – номер сообщения

Ответ при ошибке: JSON: {"err":"phone fail"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• phone fail – ошибка в номере телефона
• no WhatsApp on the number – нет WhatsApp с таким номером
• phone not checked for WhatsApp, please retry – не проверен номер на наличие WhatsApp
• text fail – пустой текст
• text fail, more 1500 – текст слишком большой, превышает 1500 символов

👉 Получение статуса сообщения

Запрос GET: https://wamm.chat/api2/msg_state/токен/?msg_id=номер-сообщения

Ответ при успехе: JSON: {"err":0,"msg_data":{"msg_id":"1хххххх","phone":"79ххххххх","state":"viewed"}}

Ответ при ошибке: JSON: {"err":"msg_id fail"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• msg_id fail – ошибка в номере
• msg not be – не найден номер сообщения

👉 Проверить наличие WhatsApp по номеру телефона

Запрос GET: https://wamm.chat/api2/check_phone/токен/?phone=номер-телефона

Ответ при успехе: JSON: {"err":0,"result":"exists"} Варианты ответов:

• exists – есть WhatsApp на номере
• none – нет WhatsApp на номере

Ответ при ошибке: JSON: {"err":"fail execution", "result":"error"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• fail execution – ошибка проверки, стоит повторить

👉 Отправка файлов / картинок / документов

Используйте GET-запрос, где номер телефона в международном формате (79001234567 и тп, но может содержать пробелы, скобки, тире и др) и URL – публичная ссылка к файлу (доступная из Интернета, вида: https://wamm.chat/i/images/wamm-chat-logo.png).

При отправке по API нескольких сообщений, они выстраиваются в очередь отправки с интервалом от 5 до 12 сек (в случайном порядке) между сообщениями. Для тестовых аккаунтов есть ограничение – не более 30 отправленных сообщений по API в день.

Запрос GET: https://wamm.chat/api2/file_to/токен/?phone=номер-телефона&url=ссылка-на-файл

Ответ при успехе: JSON: {"err":0,"msg_id":1хххххх}, где msg_id – номер сообщения

Ответ при ошибке: JSON: {"err":"phone fail"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• phone fail – ошибка в номере телефона
• no WhatsApp on the number – нет WhatsApp с таким номером
• phone not checked for WhatsApp, please retry – не проверен номер на наличие WhatsApp
• url fail – пустая ссылка или в ней отсутствует http / https

👉 Получение статуса сообщения

Запрос GET: https://wamm.chat/api2/msg_state/токен/?msg_id=номер-сообщения

Ответ при успехе: JSON: {"err":0,"msg_data":{"msg_id":"1хххххх","phone":"79ххххххх","state":"viewed"}}

Ответ при ошибке: JSON: {"err":"msg_id fail"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• msg_id fail – ошибка в номере
• msg not be – не найден номер сообщения

👉 Получение сообщений

Этой функцией можно получить до 100 последних исходящих и входящих текстовых сообщений

Запрос GET: https://wamm.chat/api2/msg_get_last/токен/?col=кол-во(1-100)

В запросе также можно указать необязательный GET-параметр from_me=0 или from_me=1, который позволит вывести не все последние сообщения, а лишь отправленные (1) или полученные (0)

Ответ при успехе: JSON: {"err":0,"msg_data":[{"msg_id":"1xxxxxx","from_me":"1","phone":"79xxxxxxxxx","chat_name":"Олег Иванов","tip_msg":"textMessage","msg_text":"текст сообщения","msg_link":"URL","date_ins":"2021-01-24 19:52:00","date_upd":"2021-01-24 19:52:22","state":"delivered"},…….. }]} Описание переменных:

• msg_id – номер сообщения
• from_me – входящее (0) или исходящее (1) сообщение
• phone – номер телефона
• chat_name – имя контакта
• tip_msg – тип сообщения: текст – textMessage, file_link – файл/картинка/голосовое и т.п.
• msg_text – текст сообщения
• msg_link – ссылка на файл
• date_ins – дата отправки/получения
• state – статус сообщения (sending, viewed, received и другие)

Ответ при ошибке: JSON: {"err":"col fail or more 100"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• col fail or more 100 – ошибка в кол-ве или превышает 100
• msgs not be – не найдены сообщения

👉 Получение сообщений по номеру телефона

Этой функцией можно получить до 100 последних исходящих и входящих текстовых сообщений по конкретному номеру телефона

Запрос GET: https://wamm.chat/api2/msg_get/токен/?phone=телефон&col=кол-во(1-100)

Ответ при успехе: JSON: {"err":0,"msg_data":[{"msg_id":"1xxxxxx","from_me":"1","phone":"79xxxxxxxxx","chat_name":"Олег Иванов","tip_msg":"textMessage","msg_text":"текст сообщения","msg_link":"URL","date_ins":"2021-01-24 19:52:00","date_upd":"2021-01-24 19:52:22","state":"delivered"},…….. }]} Описание переменных:

• msg_id – номер сообщения
• from_me – входящее (0) или исходящее (1) сообщение
• phone – номер телефона
• chat_name – имя контакта
• tip_msg – тип сообщения: текст – textMessage, file_link – файл/картинка/голосовое и т.п.
• msg_text – текст сообщения
• msg_link – ссылка на файл
• date_ins – дата отправки/получения
• state – статус сообщения (sending, viewed, received и другие)

Ответ при ошибке: JSON: {"err":"col fail or more 100"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• col fail or more 100 – ошибка в кол-ве или превышает 100
• msgs not be – не найдены сообщения
• phone fail – ошибка в номере телефона

👉 Добавление и обновление контактов

Этот запрос добавляет контакт в WAMM.chat или обновляет имя, если существует.

Запрос GET: https://wamm.chat/api2/contact_to/токен/?phone=номер-телефона&name=имя контакта

Запрос GET: https://wamm.chat/api2/contact_to/токен/?phone=номер-телефона&name=имя контакта&info=Заметка, примечание к контакту&email=e-mail&web=URL

Где, параметры info, email, web – необязательные, их можно не отправлять в запросе

Ответ при успехе: JSON: {"err":0,"result":"insert"} или JSON: {"err":0,"result":"update"}

Ответ при ошибке: JSON: {"err":"phone fail"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• phone fail – ошибка в номере телефона
• no WhatsApp on the number – нет WhatsApp с таким номером
• phone not checked for WhatsApp, please retry – не проверен номер на наличие WhatsApp
• name fail – не указано имя
• name fail, more 250 – имя слишком большое, превышает 250 символов
• web fail, more 150 – URL слишком большое, превышает 150 символов
• email fail, more 150 – email слишком большое, превышает 150 символов

👉 Удаление контактов

Этот запрос удаляет контакт в WAMM.chat, при этом в WhatsApp на смартфоне он остаётся.

Запрос GET: https://wamm.chat/api2/contact_delete/токен/?phone=номер-телефона

Ответ при успехе: JSON: {"err":0,"result":"delete"}

Ответ при ошибке: JSON: {"err":"phone fail"} Варианты ошибок:

• token fail – ошибка в токене
• acc not authorized – подключение к WhatsApp не авторизовано
• phone fail – ошибка в номере телефона
• phone not found – не найден телефон в контактах

👉 Смайлы

Текст сообщения должен быть в UTF-8 и он позволяет вставить смайлы, как отдельные символы: 🤗💐😂🤩😭 и тд. Если вы используете системы, которые по тем или иным причинам не могут отправить смайлы, то можете использовать спецсимволы, которые будут заменены на смайлы:

🤗	:sm01:
💐	:sm02:
😂	:sm03:
🤩	:sm04:
😭	:sm05:
😤	:sm06:
🤝	:sm07:
😃	:sm08:
😉	:sm09:
😍	:sm10:
😘	:sm11:
😷	:sm12:
😕	:sm13:
🙏	:sm14:
👉	:sm15:
👍	:sm16:
💐	:sm17:
🔥	:sm18:
🕒	:sm19:
🎁	:sm20:
📺	:sm21:
☎	:sm22: