Документация по WhatsApp Access API Документы API теперь доступны в: Portuguese, German, English and Spanish

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

Данное руководство предназначено для разработчиков и ИТ-персонала предприятий, которые планируют интегрировать свои системы с API для обмена сообщениями компании Gupshup. Также, данное руководство применимо для приложений, созданных после 28 января 2020 года на нашей платформе.

Чтобы подытожить то, что мы расскажем в этом руководстве:

  1. Приложение
  2. Установка Веб-хука / URL обратного вызова
  3. Входящие Сообщения и События
  4. Исходящие сообщения
  5. Ответ API
  6. Код Исключения API

    7. Annexure

    Перед использованием API для обмена сообщениями от компании Gupshup, необходимо иметь следующие общие представления:

    • Приложение (App): Приложение на платформе Gupshup представляет собой логический контейнер для определенных интеграций и сервисов. Например,для WhatsApp существует два типа приложений: Поддержка клиентов (Customer Support) и API доступа (Access API). Каждый тип имеет свои свойственные характеристики и сервисы.
    • Песочница: Среда для тестирования приложения WhatsApp Business, в которой представители бизнеса могут создавать и тестировать свои приложения перед запуском.
    • Формат Номеров: API для обмена сообщениями от Gupshup поддерживает номера в формате E.164. Подробнее. Learn more
    • Ключ API: API для обмена сообщениями от Gupshup аутентифицируется с помощью ключа API вашего аккаунта в Gupshup.
    • Веб-хук (URL обратного вызова): Это определяемые пользователем обратный вызов HTTP, которые запускаются определенными событиями, например, входящим сообщением от клиента, и могут быть перенаправлены на ваше приложение, например, на CRM, платформу клиентской поддержки или чат-бот.
    • Сессионные сообщения: Сессионные сообщения используются для ответа на запросы клиентов или сообщения. Если клиент отправляет сообщение на зарегистрированный номер WhatsApp, оно считается входящим сессионным сообщением. В этом случае WhatsApp разрешает представителю бизнеса ответить данному пользователю в течение 24 часов с момента последнего сообщения пользователя (активные пользователи) на тот же номер WhatsApp, которое также называется исходящим сессионным сообщением.
    • Шаблонные сообщения (ВСС): Шаблонные сообщения - это в основном HSM (Высокоструктурированные сообщения или Шаблонные сообщения), как их называет WhatsApp. Шаблонные сообщения используются для отправки транзакционных уведомлений зарегистрированным пользователям, подписчикам. Если клиент подписался, дал свое согласие на получение сообщений с зарегистрированного номера представителя бизнеса на WhatsApp, через один из 5 механизмов, предоставляемых компанией Gupshup, он считается зарегистрированным (опт-ин) пользователем. В таком случае WhatsApp разрешает представителям бизнеса отправлять шаблонные сообщения такими пользователями. Единственное условие WhatsApp касательно шаблонных сообщений, это то, что они должны соответствовать предварительно утвержденному текстовому формату WhatsApp (запрещается отправка мультимедийных сообщений).
    • Подписка(Опт-ин): WhatsApp обязует представителей бизнеса о получении добровольного согласия пользователя на отправку шаблонных сообщений. Gupshup, в свою очередь, эффективно управляет вашими зарегистрированными пользователями за вас. Со стороны представителей бизнеса остается привлекать пользователей через один из 5 предложенных механизмов. (При тестировании приложения, ссылайтесь на шаг 2). Вы можете просмотреть состояние опций и активности пользователей в кнопке "Просмотр пользователей" на странице "Настройки" соответствующего приложения.
    • Входящие сообщения: Это сообщения, полученные на ваш URL обратного вызова, когда клиент отправляет сообщение на зарегистрированный номер WhatsApp.
    • Исходящие сообщения: Это сообщения, отправленные с использованием WhatsApp API для отправки сообщений клиенту.

    Установка Веб-хука / URL Обратного Вызова

    Входящие сообщения, отправленные клиентами на ваш номер телефона 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


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

    Вебхуки определяются пользовательскими обратными вызовами HTTP, которые запускаются определенными событиями. URL обратного вызова в вашем приложении получает 3 события: 1. пользователь-событие 2. сообщение-событие 3. сообщение
    Мы рассмотрим эти события вкратце, разбив на 2 раздела - [События ](#events) и [Входящие Сообщения](#InboundMessage).

    События

    В этом разделе мы разберем: 1. user-event : пользователь-событие : Это событие происходит, когда URL обратного вызова устанавливается для приложения или при использовании прокси-команды для вызова вашего приложения на телефонном номере бота Gupshup Proxy (+917834811114) при тестировании приложения.
    Тип Описание Пример
    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"}}
    2. message-event : сообщение-событие : Данное событие определяет статус сообщения, отправленных с API отправки сообщений на клиент WhatsApp (который, по сути, отправляет сообщение клиенту).
    Тип Описание Пример
    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
    Тело входящего сообщения 
    {
  "app": "DemoApp",
  "timestamp": 1580227766370,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhAL3SLAWwHKeKrt6s3FKB0c",
    "source": "918x98xx21x4",
    "type": "text",
    "payload": {
      "text": "Hi"
    }
  }
}
    Изображение

    Ниже приведен пример информационного наполнения, когда клиент отправляет изображение вместе с подписью на ваш деловой номер WhatsApp. Если подпись не отправляется, то ключ "caption" будет отсутствовать в объекте messageObj.

    Заголовки Content type: application/json
    Тело входящего сообщения 
    {
  "app": "DemoApp",
  "timestamp": 1580227895991,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhAE0dyndiP9cVlr4hC5xU64",
    "source": "918x98xx21x4",
    "type": "image",
    "payload": {
      "caption": "Sample image",
      "url": "https://smapi.gupshup.io/sm/api/wamedia/demobot1/546af999-825e-485b-bf54-4a3323824cca",
      "urlExpiry": 1580832695997
    }
  }
}
    Аудио

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

    Заголовки Content type: application/json
    Тело входящего сообщения 
    {
  "app": "DemoApp",
  "timestamp": 1580228104661,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhC8Sqz6bdT95X8wgVH28wz8",
    "source": "918x98xx21x4",
    "type": "audio",
    "payload": {
      "url": "https://smapi.gupshup.io/sm/api/wamedia/demobot1/f2b80170-981d-4c16-b8be-c12b46ae3436",
      "urlExpiry": 1580832904661
    }
  }
}
    Видео

    Ниже приведен пример информационного наполнения, когда клиент отправляет видеофайл на ваш деловой номер WhatsApp.

    Заголовки Content type: application/json
    Тело входящего сообщения 
    {
  "app": "DemoApp",
  "timestamp": 1580228336953,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhDHMK-ctBQwqxyKoMbKcxES",
    "source": "918x98xx21x4",
    "type": "video",
    "payload": {
      "caption": "Funny video",
      "url": "https://smapi.gupshup.io/sm/api/wamedia/demobot1/9f5ff20a-d14f-47ea-b336-754756a8b950",
      "urlExpiry": 1580833136954
    }
  }
}
    Документ

    Ниже приведен пример информационного наполнения, когда клиент отправляет документ с подписью на ваш деловой номер WhatsApp. Если подпись не отправляется, то ключ "caption" будет отсутствовать в объекте messageObj.

    Заголовки Content type: application/json
    Тело входящего сообщения 
    {
  "app": "DemoApp",
  "timestamp": 1580228523976,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCzqobr15BdMPcRup1fIXAJ",
    "source": "918x98xx21x4",
    "type": "file",
    "payload": {
      "caption": "Pentavalent_vaccine_Guide_for_HWs_with_answers_to_FAQs.pdf",
      "url": "https://smapi.gupshup.io/sm/api/wamedia/demobot1/1c3d7efe-b600-4560-b4d8-36a822310b53",
      "urlExpiry": 1580833323976
    }
  }
}
    Местоположение

    Ниже приведен пример информационного наполнения, когда клиент отправляет свое местоположением на ваш деловой номер WhatsApp.

    Заголовки Content type: application/json
    IТело входящего сообщения 
    {
  "app": "DemoApp",
  "timestamp": 1580228767338,
  "version": 2,
  "type": "message",
  "payload": {
    "id": "ABEGkYaYVSEEAhCIxTq7KXQIqby1Uo-IO7_E",
    "source": "918x98xx21x4",
    "type": "location",
    "payload": {
      "longitude": "72.8552172",
      "latitude": "19.1453658"
    }
  }
}

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

    Это сообщения, отправленные клиенту с помощью API отправки сообщений. Рассмотрим подробнее спецификации/подписи API, т.е. конечную точку API, Заголовки, Тело запроса и его Ответ:

    Конечная точка API

    Для отправки сообщения на 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=hi' \ --data-urlencode 'src.name=DemoApp' ``` Заголовки
    Content-type application/x-www-form-urlencoded
    apikey Здесь Ваш API ключ
    Тело запроса
    Ключ Тип Описание Образец Требуется

    channel

    string

    Канал, по которому должно быть отправлено это сообщение.

    whatsapp

    Да

    destination

    string

    Номер телефона получателя, которому отправляется сообщение.

    918x98xx21x4

    Да

    source

    string

    Номер телефона WhatsApp Business, с которого будет отправляться сообщение. Это должен быть верифицированный номер, связанный с вашим приложением Gupshup.

    917834811114 Это наш прокси номер

    Да

    message

    object

    Шаблонное сообщение WhatsApp, которое вы хотите отправлять своим клиентам.

    См. документацию сообщение.информационное наполнение ниже

    Да

    src.name

    string

    Название вашего приложения WhatsApp

    Демо приложение

    Да - для приложений песочницы

    Нет – для запущенных приложений
    Объект message.payload (сообщение.информационное наполнение)
    Ключ Тип Описание Образец Требуется

    isHSM

    string

    Значение будет true если вы отправляете шаблонное сообщение.
    Для сессионных сообщений, значение будет false

    true|false

    Да

    type

    string

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

    Должен быть один из: text, image, file, audio, video.
    Expect text no other types supports isHSM is true|False

    Text

    Да

    text

    string

    Текстовое сообщение, которое будет отправлено клиенту, в случае, если тип=текст

    Привет Мир!

    Нет

    url

    string

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

    https://file-examples.com/wp-content/uploads/2017/11/file_example_MP3_700KB.mp3

    Нет

    originalUrl

    string

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

    https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg

    Нет

    previewUrl

    string

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

    https://images.pexels.com/photos/248797/pexels-photo-248797.jpeg

    Нет

    caption

    string

    Add caption to media messages, applicable to media type = image|video|file

    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.

    Ответ API

    Ответы API для отправки сообщений WhatsApp являются асинхронными, поэтому вы всегда получите успешный ответ, который включает в себя объект с идентификатором сообщения и статусом отправлено, а ваш URL обратного вызова получит сообщение-событие, в указывается, что ваше отправленное сообщение клиенту WhatsApp (который на самом деле отправляет сообщение клиенту) было запрошено или не было успешно отправлено. ``` {"status":"submitted","messageId":"ee4a68a0-1203-4c85-8dc3-49d0b3226a35"} ```

Please wait

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.

  1. sender
  2. message
  3. context

However, we will continue to send following parameters. If you are using any of the deprecated parameters, we request you to use these alternatives.

  1. senderobj
  2. messageobj
  3. contextobj

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