Campaign API

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

Методы Campaign API Exolve для управления рассылками:

• Create — создаёт рассылку;
• GetList — получает список созданных рассылок по заданным параметрам;
• GetInfo — получает информацию об одной рассылке;
• Update — обновляет имя и статус рассылки (в т.ч. отправляет её);
• GetHistory — показывает все коммуникации в рассылке по заданным параметрам;
• DownloadFileTemplate — скачивает шаблон файла со списком контактов;
• UploadContactFile — загружает файл с контактами для рассылки;
• GetFileInfo — получает информацию о загруженном файле со списком контактов;
• DownloadFileError — загружает файл с контактами для рассылки;
• DeleteFile — удаляет файл со списком контактов;
• CreateCallListFromFile — создаёт список контактов из провалидированного файла;
• GetCallList — получает информацию о списке контактов.

Метод Create

Примените этот метод для создания массовой каскадной или SMS-рассылки. Узнайте, как отправить SMS-рассылку в этой инструкции.

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

Точка подключения: Выполните POST-запрос с входными параметрами к точке подключения:

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

Авторизация

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

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

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

Channel

Sms

SmsProps

Текст рассылки можно персонализировать: обратиться к клиенту по имени, указать номер заказа или адрес доставки. Для этого в тексте введите переменные в двойных фигурных скобках. Поддерживается латиница и спецсимволы (кроме пробела). Максимум: 100 переменных.

Например: Здравствуйте, {{name}}! Ваш заказ {{order_number}} будет доставлен {{date}} по адресу: {{address}}

Затем скачайте шаблон файла с помощью метода DownloadFileTemplate, добавьте в него номера получателей и названия этих переменных как заголовки. Для каждого получателя укажите своё значение переменной.

Узнайте, как сэкономить и отправить рассылку по шаблону в этой инструкции.

VoiceMessage

VoiceMessageProps

Cascade

CascadeElement

SmsChannel

VoiceMessageChannel

Condition

Schedule

CallIntervalDays

CallInterval

From/To

Примечание

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

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

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

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

Примеры

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

Канал рассылки - текстовое 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"
}

Метод GetList

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

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

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

Авторизация

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

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

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

CampaignType

CampaignStatus

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

CampaignItem

Channel

Sms

SmsProps

VoiceMessage

VoiceMessageProps

Cascade

CascadeElement

SmsChannel

VoiceMessageChannel

Condition

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

Примеры

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

{
    "date_from" : "2023-12-01T12:40:23.832213Z",
    "date_to" : "2023-12-28T15:40:23.832213Z"
}

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

