Документация по доступу к WhatsApp API Это руководство доступно на следующих языках: Portuguese, German, English и Spanish

Сегодня более 1,5 миллиарда человек в более чем 180 странах используют WhatsApp, чтобы оставаться на связи с друзьями и семьей в любое время и в любом месте. Компании по всему миру уже используют WhatsApp для неформального общения с клиентами, будь то запросы о товарах и услугах или уведомления о финансовых транзакциях. WhatsApp Business API - это новый способ для компаний улучшить коммуникацию со своими текущими клиентами и привлечь новых, которые также оценят быстрый, удобный и приватный обмен сообщениями.

Это руководство содержит спецификацию Gupshup API для отправки и получения сообщений в WhatsApp посредством простого REST API через протоколы HTTP/HTTPS.

Это руководство предназначено для разработчиков и сотрудников ИТ отделов компаний, которые планируют интегрировать свои системы с Gupshup's Messaging API. Кроме того, данное руководство предназначено для приложений (APPs) типа Access API созданных на нашей платформе после 28 января 2020 года. Если у вас есть приложение, созданное до указанной даты, пожалуйста, произведите его миграцию на V2.

Краткий список тем, которые мы рассмотрим в этом руководстве:

1. Установка URL Webhook/Callback
2. Входящие сообщения и события
   • События
   • Входящее сообщение
     • Текст
       • Клиент ответил на сообщение от бизнеса
       • Клиент нажал на шаблон быстрого ответа
     • Медиа
       • Изображение
       • Аудио
       • Видео
       • Документ
       • Стикер
     • Интерактивные сообщения
       • Клиент ответил на сообщение в из списка
       • Клиент ответил на быстрый ответ
     • Другие сообщения
       • Местоположение
       • Карточка контакта
       • Направление
3. Исходящее сообщение
   • Сообщения сессии
     • API Endpoint
     • Запрос API
       • Отправить сообщение
         • Параметры форматирования
       • Медиа
         • Отправить изображение
         • Отправить документ/файл
         • Отправить аудио
         • Отправить видео
         • Стикер
       • Интерактивные сообщения
         • Список сообщений
         • Быстрые ответы
       • Другие типы сообщений
         • Отправить местоположение
         • Отправить карточку контакта
     • API ответ
   • Шаблон сообщений
     • API Endpoint
     • Запрос API
       • Отправить сообщение
       • Медиа
         • Отправить изображение
         • Отправить видео
         • Отправить документ/файл
         • Отправить местоположение
       • Интерактивные сообщения
         • Призыв к действию
         • Быстрые ответы
     • API ответ
4. Разные API
   • Получить список пользователей API
   • Отметить пользователя, давшего согласие на рассылку
   • Отметить пользователя, отказавшегося от рассылки
   • Получить список шаблонов
   • Проверить баланс кошелька

Установка URL Webhook/Callback

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

Входящие сообщения, отправленные клиентами на ваш номер телефона WhatsApp Business Phone Number, будут отправлены на ваш вебхук, то есть клиент отправляет текстовое сообщение или медиа-вложение в WhatsApp, платформа Gupshup регистрирует это событие и немедленно отправляет уведомление (HTTP POST запрос) на вебхук, указанный в настройках вашего приложения. Важная информация о вебхуке:

1. Вебхук должен вернуть HTTP_SUCCESS (код: 2xx) пустое значение. Если этого не произойдет в течение 10 секунд, мы будем считать, что уведомление не было доставлено, и повторим попытку после небольшой задержки.
2. Ваш вебхук должен обрабатывать входящие сообщения и события асинхронно, но подтверждать их получение синхронно и немедленно. Лучшее время подтверждения должно быть менее 100 миллисекунд, так как некоторая задержка в сети вполне объяснима, поэтому рекомендуется 500-1000 миллисекунд. Чем больше время отклика, тем больше задержанных входящих сообщений и событий вы будете получать каждый раз.
3. Вебхук должен принимать HTTP-заголовок: User-Agent
4. Вебхук должен принимать пользовательское событие: sandbox-start
5. Вебхук должен иметь публичный доступ, а если по соображениям безопасности вы хотите сохранить его конфиденциальность, вам необходимо внести IP-адреса входящих запросов Gupshup в список. Свяжитесь с нами по адресу devsupport@gupshup.io, чтобы получить данные этих IP.

