Импорт звонков

Читать 17

О методах

Существует 2 метода импорта звонков.

  1. Пакетный импорт со сторонних площадок
  2. Импорт звонков (с привязкой источника по номеру телефона и дате звонка)

Изучите их отличия, чтобы выбрать необходимый для ваших задач.

Первый метод:

  • будет полезен, если звонки проходят не через сайт, а через сторонние площадки, которые самостоятельно фиксируют источник звонка и номера не используются в подмене на сайте
  • можно передавать кастомные источники звонка без сессии, не привязанные к каким-либо номерам из настроенных пулов в личном кабинете Calltouch
  • можно передавать звонки пачками
  • не нужно заранее заводить номера в пулы в личный кабинет Calltouch

Второй метод:

  • если используете собственные телефонные номера, настроенные в Вашей АТС, для отслеживания источников звонков на сайте, их необходимо завести в наш личный кабинет Calltouch
  • кастомные источники звонков будут взяты из названия пула, настроенного в личном кабинете Calltouch
  • один запрос - один звонок

Пакетный импорт со сторонних площадок

Запрос на импорт

После отправки запроса на импорт звонков, они ставятся в очередь и импортируются в порядке очереди. В ответ на запрос импорта вы получите ID лога очереди импорта, по которому отдельным запросом можно будет узнать результат импорта.

POST: https://api.calltouch.ru/lead-service/v1/api/call/import   

HTTP-заголовки:
  • Access-Token – API-ключ
  • SiteId – ID ЛК Calltouch

Тело запроса в формате JSON:

{
    "calls": [

    // Звонок 1

    {
        "referenceId": "Уникальный ID звонка", "sipCallId": "Уникальный ID звонка из АТС",
        "clientPhoneNumber": "Номер телефона клиента",
        "callCenterPhoneNumber": "Номер телефона, на который звонит клиент",
        "callStartTime": "Дата звонка в формате yyyy-mm-dd hh:mm:ss",
        "duration": 120,
        "waitingTime": 10,
        "status": "successful",
        "recordUrl": "Ссылка на запись звонка в формате mp3",
        "comment": {
            "text": "Комментарий"
        },
        "addTags": [
         {
             "tag": "Тег 1"
         }
        ],
        "customSources": {
            "source": "Произвольный источник",
            "medium": "Произвольный канал",
            "campaign": "Произвольная кампания",
            "content": "Произвольное объявление",
            "term": "Произвольная ключевая фраза"
        }, "customFields": [ {"field": "name", "value": "Вася"}, {"field": "birthday", "value": "1990-01-01"} ],
        "sessionId": "ID сессии Calltouch"
    },

    // Звонок N

    ...
    
    ]
}

Параметры запроса

Параметр Формат Обязательный Описание
calls array Да Массив звонков. Можно перечислить до 100 звонков за 1 запрос. После отправки запроса на импорт звонков, они ставятся в очередь и импортируются в порядке очереди. В ответ на запрос импорта вы получите ID лога очереди импорта, по которому отдельным запросом можно будет узнать результат импорта. Обязательно.
calls.referenceId string Да

Уникальный ID звонка. Любые символы, максимум 100.

Обратите внимание!

Необходимо использовать всегда уникальный referenceId для разных запросов. Нельзя повторно загружать звонки с повторным referenceId, даже если ранее загруженный звонок был удален.

calls.
sipCallId
string Нет

Уникальный ID звонка из АТС. Любые символы, максимум 45.

Обратите внимание!

Необходимо использовать всегда уникальный sipCallId для разных запросов. Нельзя повторно загружать звонки с повторным sipCallId, даже если ранее загруженный звонок был удален.

calls.
clientPhoneNumber
string Да Номер телефона клиента в 11-значном формате 7xxxxxxxxxx.
calls.
callCenterPhoneNumber
string Да Номер телефона, на который звонит клиент
calls.callStartTime string Да Дата звонка в формате yyyy-mm-dd hh:mm:ss, например 2020-10-01 02:10:00",
calls.duration integer Да

Полная длительность звонка в секундах включая ожидание.

Обратите внимание, что в ЛК длительность будет показываться, как разница duraton - waitingTime.

calls.waitingTime integer Да Ожидание в секундах.
calls.status string Да

