Отправка WHATSAPP

Отправка WHATSAPP#

{% hint style=»warning» %} Для получения возможности отправки WHATSAPP-сообщений необходимо заполнить анкету, после чего будет зарегистрировано имя отправителя и шаблон для отправки сообщений.

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

{% hint style=»info» %} Отправка сообщений происходит в режиме чата:

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

Отправка 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 символов

200

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

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

401

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

4012

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

4010

{
    "error": {
        "code": 4010,
        "msg": "Not Authenticated"
    }
}

403

Использование неподходящего токена.

{
    "error": {
        "code": 4030,
        "msg": "Access Denied"
    }
}

422

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

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

402

Payment Required. Недостаточно средств на балансе.

{
    "error": {
        "code": 402,
        "msg": "Insufficient funds"
    }
}

{% hint style=»warning» %} Рекомендуемое время ожидания ответа: 70 секунд.
Как правило, ответ на запрос возвращается не более чем за несколько секунд, но таймаут величиной в 70 секунд позволяет гарантированно получить ответ на запрос, в том числе в ситуациях повышенной нагрузки. {% endhint %}

{% hint style=»danger» %} Для данного канала рекомендуется использовать ttl не менее 24 часов, так как сервис может доставить сообщение даже спустя 24 часа неактивности абонента (например, если устройство было выключено). {% endhint %}

{% hint style=»info» %} Для использования личного домена в сокращенных ссылках необходимо обратиться в поддержку {% endhint %}

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

Параметр	Варианты
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": {
    "documentUrl": "https://example.com/document.pdf",
    "documentName": "document.pdf"
  }
}

С заголовком и подписью

{
  "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 символов

{% hint style=»warning» %} Значения параметров lang, addSecurityRecommendation, codeExpirationMinutes, buttons.text должны соответствовать указанным в зарегистрированном шаблоне {% endhint %}

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

Для отправки 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

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

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

JSON

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

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

{% hint style=»info» %} В примере указан минимальный набор параметров, который позволяет моментально отправить WHATSAPP-сообщение (при наличии зарегистрированного имени отправителя и шаблона). Вы можете кастомизировать контент, время отправки, настроить коллбэки и добавить теги, используя опциональные параметры, описанные выше на данной странице. {% endhint %}

Отправка WHATSAPP

Содержание

Отправка WHATSAPP#

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

Headers#

Request Body#

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

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

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

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

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

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

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

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

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