Если у вас возникли проблемы с настройкой вебхука, обратитесь к этому FAQ, чтобы узнать процедуру устранения неполадок.

Обратитесь к изображению ниже, чтобы найти опцию установки Вебхука/Callback в настройках приложения. Если переключатель URL обратного вызова OFF. вы можете видеть входящие сообщения в Входящие сообщения | События поле. Эти сообщения и зарегистрированные события хранятся временно, то есть они удаляются, если вы обновите страницу.

Входящие сообщения и события

Три типа входящих уведомлений, доставляемых на ваш вебхук:

1. пользователь-событие
2. сообщение-событие
3. сообщение

Вышеперечисленные типы уведомлений делятся на - События а также Входящие сообщения, Давайте сначала познакомимся со структурой входящих уведомлений:

Тип содержимого входящей полезной нагрузки

Параметры/свойства, общие для всех входящих уведомлений

{
	 "app": "DemoApp",
	 "timestamp": 1580227766370,
	 "version": 2,
	 "type": "user-event"|"message-event"|"message",
	 "payload": << Это зависит от значения свойства "тип". >>
   }
   

События

В этом разделе мы разберем:
1.  user-event : Эти сообщения генерируются нашей платформой, когда происходит какое-то событие. Например, вы будете получать следующие системные события, когда:
    - URL-адрес обратного вызова устанавливается для приложения или при использовании команды прокси для вызова вашего приложения на номер телефона бота Gupshup Proxy (+917834811114) для тестирования приложения.
    - Конечный пользователь дает согласие (Opt-in) на получение уведомления с рабочего номера телефона.

{
	  "app":"DemoApp",
	  "timestamp":1580142086287,
	  "version":2,
	  "type":"user-event",
	  "payload":{
		 "phone":"callbackSetPhone"|"918x98xx21x4",
		 "type":"sandbox-start"|"opted-in"|"opted-out"
	  }
   }
   

Объект полезной нагрузки

Тип пользователь-событие:

2.  message-event : Эти события определяют статус сообщения, отправленного с помощью API отправки сообщения API отправки сообщения клиенту WhatsApp API (которое, по сути, отправляет сообщение клиенту). Клиент WhatsApp Business API будет отправлять уведомления, чтобы информировать вас о статусе сообщений между вами и пользователями. Когда сообщение успешно отправлено, вы получите уведомление о том, когда сообщение было отправлено, доставлено и прочитано. Порядок этих уведомлений в вашем приложении может не отражать фактическое время отправки/доставки сообщения. При необходимости просмотрите метку времени, чтобы определить время. Вы можете получить следующие уведомления:

{
	  "app":"DemoAPI",
	  "timestamp":1580546677791,
	  "version":2,
	  "type":"message-event",
	  "payload":{
		 "id":"59f8db90-c37e-4408-90ab-cc54ef8246ad"(идентификатор сообщения Gupshup)|"gBEGkYaYVSEEAgnZxQ3JmKK6Wvg" (идентификатор сообщения WhatsApp)
		 "gsId": "ee4a68a0-1203-4c85-8dc3-49d0b3226a35" (идентификатор сообщения Gupshup - Это свойство применимо только для событий DLR.)
		 "type":"enqueued"|"failed"|"sent"|"delivered"|"read",
		 "destination":"91XX985XX10X",
		 "payload": << Варьируется в зависимости от значения свойства - 'тип' >>;
	  }
   }
   

Объект полезной нагрузки

Типы сообщений-событий:

Причина почему сообщение не доставлено и код ошибки:

Чтобы узнать больше о кодах ошибок клиента WhatsApp Business API, here

Входящее сообщение

В этом разделе мы разберем событие: сообщения которые вы получаете на ваш URL обратного вызова. Это событие определяет тип полезной нагрузки сообщения, полученного на ваш URL обратного вызова, когда клиент отправляет сообщение на зарегистрированный номер телефона WhatsApp Business API.

Заголовки

Параметры/свойства, общие для всех входящих сообщений