Статус звонка. Возможные значения:

  • successful
  • unsuccessful
calls.recordUrl string Нет Ссылка на запись звонка в формате mp3
calls.comment.text string Нет Комментарий к звонку. Любые символы, максимум 1000.
calls.addTags array Нет

Добавление тегов к звонку. Если такие теги уже есть в ЛК, новые не создаются, а используются существующие. Любые символы, максимум 100 в каждом теги. Максимум 100 тегов.

Формат:

"addTags": [
  {
    "tag": "Тег 1",
    "tag": "Тег 2"
  }
]

calls.customSources object Нет Произвольные источники звонка. Используются только когда не указан sessionId. Необязательно. Если не указан ни sessionId ни произвольные источники, то звонок создается без источника.

calls.customSources.

source

string Да, если указан customSources. Произвольный источник

calls.customSources.

medium

string Да, если указан customSources. Произвольный канал

calls.customSources.

campaign

string Да, если указан customSources. Произвольная кампания

calls.customSources.

content

string Нет Произвольное объявление

calls.customSources.

term

string Нет Произвольная ключевая фраза
calls.sessionId string Нет

ID сессии Calltouch. Любые символы, максимум 100. Если не указано, то заявки будет присвоен произвольный источник customSources.

Подробнее о получении sessionId в статье: Получение id сессии Calltouch

calls.customFields string Нет

Данные по пользовательским полям в звонке.

Формат:

"customFields": [
     {"field": "name", "value": "Вася"},
     {"field": "birthday", "value": "1990-01-01"}
]

В field передается название пользовательского поля в API, в value передается значение пользовательского поля.

Ответ на импорт

Если валидация всех параметров прошла успешно, то запускается процесс импорта звонков и в ответ отдается ID лога очереди импорта, по которому отдельным запросом можно будет узнать результат импорта, пример:

{
    "meta": [],
    "data": {
        "logId": 471
    }
}

Если API-токен не указан, то импорт звонков не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "message": "Ошибка доступа"
    }
}

Если API-токен указан не верно, то импорт звонков не выполняется и выводится ошибка:

{
"meta": [],
"data": {
"message": "Ошибка доступа"
}
}

Если в запросе обнаруживаются ошибки валидации, то импорт звонков не выполняется и выводится ошибка:

{
    "meta": [],
    "data": {
        "type": "validationError",
        "apiErrorData": null,
        "validationErrorData": {
            "violations": [
                {
                    "fieldPath": "calls[0].clientPhoneNumber",
                    "message": "Значение должно быть равно 11 символам."
                }
            ]
        }
    }
}

Запрос на лог импорта

POST: https://api.calltouch.ru/lead-service/v1/api/call/import/log?logId={ID лога}
   
HTTP-заголовки:
  • Access-Token – API-ключ
  • SiteId – ID ЛК Calltouch

GET-параметры:

  • lodId – ID лога импорта звонков

Ответ на лог импорта

{
    "meta": [],
    "data": {
        "calls": [
            {
                "imported": true,
                "referenceId": "5lBNQaPvlR8IKP71", "sipCallId": "asdf-1234-ghk-1234",
                "callId": 2319960
            }
        ]
    }
}

Параметры ответа

Параметр Формат Описание
data.calls.imported boolean Флаг импортирован ли звонок или нет
data.calls.referenceId string ID звонка из API-метода импорта звонков
data.calls.sipCallId string ID звонка из АТС из API-метода импорта звонков
data.calls.callId string ID звонка в Calltouch, может быть null

Импорт звонков (с привязкой источника по номеру телефона и дате звонка)

Как это работает

Если вы желаете использовать собственные телефонные номера, настроенные в Вашей АТС, для отслеживания источников звонков, Calltouch может с легкостью интегрироваться с ней.

Для настройки интеграции вам необходимо отправить заявку вашему личному аккаунт-менеджеру Calltouch либо на почту info@calltouch.net. Укажите в заявке, что вам необходимо получить логин и токен к АТС Calltouch, чтобы импортировать в нее звонки из своей АТС. Далее мы произведем необходимые настройки с нашей стороны и вышлем вам авторизационные данные (логин и токен), по которым вы сможете отправлять http-запросы в нашу АТС и создавать звонки в статистики.

