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

Ресурс Send prepared message позволяет отправлять заранее подготовленное сообщение, указывая его ID в URL запроса. Это может быть письмо о восстановлении пароля, заказе, заброшенном просмотре или корзине, а также уведомление об изменении цены товара, которым интересовался пользователь.

Особенности использования:

• В одном запросе передается до тысячи получателей;
• Сообщения можно персонализировать для каждого получателя данными из запроса;
• Ресурс используется в каналах Email, SMS, Mobile Push, Web Push, Viber, Telegram и App Inbox.

1. Описание запроса
Запрос осуществляется POST-методом по адресу https://esputnik.com/api/v1/message/{id}/smartsend, где {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, номер телефона, Device ID или токен контакта, на который отправлялось сообщение;
• status — результат:
  • OK — если сообщение успешно добавлено в очередь на отправку; о статусе сообщения можно узнать, используя requestId и запрос к ресурсу Get single message status;
  • ERROR — если сообщение не удалось добавить в очередь на отправку, запрос возвращается со статусом ERROR, где message — описание ошибки (например: "message": "example@mail.com' is not valid 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"
        }
    ]
}

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

Ресурс может использоваться для отправки одиночных сообщений с персонализацией и без нее. Для персонализации используется поле jsonParam, которое может содержать объекты JSON, вложенные объекты и массивы, которые перед отправкой запроса нужно сериализировать, то есть последовательно преобразовать объекты в строку JSON.

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

Тело запроса выглядит так:

{
  "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 свидетельствует о том, что в письме не предусмотрено использование динамической персонализации.

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"
    }
  ]
}

Чтобы получить доступ к данным из массива, в сообщении нужно использовать конструкцию встроенного в 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, может вместить до 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. Пример использования с Mobile Push

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

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

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

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

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

7. Пример использования с Web Push

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

{
    "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
}

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

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