{   
	 "app": "DemoApp", 
	 "timestamp": 1580227766370,   
	 "version": 2, 
	 "type": "message",    
	 "payload": {  
	   "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c",   
	   "source": "918x98xx21x4",   
	   "type": "text"|"image"|"file"|"audio"|"video"|"contact"|"location"|"button_reply"|"list_reply", 
	   "payload": {    
		 //Varies according to the type of payload.    
	   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "Smit",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   },  
	   "context": {    
		 "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",  
		 "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"    
	   }   
	 } 
   }   
   

The payload object

Объект-отправитель

Объект контекста

Давайте рассмотрим один за другим типы входящих сообщений, получаемых на URL обратного вызова:

Текстовая полезная нагрузка

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

{ 
	 "app": "DemoApp", 
	 "timestamp": 1580227766370,   
	 "version": 2, 
	 "type": "message",    
	 "payload": {  
	   "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c",   
	   "source": "918x98xx21x4",   
	   "type": "text", 
	   "payload": {    
		 "text": "Hi"  
	   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "Smit",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   }   
	 } 
   }

Клиент ответил на сообщение от бизнеса

Пользователи могут отвечать на конкретное сообщение в WhatsApp. Чтобы компания могла понять контекст ответа на сообщение, мы включаем контекст объекта. Этот объект контекста содержит Gupshup message-id(property: gsId) сообщения, на которое ответил клиент, и WhatsApp message-id(property: id) исходного сообщения.
Ниже приведен пример входящего сообщения, которое является ответом на сообщение, отправленное компанией.

{
	 "app": "DemoApp",
	 "timestamp": 1590854464792,
	 "version": 2,
	 "type": "message",
	 "payload": {
	   "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW",
	   "source": "918x98xx21x4",
	   "type": "text",
	   "payload": {
		 "text": "hi"
	   },
	   "sender": {
		 "phone": "918x98xx21x4",
		 "name": "Smit",
		 "country_code": "91",
		 "dial_code": "8x98xx21x4"
	   },
	   "context": {
		 "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",
		 "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"
	   }
	 }
   }
   

Клиент нажал на кнопку шаблона сообщения Быстрый Ответ

Когда клиент выбирает кнопку из сообщения быстрого ответа, получается следующий пример полезной нагрузки.
Чтобы компания могла понять контекст ответа на сообщение, мы включаем контекст объекта. Этот объект контекста содержит Gupshup message-id(property: gsId) сообщения, на которое ответил клиент, и WhatsApp message-id(property: id) исходного сообщения. В дополнение к этому объекту payload предоставляется текст кнопки, которую пользователь щелкнул.

{
	 "app": "DemoApp",
	 "timestamp": 1590854464792,
	 "version": 2,
	 "type": "message",
	 "payload": {
	   "id": "ABEGkYaYVSEEAgo-sMx1DoUoQJRW",
	   "source": "918x98xx21x4",
	   "type": "text",
	   "payload": {
		 "text": "View Account Balance",
		 "type": "button"
	   },
	   "sender": {
		 "phone": "918x98xx21x4",
		 "name": "Smit",
		 "country_code": "91",
		 "dial_code": "8x98xx21x4"
	   },
	   "context": {
		 "id": "gBEGkYaYVSEEAgnPFrOLcjkFjL8",
		 "gsId": "9b71295f-f7af-4c1f-b2b4-31b4a4867bad"
	   }
	 }
   }
   

Медиа

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

Общая полезная нагрузка медиа

Изображение

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

{   
	 "app": "DemoApp", 
	 "timestamp": 1580227895991,   
	 "version": 2, 
	 "type": "message",    
	 "payload": {  
	   "id": "ABEGkYaYVSEEAhAE0dyndiP9cVlr4hC5xU64",   
	   "source": "918x98xx21x4",   
	   "type": "image",    
	   "payload": {    
		 "caption": "Sample image",    
		 "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/546af999-825e-485b-bf54-4a3323824cca",  
		 "contentType": "image/jpeg",  
		 "urlExpiry": 1624956794816    
	   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "John",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   }   
	 } 
   }   
   

Аудио

Ниже приведен пример полезной нагрузки, полученной, когда клиент отправляет аудиофайл или голосовое сообщение на телефонный номер вашей компании. В случае голосовых сообщений тип содержимого всегда: audio/ogg; codecs=opus

