Отправка WHATSAPP

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

Получение WHATSAPP-шаблонов и преобразование в сообщения описано здесь.

Отправка сообщений происходит в режиме чата:

если чат инициируется клиентом, первое сообщение должно соответствовать зарегистрированному шаблону. После каждого ответа абонента открывается 24-часовое окно для отправки сообщений с произвольным содержанием. Если абонент не ответил, клиент может отправлять сообщения пользователю вне рамок 24-часового окна с использованием заранее зарегистрированных шаблонов сообщений;
если чат инициируется абонентом, в течение 24-часового окна клиент может отправлять сообщения с произвольным содержанием.

Отправка WHATSAPP-сообщений

POST https://direct.i-dgtl.ru/api/v1/message

Метод позволяет отправлять массив одиночных сообщений (от 1 до 1000)

Headers

Name

Type

Description

Authorization*

string

Basic {TOKEN_1}

Content-Type*

string

application/json

Request Body

Name

Type

Description

channelType*

string

Канал отправки (WHATSAPP)

senderName*

string

Имя отправителя. Допускаются WHATSAPP-имена в статусе "Одобрено"

destination*

string

Номер абонента

content*

object

Контент сообщения. Ниже описаны возможные варианты содержимого.

tags

array

Теги сообщения (массив строк). Каждый тег должен соответствовать выражению ^\w+$ (допускаются буквы в любом регистре, цифры и нижнее подчеркивание "_")

useLocalTime

boolean

Флаг, отвечающий за таймзону, в которой будет отправлено сообщение: true – отправка в таймзоне абонента false – отправка по МСК По умолчанию true

localSendTime

string

Нижняя граница допустимого времени отправки сообщения (с учетом значенияuseLocalTime) Дата в формате YYYY-MM-DD hh:mm:ss в диапазоне от (текущее время в UTC - 12 часов) до (текущее время в UTC + 7 дней) По умолчанию сообщение будет отправлено сразу

localCompletionTime

string

Верхняя граница допустимого времени отправки сообщения (с учетом useLocalTime) в диапазоне от localSendTime до (текущее время в UTC + 70 дней)

ttl

integer

Время жизни сообщения в секундах. По истечении ttl сообщению устанавливается финальный статус. 60 ≤ ttl ≤ 86400

hours

array

Допустимые часы отправки (массив чисел). В массиве могут быть переданы целые числа от 0 до 23, каждое из которых соответствует разрешенному для отправки интервалу с учетом useLocalTime; значения должны быть уникальны.

days

array

Допустимые дни отправки (массив чисел). В массиве могут быть переданы целые числа от 1 (пн) до 7 (вс), каждое из которых соответствует разрешенному для отправки дню недели; значения должны быть уникальны.

shortUrl

boolean

Флаг, отвечающий за сокращение ссылок в сообщении: true - ссылки в тексте сообщения будут сокращены По умолчанию false

callbackUrl

string

Адрес для отправки callback

callbackEvents

array

События, по которым будут отправлены callback (массив строк). При наличии callbackUrl и отсутствии callbackEvents в запросе, будет отправлен callback по событию delivered.

externalMessageId

string

Внутренний id сообщения в вашей системе. До 100 символов

В случае успешного запроса возвращается ответ, в котором перечислены идентификаторы сообщений и коды результата. При значении errors = false гарантируется, что все переданные сообщения успешно созданы.

{
  "errors": false,
  "items": [
    {
      "messageUuid": "063474ec-a34f-4558-90c5-984395000004",
      "code": 201
    },
    {
      "messageUuid": "063564ec-a34f-4558-90c5-984395000005",
      "code": 201
    }
  ]
}

Использование невалидного токена / отсутствие заголовка авторизации.

{
    "error": {
        "code": 4012,
        "msg": "Bad credentials"
    }
}

Невалидные параметры в теле запроса; ниже приведены несколько примеров ответа.

