Create

Метод Create

Примените этот метод для создания массовой каскадной или SMS-рассылки. Каскадная рассылка — это автоматизированная последовательная отправка уведомлений через голосовой и текстовый каналы. Например, можно запустить обзвон, а тем, до кого не получилось дозвониться, отправить SMS. Так вы быстрее сможете донести нужную информацию до ваших клиентов удобным для них способом.

Для создания рассылки выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

Точка подключения:

POST: https://api.exolve.ru/campaign/v1/Create

Авторизация

Передайте следующие Заголовки HTTP для успешной авторизации.

Имя Тип Описание
Authorization string API-ключ приложения с Bearer перед ним. Пример: Bearer e***s0, где e***s0 замените на API-ключ вашего приложения

Входные параметры

Передайте следующие параметры в теле запроса в JSON-формате. Параметры, отмеченные жирным шрифтом, являются обязательными.

Параметр Тип Описание
name string наименование рассылки
timezone boolean параметр учёта часового пояса. По умолчанию False - рассылка отправляется по московскому времени (UTC+3), True — учитывать часовой пояс, указанный в списке контактов
schedule Schedule расписание рассылки
oneof Channel один из каналов рассылки (текстовое SMS, голосовое SMS или каскадная рассылка)

Channel

Параметр Тип Описание
sms Sms канал рассылки — текстовое SMS
voice_message VoiceMessage канал рассылки — голосовое SMS (исходящий обзвон с предзаписанным аудио)
cascade Cascade каскадная рассылка (комбинация текстового и голосового каналов для последовательного уведомления абонентов)

Sms

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS

SmsProps

Параметр Тип Описание
alpha_name string согласованное операторами имя, от которого отправляются текстовые SMS
text string текст сообщения

VoiceMessage

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

VoiceMessageProps

Параметр Тип Описание
voice_message_id string идентификатор ресурса голосового SMS
from string номер телефона Exolve, с которого отправляются голосовые SMS

Cascade

Параметр Тип Описание
elements CascadeElement структура каскадной рассылки. Один элемент (шаг) — один канал рассылки (текстовое или голосовое SMS). Максимум — 10 шагов

CascadeElement

Параметр Тип Описание
sms Sms канал рассылки — текстовое SMS
voice_message VoiceMessageChannel канал рассылки — голосовое SMS
condition enum Condition условие перехода к следующему каналу рассылки

SmsChannel

Параметр Тип Описание
props SmsProps атрибуты сценария текстового SMS
ttl string период времени в формате ’60s’, по истечении которого будет запрошен статус SMS (от 10 до 300 секунд).

VoiceMessageChannel

Параметр Тип Описание
props VoiceMessageProps атрибуты сценария голосового SMS

Condition

Параметр Тип Описание
1 enum звонок не принят/SMS не доставлено
2 enum звонок принят/SMS доставлено
3 enum в любом случае

Schedule

Параметр Тип Описание
days CallIntervalDays настройка интервалов рассылки по дням недели

CallIntervalDays

Параметр Тип Описание
mon CallInterval интервал понедельника
tue CallInterval интервал вторника
wed CallInterval интервал среды
thu CallInterval интервал четверга
fri CallInterval интервал пятницы
sat CallInterval интервал субботы
sun CallInterval интервал воскресенья

CallInterval

Параметр Тип Описание
from From/To время начала рассылки
to From/To время завершения рассылки

From/To

Параметр Тип Описание
hours uint32 час интервала
minutes uint32 минута интервала
seconds uint32 секунда интервала
nanos uint32 наносекунда интервала

Примечание

Если вы создаёте рассылку во время одного из указанных интервалов, рассылка будет запущена только при наступлении следующего интервала. Например, если вы создаете рассылку с расписанием с понедельника по среду с 10:00 по 13:00 МСК в понедельник в 10:30 МСК, то первая рассылка будет запущена только на следующий день, то есть во вторник в 10:00 МСК.

Если при создании рассылки вы не укажете интервалы расписания, рассылка будет запускаться по расписанию по умолчанию - с понедельника по пятницу с 9:00 до 18:00 МСК.

Выходные параметры

Параметр Тип Описание
campaign_id uint64 идентификатор рассылки

Возможные ошибки

Код Статус Пример сообщения Описание
404 Not Found Not Found некорректный URL запроса
401 Unauthorized invalid token невалидный API-ключ
400 Bad Request token is empty в запросе не передан API-ключ
400 Bad Request couldn’t parse incoming jwt token: couldn’t parse token: invalid character ‘[character]’ looking for beginning of value невалидный API-ключ
404 Not Found invalid alpha name: alpha name is not found введённое имя отправителя (альфа-имя) для текстовой SMS не принадлежит приложению
404 Not Found invalid number: number not found введённый номер телефона для голосовой SMS не принадлежит приложению
404 Not Found couldn’t find voice message scenario [voice_message_id]: scenario not found введённый идентификатор ресурса голосового SMS не принадлежит приложению
409 Conflict couldn’t create campaign: campaign already exists рассылка с указанными параметрами уже существует
400 Bad Request invalid SmsProps.AlphaName: value length must be between 3 and 11 runes, inclusive поле alpha_name содержит некорректное количество символов (корректно от 3 до 11 символов)
400 Bad Request invalid VoiceMessageProps.From: value length must be between 1 and 14 runes, inclusive поле from содержит некорректное количество символов (корректно от 1 до 14 символов)
400 Bad Request invalid CreateRequest.Name: value length must be between 3 and 40 runes, inclusive поле name содержит некорректное количество символов (корректно от 3 до 40 символов)
400 Bad Request invalid value for string type: [value] невалидное значение в одном из полей
400 Bad Request invalid character " after object key:value pair в запросе пропущена запятая в одном из параметров

Примеры

Входные параметры:

Канал рассылки - текстовое SMS

{
    "name": "test",
    "timezone": true,
    "sms": {
        "props": {
            "alpha_name": "shop",
            "text": "Приходите к нам в магазин!"
        }
    }
}

Канал рассылки - голосовое SMS

{
    "name": "test",
    "timezone": true,
    "voice_message": {
        "props": {
            "voice_message_id": "41117356-c9d5-4c94-8c62-68d7d2dac285",
            "from": "79991112233"
        }
    }
}

Каскадная рассылка

{ 
    "name": "Рассылка с расписанием",
    "cascade": {
        "elements": [
            {
                "sms": {
                    "props": {
                        "alpha_name": "shop",
                        "text": "Приходите к нам!"
                    }
                },
                "condition": "1"
            },
            {
                "voice_message": {
                    "props": {
                        "voice_message_id": "353b86e0-a62c-47d4-9b94-8dba32c922fc",
                        "from": "79991112233"
                    }
                }
            }
        ]
    },
    "schedule": {
        "days": {
            "mon": {
                "intervals": [
                    {
                        "from": {
                            "hours": 10,
                            "minutes": 0,
                            "seconds": 0,
                            "nanos": 0
                        },
                        "to": {
                            "hours": 15,
                            "minutes": 30,
                            "seconds": 0,
                            "nanos": 0
                        }
                    }
                ]
            }
        }
    }
}

Выходные параметры:

{
    "campaign_id": "130370354778222592"
}

Содержание статьи