Использование API-ресурса Send prepared message

Ресурс Send prepared message предназначен для отправки подготовленного сообщения одному или нескольким контактам, в одном запросе можно передать до тысячи получателей. Сообщение может параметризироваться для каждого контакта отдельно. Поддержана возможность работать с email, SMS, Viber, Mob push и web push уведомлениями, путем указания id в URL.

1. Описание запроса

Запрос к ресурсу осуществляется POST методом по адресу https://esputnik.com/api/v1/message/{id}/smartsend, где {id} - id (идентификатор) подготовленного в личном кабинете сообщения.

{
"recipients" : [{
"contactId" : "Идентификатор контакта (может быть не указано, если указан параметр locator).",
"locator" : "Получатель. Например, email-адрес для email сообщений, номер телефона для SMS или Viber.",
"jsonParam" : "Параметр в формате json. Используется для писем со сложными velocity-шаблонами.",
"languageCode" : "Желаемый язык сообщения для контакта. Используется для мультиязычных писем."
  }],
"email" : "Тип сообщения. true - для email, false - для остальных медиа-каналов.",
"fromName" : "Имя отправителя. Необходимо указать только имя отправителя, без email-адреса. Будет использован email отправителя, который выбран в сообщении. Для SMS указывается альфа-имя. Если параметр не указан - будет использоваться имя, выбранное в сообщении."
"externalRequestId" : "Необязательный параметр. Позволяет присвоить отправленому сообщению Ваш собственный идентификатор и в последствии при помощи Get contacts activity получить статус отправленного сообщения."
}

2. Ответ сервера

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

id - всегда возвращается 0;

locator - email или номер телефона, на который отправлялось сообщение;

Если запрос прошел успешно без ошибок, ответ от сервера при отправке двух емейлов в рамках одного запроса будет иметь приблизительно такой вид:

{
    "id": 0,
    "results": [
        {
            "id": 0,
            "locator": "example@mail.com",
            "status": "OK",
            "requestId": "8b2e65d9-060b-4c61-bbd7-73c6796fa504"
        }, {
            "id": 0,
            "locator": "new. example@mail.com",
            "status": "OK",
            "requestId": "458f3533-51d9-439e-a5d0-5fb7c2490c41"
        }
    ]
}

status - Результат. OK - если сообщение успешно поставлено в очередь на отправку; Статус сообщения можно узнать, используя requestId и запрос к ресурсу.

ERROR - если сообщение не удалось поставить в очередь на отправку.

message - Описание ошибки, возвращается со статусом ERROR.

Пример: "message": "'example@mail.com' is not valid email"

3. Пример использования с email сообщением

3.1 Отправка сообщения без параметризации

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

Так, для отправки одного письма тело запроса примет вид:

{
  "recipients": [
    {
      "jsonParam": null,
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

И для двух получателей, соответственно:

{
  "recipients": [
    {
      "jsonParam": null,
      "locator": "example@mail.com"
    }, {
      "jsonParam": null,
      "locator": "new.example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

Для случая, когда поле fromName передается со значением null в письме будет использоваться имя, заданное при добавлении адреса отправителя:

Передача поля jsonParam со значение null свидетельствует о том, что в письме не предполагается или не предусмотрено использования динамической параметризации.

Кроме null jsonParam может содержать JSON объекты, вложенные объекты и вложенные массивы, которые перед отправкой запроса нужно сериализовать, то есть последовательно преобразовать объекты в JSON строку.

3.2 Передача JSON объекта

Формат JSON объекта устанавливается двумя фигурными скобками { }, а данные с ключевыми значениями находятся между ними. Пары ключевых значений имеют двоеточие между собой: {"key" : "value"}. Каждая пара значений разделена запятой, таким образом середина JSON выглядит так: {"key" : "value", "key" : "value", "key": "value"}. 

Для примера, объект из двух пар ключевых значений будет выглядеть так:

{
  "discount": "5%",
  "link": "https://example.site.com/items_for_sale"
}

Для корректной передачи, в теле запроса объект нужно привести к строке, и запрос примет вид:

{
  "recipients": [
    {
      "jsonParam": "{\"discount\":\"5%\",\"link\":\"https:\/\/site.com\/items_for_sale\"}",
      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

Чтобы в сообщении вывести передаваемые значения, нужно воспользоваться velocity конструкцией: $!data.get('discount') и $!data.get('link')

В редакторе сообщений:

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

Вместо переменной discount будет подставлено значение “5%”, а для кнопки вместо переменной link в качестве ссылки будет подставлено значение: “https://site.com/items_for_sale”

3.3 Передача вложенного JSON объекта

Формат вложенного JSON объекта ”objectName”: {"key" : "value", "key": "value"}. 

Пример, вложенных объектов customerData и orderData будет выглядеть так:

{
  "customerData": {
    "firstName": "Сергей",
    "lastName": "Иванов"
  },
    "orderData": {
    "name": "Смартфон Apple iPhone X 64GB Black",
    "cost": 25999,
    "url": "https:\\example.site.com\smartfon-apple-iphone-x-64gb.html",
    "imageUrl": "https:\\example.site.com\smartfon-apple\apple_iphone_x_64gb.jpg"
  }
}

Данные также нужно привести к строке (сериализовать) и запрос примет вид:

{
  "recipients": [
    {
      "jsonParam": "{

\"customerData\":{\"firstName\":\"Сергей\",\"lastName\":\"Иванов\"},
\"orderData\":{\"name\":\"Смартфон Apple iPhone X 64GB Black\",
\"cost\":"25999",\"url\":\"https:\/\/example.site.com\/smartfon-apple-iphone-x-64gb.html\",
\"imageUrl\":\"https:\/\/example.site.com\/smartfon-apple\/apple_iphone_x_64gb.jpg\"}
}",

      "locator": "example@mail.com"
    }
  ],
  "email": true,
  "fromName": null
}

Для отображения данных в сообщении, используем velocity конструкцию вида:

$!data.get('customerData').get('firstName') и $!data.get('orderData').get('name') 

В редакторе сообщений переменные для динамического контента :

В результате подстановки данных, так сообщение увидит получатель:

3.4 Передача вложенного JSON массива

Массивы - упорядоченная коллекция значений, для определения массива используются квадратные скобки [ ],  где значения разделяются запятыми.

Формат вложенного JSON массива ”arrayName”:[{"key":"value", "key":"value"},{...}], в рамках одного запроса может быть передано несколько массивов.

{
  "orderData": [
    {
      "name": "Смартфон Apple iPhone Xs 512Gb",
      "price": "49999",
      "url": "http://example.com/smartfon-apple-iphone-27.html",
      "imageUrl": "http://example.com/apple_iphone_xs_silver.jpg"
    },
    {...},
    {
      "name": "Смарт-часы Apple Watch Series 4 GPS 44mm Space Grey",
      "price": "13699",
      "url": "http://example.com/smart-chasy-apple-watch-series-4-gps-45-2mm.html",
      "imageUrl": "http://example.com/apple_watch_series_4_gps_44mm.jpg"
    }],
  "recommendationsData": [
    {
      "name": "Защитное стекло для смартфона MakeFuture 3D Apple iPhone X/XS",
      "url": "http://example.com/zaschitnoe-steklo-dlja-smartfona-makefuture.html",
      "imageUrl": "http://example.com/makefuture_3d_apple_iphone_xxs_black.jpg",
      "price": "399"
    },
    {...},
    {
      "name": "Ремешок для смарт-часов Apple 44mm Black Sport Band",
      "url": "http://example.com/remeshok-dlja-smart-chasov-apple-44mm.html",
      "imageUrl": "http://example.com/apple_44mm_black_sport_band.jpg",
      "price": "1999"
    }
  ]
}

Важно: Идентично с объектом и вложенным JSON объектом, JSON массив нужно также привести к строке (сериализовать).

Использование массивов предпочтительней при работе с большим количеством данных, которые могут быть сгруппированы вместе. 
Чтобы получить доступ к данным из массива в сообщении нужно использовать конструкцию встроенного в velocity цикла foreach. На примере массива orderData, velocity код примет вид:

// Внутри конструкции будут выведены последовательно данные из каждого элемента массива
#foreach($order in $!data.get('orderData'))
  // Для вывода значения из заказа поля name
  $!order.get('name') 
  // Для поля url
  $!order.get('url') 
  // Для поля imageUrl
  $!order.get('imageUrl')
  // Для поля price
  $!order.get('price')
#end  

Аналогично для массива, в котором передаются рекомендации recommendationsData:

// Внутри конструкции будет выведены последовательно данные из каждого элемента массива
#foreach($recomm in $!data.get('recommendationsData'))
  $!recomm.get('name') 
  $!recomm.get('url') 
  $!recomm.get('imageUrl')
  $!recomm.get('price')
#end

Подготовленное письмо с velocity кодом будет иметь вид:

Результатом подстановки в письмо данных о трех товарах из заказа и трех сопутствующих рекомендациях станет такое письмо:

4. Пример использования с SMS сообщением

Допустим, стоит задача дополнительно уведомить пользователя SMS сообщением о том, что его заказ сформирован и отправлен. 

Тогда формируем тело запроса вида:

{
  "recipients": [
    {
      "jsonParam": "{\"firstName\":\"Сергей\",\"orderId\":\"JN134173389\",\"deliveryAddress\":\"г. Днепр, отделение НП №32\"}",
      "locator": "380501234567"
    }
  ],
  "email": false,
  "fromName": "V-COMP"
}

где в поле locator указываем номер телефона получателя, а в fromName - альфа-имя

Подготовим SMS сообщение в личном кабине:

Так сообщение будет выглядеть с подстановкой данных:

В теле SMS сообщения не всегда рационально выводить все содержимое массива при помощи цикла foreach, поэтому можно обратиться к конкретному элементу массива на примере orderData velocity конструкция примет вид: $!data.get('orderData').get(0).get('name'), где происходит обращение к первому элементу массива (нумерация с 0).

5. Пример использования с Viber сообщением

Процесс настройки идентичен настройке SMS. Необходимо определится с теми данными, которые планируете отобразить в viber сообщении. Но следует учесть, что в отличии от SMS, Viber сообщение позволяет вместить до 1000 символов, отобразить изображение и кнопку, к которой можно добавить ссылку.

В таком случае тело запроса примет вид:

{
    "recipients": [
        {
            "jsonParam": "{
\"firstName\":\"Сергей\",\"orderId\":\"JN134-173-389\",
\"deliveryAddress\":\"г. Днепр, отделение НП №32\",
\"url\":\"https:\/\/example.com\/offers.html\",
\"imageUrl\":\"https:\/\/example.com\/apple_iphone_xs.jpg\"
}",
            "locator": "380501234567"
        }
    ],
    "email": false
}

где в поле locator указываем номер телефона получателя и дополнительно передаем ссылку на изображение в переменной imageUrl и ссылку для кнопки - в переменной url.

Формируем viber сообщение в личном кабинете:

Так сообщение будет выглядеть с подстановкой данных:

6. Пример использования с Mob push уведомлением

Для отправки заранее подготоволенного одиночного мобильного push уведомления тело запроса примет вид:

{
    "recipients": [
        {
            "jsonParam": null,
            "contactId": 449790707
        }
    ],
    "email": false
}

Вместо contactId для идентификации контакта можно использовать locator и в нем передавать токен.

Для мобильного push уведомления на равне с остальными медиа каналами доступна возможность параметризовать содержимое, если передавать данные в поле jsonParam:

Поле Custom data может содержать данные в JSON формате и быть дополнительным источником информации. ​​​На стороне мобильного приложения должна быть поддержана такая возможность использования данных.

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

7. Пример использования с web push уведомлением

Аналогично с запросом для Mob push уведомления, вместо contactId для идентификации контакта можно использовать locator и в нем передавать токен.

{
    "recipients": [
        {
            "jsonParam": null,
            "contactId": 449790707
        }
    ],
    "email": false
}

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

Тело запроса в таком случае будет иметь такой вид:

{
    "recipients": [
        {
            "jsonParam": "{
\"userName\":\"Алексей\",\"productName\":\"Huawei Watch GT Black\",
\"price\":\"6999 грн\",\"https:\/\/example.com\/huawei-watch-gt\/431369.html\",
\"imageUrl\":\"https:\/\/example.com\/gallery\/huawei-watch-gt.jpeg\",
\"logo\":\"https:\/\/example.com\/Your-Logo.jpeg\",
\"moreOffer\":\"https:\/\/example.com\/more-offer.html\"
}",
            "contactId": 380470486
       }
    ],
    "email": false
}