Please make sure you sign up with the same account with which you would like to create and maintain the app from. Transferring apps/wallet balance from one account to another in future would not be possible
By logging in, you are agreeing to the Terms of Service and the Privacy Policy.
Want to outsource bot development? We have partners to get it done. Click here to get in touch
На сегодняшний день более 1,5 миллиарда человек в более чем 180 странах используют приложение WhatsApp, чтобы оставаться на связи с друзьями и семьей - в любое время и в любом месте. Представители бизнеса по всему миру уже используют WhatsApp в неформальном режиме для общения с клиентами, будь то вопросы о продукте либо уведомления о транзакциях. WhatsApp Business - это новый способ для представителей бизнеса усовершенствовать контроль таких диалогов со своими клиентами, а также привлечь новых клиентов, которые также оценят быстрое, удобное и личное общение. Данное руководство описывает спецификации API по обмену сообщениями от компании Gupshup для приложения WhatsApp Business с целью отправки и получения сообщений на WhatsApp с помощью простого API REST через режимы HTTP/HTTPS.
Данное руководство предназначено для разработчиков и ИТ-персонала предприятий, которые планируют интегрировать свои системы с API для обмена сообщениями компании Gupshup. Также, данное руководство применимо для приложений, созданных после 28 января 2020 года на нашей платформе.
Чтобы подытожить то, что мы расскажем в этом руководстве:
Перед использованием API для обмена сообщениями от компании Gupshup, необходимо иметь следующие общие представления:
Входящие сообщения, отправленные клиентами на ваш номер телефона WhatsApp Business, будут направляться на ваш эндпоинт веб-хука по протоколу HTTP/HTTPS, т.е. клиент отправит текстовое сообщение или медиа-вложение в WhatsApp. Всякий раз, когда происходит такое триггерное событие, API для обмена сообщениями Gupshup регистрирует его и немедленно отправляет уведомление (HTTP POST запрос) на URL обратного вызова, заданный в настройках вашего приложения, указывая, когда вы получаете сообщение.
Смотрите изображение ниже, для определения местоположения опций обратного вызова. Если переключатель URL Обратного вызова ВЫКЛ.
Входящие сообщения отобразятся в поле
Входящие Сообщения | События. field.
Сообщения и события, записанные в этом поле, хранятся временно, то есть, если вы обновите страницу настроек приложения, журналы будут очищены.
Чтобы настроить обратный вызов, он должен соответствовать следующим требованиям:
1. В ответ должно прийти HTTP_SUCCESS (code: 2xx)
2. URL обратного вызова может быть общедоступным; при ограничении доступа необходимо внести IP адрес Gupshup в белый список.
3. URL обратного вызова должен принимать HTTP header: User-Agent
4. URL обратного вызова должен принимать пользовательское событие: sandbox-start
Тип | Описание | Пример |
---|---|---|
sandbox-start | Данное событие срабатывает, когда приложение находится в режиме Песочницы, и вы установили URL обратного вызова |
Content type: application/json {"app":"DemoApp","timestamp":1580142086287,"version":2,"type":"user-event","payload":{"phone":"callbackSetPhone","type":"sandbox-start"}} |
sandbox-start | Данное событие срабатывает, когда приложение находится в режиме Песочницы, и вы использовали прокси-бота Gupshup для вызова приложения с помощью команды Proxy {{App_Name}} |
Content type: application/json {"app":"DemoApp","timestamp":1580227393386,"version":2,"type":"user-event","payload":{"phone":"918x98xx21x4","type":"sandbox-start"}} |
Тип | Описание | Пример |
---|---|---|
enqueued | Сообщение успешно отправлено клиенту WhatsApp. |
Content type: application/json {"app":"DemoAPI","timestamp":1580546677791,"version":2,"type":"message-event""payload":{"id":"59f8db90-c37e-4408-90ab-cc54ef8246ad","type":"enqueued","destination":"91XX985XX10X","payload":{"whatsappMessageId":"gBEGkYaYVSEEAgkD7bRi9syGnBk","type":"session"}}} |
failed | Сообщение не было отправлено клиенту WhatsApp по причине, указанной в коде сбоя сообщения и в таблице причин. |
Content type: application/json {"app":"DemoAPI","timestamp":1580311136040,"version":2,"type":"message-event","payload":{"id":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35","type":"failed","destination":"918x98xx21x4","payload":{"code":1008,"reason":"User is not Opted in and Inactive"}}} |
Код | Причина |
---|---|
1001 | Несоответствие данных последнего назначенного бота и отправителя |
1002 | Номер не существует на WhatsApp |
1003 | Не получается отправить сообщение | Проверьте баланс вашего кошелька |
1004 | Отправка сообщения не удалась, так как пользователь неактивен для сессионных сообщений, а отправка шаблонных сообщений отключена. |
1005 | Отправка сообщения не удалась, так как пользователь неактивен для сессионных сообщений, а шаблон не соответствует. |
1006 | Отправка сообщения не удалась, так как пользователь неактивен для сессионных сообщений и не подписался на получение шаблонных сообщений. |
1007 | Отправка сообщения не удалась, так как пользователь неактивен для сессионных сообщений, не подписался на получение шаблонных сообщений, и шаблон не соответствует. |
1008 | Пользователь не зарегистрирован и неактивен |
В этом разделе мы разберем событие: сообщение, которое вы получаете на вашем URL обратного вызова. Данное событие указывает на тип сообщения, его информационном наполнении, полученного с вашего URL обратного вызова, когда клиент отправляет сообщение на зарегистрированный номер WhatsApp. Давайте по очереди рассмотрим типы входящий сообщений и его информационное наполнение на URL обратного вызова:
Ниже приведен пример информационного наполнения, когда клиент отправляет текстовое сообщение на ваш деловой номер WhatsApp.
Заголовки |
Content type: application/json
|
Тело входящего сообщения |
|
Ниже приведен пример информационного наполнения, когда клиент отправляет изображение вместе с подписью на ваш деловой номер WhatsApp. Если подпись не отправляется, то ключ "caption" будет отсутствовать в объекте messageObj.
Заголовки |
Content type: application/json
|
Тело входящего сообщения |
|
Ниже приведен пример информационного наполнения, когда клиент отправляет аудиофайл на ваш деловой номер WhatsApp.
Заголовки |
Content type: application/json
|
Тело входящего сообщения |
|
Ниже приведен пример информационного наполнения, когда клиент отправляет видеофайл на ваш деловой номер WhatsApp.
Заголовки |
Content type: application/json
|
Тело входящего сообщения |
|
Ниже приведен пример информационного наполнения, когда клиент отправляет документ с подписью на ваш деловой номер WhatsApp. Если подпись не отправляется, то ключ "caption" будет отсутствовать в объекте messageObj.
Заголовки |
Content type: application/json
|
Тело входящего сообщения |
|
Ниже приведен пример информационного наполнения, когда клиент отправляет свое местоположением на ваш деловой номер WhatsApp.
Заголовки |
Content type: application/json
|
IТело входящего сообщения |
|
Это сообщения, отправленные клиенту с помощью API отправки сообщений. Рассмотрим подробнее спецификации/подписи API, т.е. конечную точку API, Заголовки, Тело запроса и его Ответ:
Content-type
|
application/x-www-form-urlencoded |
apikey
|
Здесь Ваш API ключ |
Ключ | Тип | Описание | Образец | Требуется |
---|---|---|---|---|
|
string |
Канал, по которому должно быть отправлено это сообщение. |
|
Да |
|
string |
Номер телефона получателя, которому отправляется сообщение. |
918x98xx21x4 |
Да |
|
string |
Номер телефона WhatsApp Business, с которого будет отправляться сообщение. Это должен быть верифицированный номер, связанный с вашим приложением Gupshup. |
917834811114 |
Да |
|
object |
Шаблонное сообщение WhatsApp, которое вы хотите отправлять своим клиентам. |
См. документацию сообщение.информационное наполнение ниже |
Да |
|
string |
Название вашего приложения WhatsApp |
Демо приложение |
Да - для приложений песочницы |
Ключ | Тип | Описание | Образец | Требуется |
---|---|---|---|---|
|
string |
Значение будет |
|
Да |
|
string |
Тип сообщения, которое будет отправлено клиенту. В зависимости от "типа", соответствующие параметры должны быть отправлены как часть объекта сообщение.информационное наполнение
|
|
Да |
|
string |
Текстовое сообщение, которое будет отправлено клиенту, в случае, если тип=текст |
Привет Мир! |
Нет |
|
string |
Публичный URL, где размещаются файловые / аудио / видео вложения, отправляемые клиенту. |
https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_700KB.mp3 |
Нет |
|
string |
Публичный URL, где размещается изображение, отправляемое клиенту. Только для типа = изображение |
https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg |
Нет |
|
string |
Публичный URL, где размещается эскиз изображения, отправляемый клиенту. Только для типа = изображение |
https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg |
Нет |
|
string |
Add caption to media messages, applicable to media type = |
Media caption text |
N |
Ниже приведен пример информационного наполнения при отправке шаблонного сообщения на WhatsApp.
API URL | https://api.gupshup.io/sm/api/v1/msg |
Заголовки запросов |
Content-Type: application/x-www-form-urlencoded apikey: {{Your API Key}} |
Тело запроса |
"channel" : "whatsapp", "source" : "917384811114", "destination" : "918x98xx21x4" "src.name":"DemoApp" "message.payload" : { "isHSM":"true", "type": "text", "text": "Привет, Джон, твой заказ подтвержден и будет доставлен тебе к 15 февраля." } |
Ниже приведен пример информационного наполнения при отправке текстового сообщения на WhatsApp.
API URL | https://api.gupshup.io/sm/api/v1/msg |
Заголовки запросов |
Content-Type: application/x-www-form-urlencoded apikey: {{Your API Key}} |
Тело запроса |
"channel" : "whatsapp", "source" : "917384811114", "destination" : "918x98xx21x4" "src.name":"DemoApp" "message.payload" : { "isHSM":"false", "type": "text", "text": "Привет, Джон, как дела?" } |
Ниже приведен пример информационного наполнения при отправке изображения на WhatsApp.
API URL | https://api.gupshup.io/sm/api/v1/msg |
Заголовки запросов |
Content-Type: application/x-www-form-urlencoded apikey: {{Your API Key}} |
Тело запроса |
"channel" : "whatsapp", "source" : "917384811114", "destination" : "918x98xx21x4" "src.name":"DemoApp" "message.payload" : { "type": "image", "originalUrl": "https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg", "previewUrl": "https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg", "caption":"Sample image" } |
Ниже приведен пример информационного наполнения при отправке документа / файла на WhatsApp.
API URL | https://api.gupshup.io/sm/api/v1/msg |
Заголовки запросов |
Content-Type: application/x-www-form-urlencoded apikey: {{Your API Key}} |
Тело запроса |
"channel" : "whatsapp", "source" : "917384811114", "destination" : "918x98xx21x4" "src.name":"DemoApp" "message.payload" : { "type": "file", "url": "http://enterprise.smsgupshup.com/doc/GatewayAPIDoc.pdf", "filename": "Sample file" } |
Ниже приведен пример информационного наполнения при отправке аудиофайла на WhatsApp.
API URL | https://api.gupshup.io/sm/api/v1/msg |
Заголовки запросов |
Content-Type: application/x-www-form-urlencoded apikey: {{Your API Key}} |
Тело запроса |
"channel" : "whatsapp", "source" : "917384811114", "destination" : "918x98xx21x4" "src.name":"DemoApp" "message.payload" : { "type": "audio", "url": "https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_700KB.mp3" } |
Ниже приведен пример информационного наполнения при отправке видео на WhatsApp.
API URL | https://api.gupshup.io/sm/api/v1/msg |
Заголовки запросов |
Content-Type: application/x-www-form-urlencoded apikey: {{Your API Key}} |
Тело запроса |
"channel" : "whatsapp", "source" : "917384811114", "destination" : "918x98xx21x4" "src.name":"DemoApp" "message.payload" : { "type": "video", "url":"http://clips.vorwaerts-gmbh.de/big_buck_bunny.mp4", "caption":"Sample video" } |
WhatsApp поддерживает некоторое форматирование в сообщениях. Для того, чтобы отформатировать сообщение целиком или его часть, используйте следующие символы форматирования:
Форматирование | Символ | Пример | Как отображаются сообщения в WhatsApp |
---|---|---|---|
Жирный | Звездочка (*) | Ваша сумма составляет *$10.50*. | Ваша сумма составляет $10.50.. |
Курсив | Нижнее подчеркивание(_) | Добро_пожаловать_в_WhatsApp_! | Добро пожаловать в WhatsApp!! |
|
Зачёркнутый (~) | Так ~будет~ лучше! | Так будет лучше! best! |
Code
|
Три обратные галочки (```) | ```print 'Привет Мир';``` | print 'Hello World'; |
Также поддерживаются смайлики. Список поддерживаемых смайликов находится на сайте https://emojipedia.org/whatsapp/ . Скопируйте символ смайлика в сообщение при отправке через API.
Added below language support for WhatsApp,
Bot developers for Line: With the release of Line Messaging API, all BOT API Trial Accounts are scheduled to be deleted. Please republish your bot according to new Line implementation, mentioned under Publish tab in My Bots section.
New tool for non-developers- Our Flow Bot Builder helps users create their bot messaging flow with a graphical editor.
API.ai tool is now available for developing your NLP/AI bot.
Gupshup Enterprise APIs (SMS,Voice and Email) are now available directly in the APIs section.
New channels added for publishing bots- Smooch.io and your website as a web widget.
Now you can access our services including the bot builder tool using your Facebook login credentials.
Now you can delete the dummy bots created for testing from the My Bots Dashboard.
You can now access Bot specific data from your Dashboard itself.
Introducing a hassle free bot development experience for users to instantly create bots using our pre-defined restaurant templates. Check out our blog to know more.
We are removing few redundant parameters, that were being sent when a callback happens to your bot (i.e. inbound message comes to your bot).
Following is the list of parameters.
However, we will continue to send following parameters. If you are using any of the deprecated parameters, we request you to use these alternatives.
You are requested to make a note of this and do the necessary changes immediately to your bot code to keep it working. Should you need any help, please feel free to send an email to devsupport@gupshup.io