{
    "error": {
        "code": 4220,
        "msg": "Invalid msisdn"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid text length in viber content (0)"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid caption length in viber content (3)"
    }
}
-----------------------------------------------------------------------------
{
    "error": {
        "code": 4220,
        "msg": "Invalid caption length in viber content (3)"
    }
}

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

Для данного канала рекомендуется использовать ttl не менее 24 часов, так как сервис может доставить сообщение даже спустя 24 часа неактивности абонента (например, если устройство было выключено).

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

Возможные варианты перечислений:

Параметр

Варианты

callbackEvents

События для отправки callback

Текстовое сообщение

Текстовое WHATSAPP-сообщение, помимо текста, может содержать заголовок, подпись и кнопки.

Для отправки текстового WHATSAPP-сообщения используется следующий объект content:

{
  "contentType": "text",
  "text": "текст whatsapp-сообщения",
  "header": {
    "text": "Заголовок сообщения"
  },
  "footer": {
    "text": "Подпись сообщения"
  },
  "buttons": [
    {
      "text": "текст кнопки",
      "url": "https://i-dgtl.ru"
    },
    {
      "text": "текст второй кнопки",
      "phone": "78124269988"
    }
  ]
}

Параметр

Тип

Описание

contentType

string

required

Тип контента (text)

text

string

required

Текст сообщения; строка в кодировке UTF-8 без Byte Order Mark

От 1 до 1000 символов

header

object optional

Заголовок сообщения

header.text

string optonal

Текст для заголовка От 1 до 60 символов

header.documentUrl

string optional

Ссылка на документ для заголовка. Документ должен быть в формате PDF.

header.documentName

string optional

Название документа для заголовка; может присутствовать только при наличии documentUrl

header.imageUrl

string optional

Ссылка на изображение для заголовка. Изображение должно быть в формате JPG или PNG

footer

object optional

Подпись сообщения

footer.text

string optional

Текст для подписи; от 1 до 60 символов

buttons

array (objects) optional

Массив с объектами кнопок

buttons.text

string optonal

Текст кнопки; от 1 до 25 символов

buttons.url

string optional

Ссылка, на которую происходит переход при нажатии на кнопку; от 1 до 1000 символов; должна начинаться с http

buttons.phone

string optional

Телефонный номер, на который предлагается сделать вызов при нажатии на кнопку; от 1 до 1000 символов

buttons.payload

string optional

Скрытый текст, который будет передан во входящем сообщении, если пользователь нажмет на кнопку; от 1 до 1000 символов

Заголовок в сообщениях

в объекте header допускается использовать только одно из:

text
documentUrl и documentName
imageUrl

Кнопки в сообщениях

кнопки передаются объектами в массиве buttons
в каждом объекте обязателен text
существует два типа кнопок:
- кнопка с ссылкой: содержит text и url или text и phone
- кнопка с текстом: содержит text и payload
в одном сообщении допускается передача кнопок только одного типа (то есть передача payload-кнопок вместе с url/phone-кнопками не допускается)
в сообщении допускается только одна кнопка с параметром url
в сообщении допускается только одна кнопка с параметром phone
при передаче кнопок с текстом допускается не более трех объектов в массиве
при передаче кнопок с ссылкой допускается не более двух объектов в массиве
наличие кнопок в сообщении не влияет на возможность наличия заголовка и подписи

Примеры объектов

{
  "contentType": "text",
  "text": "текст сообщения"
}

{
  "contentType": "text",
  "text": "Текст сообщения",
  "header": {
    "imageUrl": "https://example.com/image.png"
  },
  "footer": {
  "text": "Подпись сообщения"
  }
}

{
  "contentType": "text",
  "text": "Текст сообщения",
  "buttons": [
    {
      "text": "текст кнопки 1",
      "payload": "id=1"
    },
    {
      "text": "текст кнопки 2",
      "payload": "id=2"
    }
  ]
}