{   
	 "app": "DemoApp", 
	 "timestamp": 1580228104661,   
	 "version": 2, 
	 "type": "message",    
	 "payload": {  
	   "id": "ABEGkYaYVSEEAhC8Sqz6bdT95X8wgVH28wz8",   
	   "source": "918x98xx21x4",   
	   "type": "audio",    
	   "payload": {    
		 "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/eae8a65a-b3ec-4085-94a6-3738338835fc",  
		 "contentType": "audio/ogg; codecs=opus",  
		 "urlExpiry": 1624956864635    
	   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "John",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   }   
	 } 
   }   
   

Видео

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

{   
	 "app": "DemoApp", 
	 "timestamp": 1580228336953,   
	 "version": 2, 
	 "type": "message",    
	 "payload": {  
	   "id": "ABEGkYaYVSEEAhDHMK-ctBQwqxyKoMbKcxES",   
	   "source": "918x98xx21x4",   
	   "type": "video",    
	   "payload": {    
		 "caption": "Sample video",    
		 "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/9f5ff20a-d14f-47ea-b336-754756a8b950",  
		 "contentType": "video/mp4",   
		 "urlExpiry": 1580833136954    
	   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "John",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   }   
	 } 
   }   
   

Документ

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

{   
	 "app": "DemoApp", 
	 "timestamp": 1580228523976,   
	 "version": 2, 
	 "type": "message",    
	 "payload": {  
	   "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",   
	   "source": "918x98xx21x4",   
	   "type": "file", 
	   "payload": {    
		 "caption": "Document caption",    
		 "name": "samplefile.pdf", 
		 "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/b6e4e360-be01-4ffa-8928-84b8f40dd2eb",  
		 "contentType": "application/pdf", 
		 "urlExpiry": 1624957181122    
	   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "Smit",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   }   
	 } 
   }   
   

Стикер

Ниже приведен пример полезной нагрузки, полученной при отправке клиентом наклейки на ваш рабочий номер.

{
	 "app": "DemoApp",
	 "timestamp": 1580228523976,
	 "version": 2,
	 "type": "message",
	 "payload": {
	   "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
	   "source": "918x98xx21x4",
	   "type": "sticker",
	   "payload": {
		 "url": "https://filemanager.gupshup.io/fm/wamedia/DemoApp/32030cb2-68de-4c3c-a795-c4647fd4a9c7",
		 "contentType": "image/webp",
		 "urlExpiry": 1624957279044
	   },
	   "sender": {
		 "phone": "918x98xx21x4",
		 "name": "John",
		 "country_code": "91",
		 "dial_code": "8x98xx21x4"
	   }
	 }
   }
   

Интерактивные сообщения

Клиент ответил на сообщение из списка

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

{
	 "app": "DemoApp",
	 "timestamp": 1580228523976,
	 "version": 2,
	 "type": "message",
	 "payload": {
	   "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
	   "source": "918x98xx21x4",
	   "type": "list_reply",
	   "payload": {
			   "title": "section 1 row 1",
			   "id": "list1",
			   "reply":"section 1 row 1 1",
			   "postbackText":"section 1 row 1 postback payload",
			   "description": "first row of first section description"
		   },
	   "sender": {
		 "phone": "918x98xx21x4",
		 "name": "John",
		 "country_code": "91",
		 "dial_code": "8x98xx21x4"
	   },
	   "context": {
		   "id": "gBEGkYaYVSEEAgnPGGVYGg1uNU4",
		   "gsId": "cbdafe39-1023-42a7-89d6-6c01a3388bb5"
	   }
	 }
   }
   

Клиент ответил на Кнопку быстрого ответа

Когда клиент выбирает кнопку из сообщения быстрого ответа, получается следующий пример полезной нагрузки.

{
	 "app": "DemoApp",
	 "timestamp": 1580228523976,
	 "version": 2,
	 "type": "message",
	 "payload": {
	   "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
	   "source": "918x98xx21x4",   
	   "type": "button_reply", 
	   "payload": {    
			   "title": "First",   
			   "id": "qr1",    
			   "reply":"First 1"   
		   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "John",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   },  
	   "context": {    
		   "id": "gBEGkYaYVSEEAgkvE0f1ZkfXX78",    
		   "gsId": "123b0fb2-0620-493b-8f7e-5a1ceb6d8c58"  
	   }   
	 } 
   }   
   