Таким образом, после завершения звонка на ваш номер, ваша АТС будет должна отправлять http-запрос в наш сервис, содержащий всю информацию о поступившем звонке, а Calltouch на своей стороне будет склеивать эту информацию со своими данными о посетителе на сайте, которому был выделен в этот момент времени номер, на который поступил звонок. Таким образом Calltouch установит источник звонка.

Отправка запроса на импорт звонка в Calltouch

HTTP-запрос

https://ats.calltouch.ru/event-service/platform/{ATS_CODE}/inbound-call
   
где, {ATS_CODE} - логин АТС в Calltouch, предоставляется по заявке вашему личному аккаунт-менеджеру Calltouch либо на почту info@calltouch.net.

Поддерживаемые методы отправки: GET.

Передаваемые параметры

Параметр Описание Формат / Значение Обязательный
model Модель обработки вызова.
telemirfact – будет произведена попытка найти источник звонка по дате/времени и номеру телефона, который выделялся в этот момент времени для пользователя из заранее настроенного пула.
sessionfact – будет произведен поиск источника по переданному ID сессии в API-методе
telemirfact, sessionfact Да
apikey 

API ключ, предоставляется по заявке вашему личному аккаунт-менеджеру Calltouch либо на почту info@calltouch.net.

advice_ver2.png Это не тот же самый API-ключ, который вы можете получить в настройках API личного кабинета Calltouch.

- Да
callid

Уникальный идентификатор звонка в вашей АТС.

advice_ver2.png Переданный вами ID звонка из вашей АТС можно впоследствии использовать в параметре callreferenceId API-метода выгрузки звонков.

- Да
callerid  Номер вызывающего абонента (АОН). - Да
ctSessionId

ID сессии Calltouch. Пользователь, отправляющий данный запрос, должен заранее получить ID сессии с сайта, для этого используется JS-функция calltracking_params.

Подробнее о получении sessionId в статье: Получение id сессии Calltouch

Целое число Да, если model=sessionfact
siteId ID сайта в Calltouch. Целое число Да, если model=sessionfact
service В этом параметре вы можете передать то, что будет отображаться в Журнале звонков в качестве номера, на который звонил клиент (или заказывал обратный звонок). Любые символы, максимум 20. Да, если model=sessionfact
phonenumber 

Отслеживаемый номер, на который позвонили (номер, подключенный к Calltouch).

Необходимо указывать в международном формате: 7ХХХХХХХХХХ

- Да, если model=telemirfact
destphonenumber 

Отслеживаемый номер, на который позвонили (номер, подключенный к Calltouch).

advice_ver2.png Это тот же самый номер, который вы отправили в phonenumber выше. Особенности АТС - просто отправляйте его еще раз в этом параметре :)

Необходимо указывать в международном формате: 7ХХХХХХХХХХ

  Да, если model=telemirfact
date  Дата/время вызова. YYYY-MM-DD HH:MI:SS Да
duration  Полная длительность вызова, в секундах. - Да
waitingtime  Время ожидания ответа оператора, в секундах. - Да
status  Статус завершения вызова. successful, unsuccessful Да
clientdtmf  Тоновые dtmf-сигналы со стороны клиента. Могут быть использованы для тегирования звонков в ЛК. - Нет
operatordtmf  Тоновые dtmf-сигналы со стороны оператора. Могут быть использованы для тегирования звонков в ЛК. - Нет
callrecordurl  Ссылка на запись разговора в формате mp3. http url Нет

Создание звонка по номеру телефона клиента и дате/времени звонка

Вы можете создавать звонки в Calltouch по номеру телефона клиента и дате/времени звонка. Для этого используйте параметр model=telemirfact и передавайте соответствующие значения.

Пример заполненных параметров

  • model=telemirfact
  • apikey=dL9juaKJnm4kSNzDhHIxtgeb9ZCxRoDE
  • callid=dfjhvbskdjfvlsdkfjb1233443
  • callerid=74955550101
  • phonenumber=78126007428
  • destphonenumber=78126007428
  • date=2019-02-27%2012:03:00
  • duration=30
  • waitingtime=10
  • status=successful
  • clientdtmf=567,789
  • operatordtmf=123,456
  • callrecordurl=https://test.ru/calltouch/mp3/dialup.mp3

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