{
  "contentType": "text",
  "text": "Текст сообщения",
  "buttons": [
    {
      "text": "текст кнопки 1",
      "url": "https://i-dgtl.ru/"
    },
    {
      "text": "текст кнопки 2",
      "phone": "78124269988"
    }
  ]
}

Аутентификационное сообщение

Для отправки аутентификационного WHATSAPP-сообщения используется следующий объект content:

{
  "contentType": "authentication",
  "text": "1234",
  "lang": "ru",
  "addSecurityRecommendation": true,
  "codeExpirationMinutes": 10,
  "buttons": [
    {
      "text": "Скопировать"
    }
  ]
}

Параметр

Тип

Описание

contentType

string required

Тип контента (authentication)

text

string required

Текст сообщения, не более 15 символов

lang

string required

Язык сообщения, не более 2 символов

addSecurityRecommendation

boolean required

Определяет, будет ли сообщение содержать предустановленный текст безопасности

codeExpirationMinutes

integer optional

Срок действия пароля или кода в минутах. Если не указывать этот параметр, сообщение не будет содержать предупреждение об истечении срока действия пароля. Допустимые значения: от 1 до 90.

buttons

array required

Массив кнопок. Должен содержать ровно одну кнопку.

buttons.text

string required

Текст на кнопке, не более 25 символов

Значения параметров lang, addSecurityRecommendation, codeExpirationMinutes, buttons.text должны соответствовать указанным в зарегистрированном шаблоне

Сообщение с изображением

Для отправки WHATSAPP-сообщения с изображением используется следующий объект content:

{
  "contentType": "image",
  "imageUrl": "https://image.png",
  "imageName": "Изображение"
}

Параметр

Тип

Описание

contentType

string

required

Тип контента (image)

imageUrl

string

required

Ссылка на изображение

imageName

string required

Название изображения

Сообщение с документом

Для отправки WHATSAPP-сообщения с документом используется следующий объект content:

{
  "contentType": "document",
  "documentUrl": "https://document.pdf",
  "documentName": "Документ"
}

Параметр

Тип

Описание

contentType

string

required

Тип контента (document)

documentUrl

string

required

Ссылка на документ

documentName

string required

Название документа

Сообщение с видео

Для отправки WHATSAPP-сообщения с видео используется следующий объект content:

{
  "contentType": "video",
  "videoUrl": "https://video.mp4",
  "videoName": "Название видео"
}

Параметр

Тип

Описание

contentType

string

required

Тип контента (video)

videoUrl

string

required

Ссылка на видео

videoName

string optional

Название видео

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

POST https://direct.i-dgtl.ru/api/v1/message
Authorization: Basic QWxhZGRpbjp...
Content-Type: application/json
[
  {
    "senderName": "SENDER",
    "channelType": "WHATSAPP",
    "content": {
      "contentType": "text",
      "text": "Текст WHATSAPP-сообщения",
    },
    "destination": "7818242882",
  }
]

curl -X POST 'https://direct.i-dgtl.ru/api/v1/message' \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic QWxhZGRpbjpvc...' \
-d '[{"senderName":"SENDER","channelType":"WHATSAPP","content":{"contentType":"text","text":"Текст WHATSAPP-сообщения"},"destination":"7818242882"}]'

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

PreviousОтправка PUSH NextОтправка WEASY

Last updated 2 months ago

hashtagОтправка WHATSAPP-сообщений

hashtagHeaders

hashtagRequest Body

hashtagТекстовое сообщение

hashtagЗаголовок в сообщениях

hashtagКнопки в сообщениях

hashtagПримеры объектов

hashtagАутентификационное сообщение

hashtagСообщение с изображением

hashtagСообщение с документом

hashtagСообщение с видео

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

Отправка WHATSAPP-сообщений

Headers

Request Body

Текстовое сообщение

Заголовок в сообщениях

Кнопки в сообщениях

Примеры объектов

Аутентификационное сообщение

Сообщение с изображением

Сообщение с документом

Сообщение с видео

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