Другие типы сообщений

Местоположение

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

Обратите внимание, что в настоящее время Трансляция геопозиции не является поддерживаемым типом сообщения в WhatsApp Business.

{   
	 "app": "DemoApp", 
	 "timestamp": 1580228767338,   
	 "version": 2, 
	 "type": "message",    
	 "payload": {  
	   "id": "ABEGkYaYVSEEAhCIxTq7KXQIqby1Uo-IO7_E",   
	   "source": "918x98xx21x4",   
	   "type": "location", 
	   "payload": {    
		 "longitude": "72.8552172",    
		 "latitude": "19.1453658"  
	   },  
	   "sender": { 
		 "phone": "918x98xx21x4",  
		 "name": "Smit",   
		 "country_code": "91", 
		 "dial_code": "8x98xx21x4" 
	   }   
	 } 
   }   
   

Карточка контакта

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

{
	 "app": "DemoApp",
	 "timestamp": 1584898884710,
	 "version": 2,
	 "type": "message",
	 "payload": {
	   "id": "ABEGkYaYVSEEAhD9cTZVyPlOGYZJOnviI7OJ",
	   "source": "918x98xx21x4",
	   "type": "contact",
	   "payload": {
		 "contacts": [
		   {
			 "addresses": [
			   {
				 "city": "Menlo Park",
				 "country": "United States",
				 "countryCode": "us",
				 "state": "CA",
				 "street": "1 Hacker Way",
				 "type": "HOME",
				 "zip": "94025"
			   },
			   {
				 "city": "Menlo Park",
				 "country": "United States",
				 "countryCode": "us",
				 "state": "CA",
				 "street": "200 Jefferson Dr",
				 "type": "WORK",
				 "zip": "94025"
			   }
			 ],
			 "emails": [
			   {
				 "email": "test@fb.com",
				 "type": "WORK"
			   },
			   {
				 "email": "test@whatsapp.com",
				 "type": "WORK"
			   }
			 ],
			 "ims": [
   
			 ],
			 "name": {
			   "first_name": "Dev",
			   "formatted_name": "Dev Support",
			   "last_name": "Support"
			 },
			 "org": {
			   "company": "Dev Support"
			 },
			 "phones": [
			   {
				 "phone": "+91 77383 05433",
				 "type": "Mobile"
			   }
			 ],
			 "urls": [
			   {
				 "url": "https://www.facebook.com",
				 "type": "WORK"
			   }
			 ]
		   }
		 ]
	   },
	   "sender": {
		 "phone": "918x98xx21x4",
		 "name": "Smit",
		 "country_code": "91",
		 "dial_code": "8x98xx21x4"
	   }
	 }
   }
   

Направление

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

{
	   "app": "DemoApp",
	   "timestamp": 1624350395531,
	   "version": 2,
	   "type": "message",
	   "payload": {
		   "id": "ABEGkZlpNARoAgo6v1b-zBR7EnX3",
		   "source": "918x98xx21x4",
		   "type": "text",
		   "payload": {
			   "text": "I saw this on Facebook..."
		   },
		   "sender": {
			   "phone": "918x98xx21x4",
			   "name": "Smit",
			   "country_code": "91",
			   "dial_code": "8x98xx21x4"
		   },
		   "referral": {
				   "body": "Test post payload",
				   "headline": "Demo Gupshup ad",
				   "image": {
					   "id": "6a35b528-429d-4fe3-953d-536ef0397ece"
				   },
				   "source_id": "951242428775548",
				   "source_type": "post",
				   "source_url": "https://fb.me/2oNXGTsjn"
		   }
	   }
   }
   

Исходящее сообщение

Сообщения сессии

Это руководство научит вас, как отправить сообщение сессии клиенту с помощью API для отправки сообщения. В настоящее время этот тип отправки сообщений может быть осуществлен только в течение 24 часов после последнего сообщения, отправленного пользователем. Если вы попытаетесь отправить сообщение по истечении 24-часов, вы получите событие сбоя на вашем вебхук. Чтобы лучше понять Пользователя нашей платформы, пожалуйста, обратитесь к этой статье, это поможет вам более эффективно использовать API.
Давайте разберем спецификацию/признак API, т.е. конечную Точку API, Заголовки, Тело запроса и его Ответ в деталях:.