{
    "items": [
        // Текстовая SMS рассылка
        {
            "id": "130366147371216896",
            "name": "SMS Campaign",
            "scenario_id": "e1b9ae25-f36c-44b8-a327-ac46d414e180",
            "call_list_id": "130366147266359296",
            "timezone": true,
            "type": "1",
            "status": "1",
            "created_at": "2023-12-26T17:48:31.619796Z",
            "sms": {
                "props": {
                    "alpha_name": "SHOP",
                    "text": "Приходите к нам!"
                }
            }
        },
        // Голосовая SMS рассылка
        {
            "id": "130334219200901120",
            "name": "Voice Message Campaign",
            "scenario_id": "bb33e01b-9ec3-4d44-955c-c4cac2d23971",
            "call_list_id": "130334219041517568",
            "timezone": true,
            "type": "CAMPAIGN_TYPE_VOICE",
            "status": "CAMPAIGN_STATUS_IS_STOP",
            "created_at": "2023-12-26T15:41:39.350391Z",
            "voice_message": {
                "props": {
                    "voice_message_id": "41117356-c9d5-4c94-8c62-68d7d2dac285",
                    "from": "79991112233"
                }
            }
        },
        // Каскадная рассылка
        {
            "id": "130369523110653952",
            "name": "Cascade",
            "scenario_id": "a466b60e-ca5a-4da8-b60c-bc9cb9e6fd8a",
            "call_list_id": "130369523102265344",
            "type": "CAMPAIGN_TYPE_CASCADE",
            "status": "CAMPAIGN_STATUS_IS_RUN",
            "created_at": "2023-12-26T18:01:56.458047Z",
            "cascade": {
                "elements": [
                    {
                        "sms": {
                            "props": {
                                "alpha_name": "Shop",
                                "text": "Скидка 10% на все товары!"
                            },
                            "ttl": "10s"
                        },
                        "condition": "1"
                    },
                    {
                        "voice_message": {
                            "props": {
                                "voice_message_id": "353b86e0-a62c-47d4-9b94-8dba32c922fc",
                                "from": "79998889900"
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Метод GetInfo

Примените этот метод для получения информации об одной рассылке. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

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

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

Авторизация

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

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

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

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

CampaignInfo

CallListInfo

CampaignType

CampaignStatus

Channel

Sms

SmsProps

VoiceMessage

VoiceMessageProps

Cascade

CascadeElement

SmsChannel

VoiceMessageChannel

Condition

ContactFileInfo

EventTimestamp

Schedule

CallIntervalDays

CallInterval

From/To

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

Примеры

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

{
    "id": 129931120807677952
}

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

{
    "campaign_info": {
        "id": "129931120807677952",
        "name": "test12356",
        "scenario_id": "5d8eb1f8-0bfa-49a8-9109-e383a5653c42",
        "call_list": {
            "id": "128511757563326464",
            "file_infos": [
                {
                    "name": "contacts.csv",
                    "total": "2",
                    "created_at": "2024-12-21T15:04:37.112Z"
                }
            ],
            "total": "2"
        },
        "type": 3,
        "status": 1,
        "created_at": "2024-12-21T14:59:50.637856Z",
        "cascade_info": {
            "elements": [
                {
                    "voice_message": {
                        "voice_message_id": "366dbec4-c2ab-4a1c-993f-d1d221faec44",
                        "from": "79813340026"
                    },
                    "condition": "1",
                    "step": "1"
                },
                {
                    "sms": {
                        "alpha_name": "test_name",
                        "text": "Test",
                        "ttl": {
                            "seconds": "10",
                            "nanos": 0
                        }
                    },
                    "condition": "",
                    "step": "2"
                }
            ]
        },
         "event_timestamp": {
            "start_at": "2024-12-05T14:02:48.068046975Z",
            "finish_at": "2024-12-05T14:03:20.425123760Z"
        }
    },
    "schedule": {
        "days": {
            "mon": {
                "intervals": [
                    {
                        "from": {
                            "hours": 12,
                            "minutes": 0,
                            "seconds": 0,
                            "nanos": 0
                        },
                        "to": {
                            "hours": 23,
                            "minutes": 30,
                            "seconds": 0,
                            "nanos": 0
                        }
                    }
                ]
            },
        }
    }
}

Метод Update

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

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

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

Авторизация

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

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

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

CampaignStatus

Примечание

• Невозможно начать выполнение рассылки при отсутствии списка получателей.
• Нельзя изменить статус завершённой рассылки.

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

Пустой JSON с 200 OK статусом.

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

Примеры

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

{
    "id": "129883751852937216",
    "name": "SHOP",
    "status": 2
}

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

{}

Метод GetHistory

Примените этот метод для просмотра всех коммуникаций в рассылке по заданным параметрам (если параметры не указаны, выводятся все коммуникации в рамках рассылки). Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

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

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

Авторизация

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

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

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

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

HistoryItem

CallListStatus

Примеры

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

{
    "campaign_id": 129886921253588992
}

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

{
    "campaign_id": "129886921253588992",
    "call_list_id": "129886921245200384",
    "items": [
        {
            "id": "129928904844120064",
            "to": "79991112233",
            "from": "Exolve",
            "timezone": 3,
            "operation_id": "603251350989474631",
            "date": "2026-01-22T15:23:55.356227Z",
            "status": "2"
        },
        {
            "id": "129928904844120065",
            "to": "79995556677",
            "timezone": 6,
            "operation_id": "603251350989474632",
            "date": "2026-01-22T15:27:33.356227Z",
            "status": "6"
        }
    ],
    "limit": 3000,
    "total": "2"
}

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

Метод DownloadFileTemplate

Примените этот метод для получения шаблона файла со списком контактов. Для этого выполните POST-запрос с входными параметрами к точке подключения, указанными ниже.

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

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

Авторизация

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

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

Пустой JSON.

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

File

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

Примеры

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

{}

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

{
    "file": {
        "name": "template.csv",
        "mime_type": "text/csv",
        "content": "bnVtYmVyO3RpbWUgem9uZQo="
    }
}

Метод UploadContactFile

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

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

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

Авторизация

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

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

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

File

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

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

Примеры

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

{
    "campaign_id": "12345",
    "file": {
        "content": "bnVtYmVyO3RpbWUgem9uZQ0KNzk5OTExMTIyMzM7VVRDKzINCjc5OTk0NDQ1NTY2O1VUQys1",
        "mime_type": "text/csv",
        "name": "contacts.csv"
    }
}

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

{
    "file_id": "119362165802627072"
}

Метод GetFileInfo

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

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

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

Авторизация

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

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

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

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

FileStatus

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

Примеры

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

{
    "campaign_id": 129931120807677952,
    "file_id": 130798251019812864
}

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

{
    "id": "130798251019812864",
    "name": "contacts.csv",
    "status": "3",
    "amount_contacts": "2"
}

Метод DownloadFileError

Примените этот метод для скачивания файла с ошибками валидации. Для этого выполните POST запрос с входными параметрами к точке подключения, указанными ниже.

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

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

Авторизация

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

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

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

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

File

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

Примеры

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

{
    "campaign_id": "12345",
    "file_id": "119362165802627072"
}

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

{
    "file": {
        "name": "report_contacts.csv",
        "mime_type": "text/csv",
        "content": "bnVtYmVyO3RpbWUgem9uZTtlcnJvciAobnVtYmVyKQo3OTEzMTIwMjEyMjs7Cjc5MTMxMjAyMTIyO1VUQysyO2R1cGxpY2F0ZQo3OTA1MTIzNDU2NztVVEMrNTsK"
    }
}

Метод DeleteFile

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

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

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

Авторизация

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

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

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

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

Пустой JSON с 200 OK статусом.

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

Примеры

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

{
    "campaign_id": "12345",
    "file_id": "119362165802627072"
}

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

{}

Метод CreateCallListFromFile

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

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

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

Авторизация

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

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

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

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

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

Примеры

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

{
    "campaign_id": 128462752095809536,
    "file_id": 128466384803266560
}

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

{
    "call_list_id": "128462752087420928"
}

Метод GetCallList

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

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

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

Авторизация

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

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

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

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

CallListItem

CallListStatus

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

Примеры

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

{
    "campaign_id": 128484451264724992,
    "call_list_id": 130334219041517568,
    "limit":10
}

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

{
    "campaign_id": "130334219200901120",
    "campaign_name": "test",
    "call_list_id": "130334219041517568",
    "call_list_total": "2",
    "file_name": "contacts.csv",
    "file_upload_at": "2023-12-28T11:25:38.428Z",
    "call_list_items": [
        {
            "to": "79991112233",
            "timezone": 2,
            "status": "1",
            "created_at": "2023-12-28T11:25:49.428275Z",
            "updated_at": "1970-01-01T00:00:00Z"
        },
        {
            "to": "79994445566",
            "timezone": 5,
            "status": "1",
            "created_at": "2023-12-28T11:25:49.428337Z",
            "updated_at": "1970-01-01T00:00:00Z"
        }
    ],
    "limit": 10
}