https://ats.calltouch.ru/event-service/platform/{ATS_CODE}/inbound-call?model=telemirfact&apikey=dL9juaKJnm4kSNzDhHIxtgeb9ZCxRoDE&callid=dfjhvbskdjfvlsdkfjb1233443&callerid=74955550101&phonenumber=78126007428&destphonenumber=78126007428&date=2019-02-27%2012:03:00&duration=30&waitingtime=10&status=successful&clientdtmf=567,789&operatordtmf=123,456&callrecordurl=https://test.ru/calltouch/mp3/dialup.mp3
   

Пример JSON-ответа на успешный HTTP-запрос:

{
"success": true,
"eventId": 61924734
}

где, значение true параметра success означает успешное выполнение HTTP-запроса, а в параметре eventId содержится идентификатор HTTP-запроса на стороне АТС Calltouch (техническая информация, вам она не пригодится).

advice_ver2.png По импортированному звонку будут доступны все возможности отправки этого звонка из ЛК во внешние сервисы по событию завершения вызова (Webhook'и, amoCRM, Google Analytics и т.д).

Создание звонка по id сессии

Вы можете создавать звонки в Calltouch по id сессии. Для этого используйте параметр model=sessionfact и передавайте соответствующие значения.

Пример заполненных параметров

  • model=sessionfact
  • apikey=dL9juaKJnm4kSNzDhHIdfkvj
  • callid=dfjh21234245vbskdj245fvdfvdfsv
  • callerid=74955550101
  • ctSessionID=12312424234
  • siteId=6969
  • date=2019-02-27%2012:03:00
  • duration=30
  • waitingtime=10
  • status=successful
  • clientdtmf=567,789
  • operatordtmf=7
  • callrecordurl=https://test.ru/calltouch/mp3/dialup.mp3

 

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

https://ats.calltouch.ru/event-service/platform/{ATS_CODE}/inbound-call?model=sessionfact&apikey=dL9juaKJnm4kSNzDhHIdfkvj&callid=dfjh21234245vbskdj245fvdfvdfsv&callerid=74955550101&ctSessionId=12312424234&siteId=6969&date=2019-02-27%2012:03:00&duration=30&waitingtime=10&status=successful&clientdtmf=567,789&operatordtmf=7&callrecordurl=https://alftest.ru/calltouch/mp3/dialup.mp3
    

Возможные ошибки HTTP-запроса

1. Не указан токен apikey или указан некорректно.

HTTP-код ответа: 403 Forbidden

Тело ответа HTML:

<html>
<head>
<title>Error</title>
</head>
<body>Access Denied</body>
</html>
2. Не найден номер телефона destphonenumber, звонок на который необходимо создать.

HTTP-код ответа: 400 Bad Request

Пример тела ответа JSON:

"success": false,
"errors": {
"destphonenumber": [
"Номер телефона 7XXXXXXXXXX не найден"
]
}
}
3. Не указан один из параметров: callid, callerid, siteId, ctSessionId, service, date, duration, waitingtime, status или указан не в верном формате.

HTTP-код ответа: 400 Bad Request

Пример тела ответа JSON:

{
"success": false,
"errors": {
"duration": [
"Wrong format"
],
"waitingtime": [
"Missing data for required field"
]
}
}
4. Сервер АТС не доступен.

HTTP-код ответа: 500 Internal Server Error 

{
"success": false
}
5. Не найден ID сайта или ID сессии, звонок в котором необходимо создать.

Статус: 400 Bad Request

Тело ответа JSON:

{
"success": false,
"errors": {
"ctSessionId": [
"Сессия 191834719834 не найдена"
]
}
}
{
"success": false,
"errors": {
"siteId": [
"Сайт 1223 не найден"
]
}
}

Система баллов API Calltouch

Система баллов API - механизм, регулирующий нагрузку на сервера Calltouch. Для каждого проекта выдается индивидуальное суточное количество баллов За каждый успешно выполненный запрос списываются баллы. Подробнее читайте в статье: Система баллов API Calltouch

Количество запросов в секунду к API Calltouch ограничено – не более 5 запросов в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, а остальные API-запросы завершатся с ошибкой.