API Endpoint

Чтобы отправить сообщение в WhatsApp, делается запрос API к конечной точке:

https://api.gupshup.io/sm/api/v1/msg
   

Запрос API

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

curl --location --request POST 'https://api.gupshup.io/sm/api/v1/msg' \
   --header 'Cache-Control: no-cache' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --data-urlencode 'channel=whatsapp' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'message={"type": "text","text": "Hi John, how are you?"}' \
   --data-urlencode 'src.name=DemoApp' \
   --data-urlencode 'disablePreview=false'
   

Заголовки

Тело запроса

Общие параметры объекта сообщения

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

Ниже приведен пример полезной нагрузки при отправке текстового сообщения в WhatsApp.

- Текстовое сообщение может быть максимум 4096 символов.
- Чтобы включить предварительный просмотр URL в сообщение, убедитесь, что URL начинается с http:// или https://.
- URL для предварительного просмотра: имя хоста обязательно, IP-адреса не рассматриваются.
- Если текстовое сообщение имеет несколько URL, первый URL будет только предварительно просмотрен.

Параметры форматирования

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

Эмодзи также поддерживаются. Список поддерживаемых эмодзи находится по адресу https://emojipedia.org/whatsapp/. Копирование символа emoji в текстовом сообщении при отправке через API.

Медиа

Отправить изображение

Ниже приведен пример полезной нагрузки при отправке изображения в WhatsApp.

- Поддерживаемые типы контента: image/jpeg, image/png
- максимальный размер файла: 5 MB

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

Ниже приведен пример полезной нагрузки при отправке документа / файла в WhatsApp.

- Поддерживаемые типы контента: Любой допустимый MIME-тип
- максимальный размер файла: 100 MB

Отправить аудио

Ниже приведен пример полезной нагрузки при отправке аудиофайла в WhatsApp.

- Поддерживаемые типы контента: audio/aac, audio/mp4, audio/amr, audio/mpeg, audio/ogg; codecs=opus. Note: Базовый тип audio / ogg не поддерживается.
- максимальный размер файла: 16 MB

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

Ниже приведен пример полезной нагрузки при отправке видео в WhatsApp.

- Поддерживаемые типы контента: video/mp4, video/3gpp. Note: Поддерживаются только видеокодек H.264 и аудиокодек AAC.
- максимальный размер файла: 16 MB

Отправить стикеры

Ниже приведен пример полезной нагрузки при отправке стикера в WhatsApp.

- Каждая наклейка имеет прозрачный фон.
- Наклейки должны быть ровно 512x512 пикселей.
- Размер каждой наклейки не должен превышать 100 КБ.

Интерактивные сообщения

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

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

Отправить быстрые ответы

Этот тип сообщения предлагает пользователям более быстрый способ сделать выбор из меню при взаимодействии с компанией. Кнопки ответа имеют такой же пользовательский опыт, как и интерактивные шаблоны с кнопками.
Ниже приведен пример полезной нагрузки при отправке сообщения Быстрые ответы конечным пользователям в WhatsApp.

Другие сообщения

Отправить местоположение

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

Отправить карточку контакта

Ниже приведен пример полезной нагрузки для отправки карточки контакта конечному пользователю.

API ответ

API-запросы на отправку сообщения, полученные нашей платформой, обрабатываются асинхронно, поэтому вы всегда получите ответ HTTP_SUCCESS(200 to 299), если API-запрос был сделан правильно. API-ответ включает в себя объект с идентификатором сообщения Gupshup и статусом submitted а ваш webhook получит message-event, в котором говорится, что отправленное вами сообщение клиенту API WhatsApp (который фактически отправляет сообщение клиенту) зарегистрировано или не доставлено.

{"status":"submitted","messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"}
   

Идентификатор сообщения Gupshup, т.е. messageId Id сообщения в ответе API, поможет отследить сообщения по событиям сообщения, т.е. "enqueued"|"failed"|"sent"|"delivered"|"read" полученным на webhook.

Шаблон сообщений

Шаблонная рассылка сообщений позволяет бизнесу рассылать уведомления своим клиентам за пределами 24-часового интервала. Согласно правилам WhatsApp, уведомления должны отправляться только тем пользователям, которые дали согласие на получение сообщений от компании. В соответствии с этим, по умолчанию, на нашей платформе шаблонные сообщения могут отправляться только тем пользователям, которые согласились получать сообщения от компании. Чтобы отметить пользователя как согласившегося получать сообщения, используйте Отметить пользователя, давшего согласие на рассылку.

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

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

Давайте подробнее разберем спецификацию API, т.е. конечную точку API, заголовки, тело запроса и ответ:

API Endpoint

Чтобы отправить сообщение в WhatsApp, запрос API делается к этой конечной точке:

http://api.gupshup.io/sm/api/v1/template/msg
   

Запрос API

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

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}'
   

Заголовки запроса

Тело запроса

API ответ

API-запросы на отправку сообщения, полученные нашей платформой, обрабатываются асинхронно, поэтому вы всегда получите ответ HTTP_SUCCESS(200 to 299), если API-запрос был сделан правильно. API-ответ включает в себя объект с идентификатором сообщения Gupshup и статусом submitted а ваш webhook получит message-event в котором говорится, что отправленное вами сообщение клиенту API WhatsApp (который фактически отправляет сообщение клиенту) зарегистрировано или не доставлено.

{
	   "messageId": "bf70b8c4-a5b9-4acd-b108-512ce704f4dc",
	   "status": "submitted"
   }
   

Идентификатор сообщения Gupshup, т.е. messageId Id сообщения в ответе API, поможет отследить сообщения по событиям сообщения, т.е. "enqueued"|"failed"|"sent"|"delivered"|"read" полученным на webhook.

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

Послать текст

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}'
   

Медиа

Отправить изображение

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
   --data-urlencode 'message={"type":"image","image":{"link":"https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg"}}'
   

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

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
   --data-urlencode 'message={"type":"video","video":{"link": "https://www.buildquickbots.com/whatsapp/media/sample/video/sample01.mp4"}}'
   

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

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
   --data-urlencode 'message={"type":"document","document":{"link":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf","filename": "Sample funtional resume"}}'
   

Отправить местоположение

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["Agent","Local Address","Tracking code"]}' \
   --data-urlencode 'message={"type":"location","location":{"longitude":"","latitude":""}}'
   

Интерактивные сообщения

Призыв к действию

Для утвержденного интерактивного шаблона мультимедиа, подобного этому:
Hi {{1}}, Please find the attached bill. For more details please visit our website. | [Visit Website,https://www.gupshup.io/developer/{{1}}]

Если в теле сообщения, а также в кнопке призыва к действию есть текст, запрос API может быть таким:

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c49ee21d-4d39-452d-a6c1-25b7615e01e4","params": ["John","docs/bot-platform/guide/whatsapp-api-documentation"]}' \
   --data-urlencode 'message={"type":"document","document":{"link":"https://www.buildquickbots.com/whatsapp/media/sample/pdf/sample01.pdf","filename": "Sample funtional resume"}}'
   

Быстрые ответы

Для утвержденного интерактивного шаблона мультимедиа, подобного этому:
You can now view your Account Balance or Mini statement for Account ending with {{1}} simply by selecting one of the options below. | [View Account Balance] | [View Mini Statement]
Если в теле сообщения, а также в кнопке призыва к действию есть текст, запрос API может быть таким:

curl --location --request POST 'http://api.gupshup.io/sm/api/v1/template/msg' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --data-urlencode 'source=917834811114' \
   --data-urlencode 'destination=918x98xx21x4' \
   --data-urlencode 'template={"id": "c6aecef6-bcb0-4fb1-8100-28c094e3bc6b","params": ["12323XXXX"]}'
   

Разные API

Получить список пользователей API

Этот API поможет вам получить список всех пользователей, взаимодействовавших с телефонным номером вашего бизнеса, и их статус согласия/не согласия на получение рассылки:
Curl request

Запрос API

curl --location --request GET 'https://api.gupshup.io/sm/api/v1/users/{{App_Name}}' \
   --header 'apikey: {{Gupshup_Account_APIKey}}'
   

API ответ

{
	 "status": "success",
	 "users": [
	   {
		 "countryCode": "91",
		 "lastMessageTimeStamp": 1585593959851,
		 "optinSource": "URL",
		 "optinStatus": "OPT_IN",
		 "optinTimeStamp": 1585504095053,
		 "phoneCode": "8x98xx21x4"
	   }
	 ]
   }
   

Отметить пользователя, давшего согласие на рассылку

Компании обязаны получить согласие на отправку сообщений перед отправкой проактивных уведомлений клиентам. Компании могут получить согласие множеством способов, как в WhatsApp, так и за его пределами. Этот API очень полезен для получения согласия пользователя с вашего веб-сайта, потоков интерактивного голосового ответа (IVR) или в потоке WhatsApp и т.д.

Запрос API

curl --location --request POST 'https://api.gupshup.io/sm/api/v1/app/opt/in/{{App_Name}}' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'apikey: {{Gupshup_Account_APIKey}}' \
   --data-urlencode 'user={{User_Mobile_Number}}'
   

Значение User_Mobile_Number - это действительный номер телефона с кодом страны. Пример: 918x98xx21x4

Код ответа API

202
   

Отметить пользователя, отказавшегося от рассылки

Если клиент хочет отписаться или отказаться от получения уведомлений. Бизнес может использовать этот API, чтобы сделать то же самое.

Запрос API

curl --location --request POST 'https://api.gupshup.io/sm/api/v1/app/opt/out/{{App_Name}}' \
   --header 'Content-Type: application/x-www-form-urlencoded' \
   --header 'apikey: {{Gupshup_Account_APIKey}}' \
   --data-urlencode 'user={{User_Mobile_Number}}'
   

Значение User_Mobile_Number - действительный номер телефона с кодом страны. Пример: 918x98xx21x4

Код ответа API

202
   

Получить список шаблонов

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

Давайте разберемся в этом API:

API Endpoint

https://api.gupshup.io/sm/api/v1/template/list/:AppName
   

Заголовки запроса

Запрос API

curl --location --request GET 'https://api.gupshup.io/sm/api/v1/template/list/:AppName' \
   --header 'apikey: 2xxc4x4xx2c94xxxc2f9xx9d43xxxx8a'
   

API ответ
HTTP response code: 200

{
   "status": "success",
   "templates": [
	 {
		"category": "ACCOUNT_UPDATE",
		"createdOn": 1580978917761,
		"data": "{{1}} debited with {{2}} on {{3}} for {{4}}.",
		"elementName": "common_transaction_2",
		"id": "05c82e91-05e5-4d35-b280-2d3d20feda38",
		"languageCode": "en_US",
		"languagePolicy": "deterministic",
		"master": false,
		"meta": "{\"example\":\"[Your Bank ac ending with 1245] debited with [Rs. 10000] on [11-Jan-2011] for [ATM cash withdrawal].\"}",
		"modifiedOn": 1581966008618,
		"status": "APPROVED",
		"templateType": "TEXT",
		"vertical": "TRANSACTIONS"
	 },
	 {
		"category": "ISSUE_RESOLUTION",
		"createdOn": 1593540550247,
		"data": "Hola! Soy {{1}} de Ofisí, recibimos una llamada suya, ¿en qué puedo ayudarle?",
		"elementName": "recibimos_llamada",
		"id": "072867eb-dd12-46f5-950d-2dd03a7677e5",
		"languageCode": "es_MX",
		"languagePolicy": "deterministic",
		"master": true,
		"meta": "{\"example\":\"Hola! Soy [Leon] de Ofisí, recibimos una llamada suya, ¿en qué puedo ayudarle?\"}",
		"modifiedOn": 1593627001825,
		"status": "APPROVED",
		"templateType": "TEXT",
		"vertical": "ISSUE RESOLUTION"
	  }
	]
   }
   

Свойство id - это идентификатор шаблона.

Проверить баланс кошелька

Запрос API

curl --location --request GET 'https://api.gupshup.io/sm/api/v2/wallet/balance' \
   --header 'apikey: {{Gupshup Account apikey}}'
   

Код ответа API

200
   

Тело ответа API

{
	   "balance": 1313.7675,
	   "status": "success"
   }