Отображение заявок в статистике
Чтобы эффективно анализировать статистику, необходимо отслеживать как можно больше обращений клиентов. А клиенты могут обращаться в Вашу компанию не только посредством звонков, но и оставляя заявки на Вашем сайте. Заявки в Calltouch так же являются составляющей лида. Напомним, что лид в Calltouch это звонок + обратный звонок + заявка. Созданные заявки будут доступны в качестве метрик любого отчета Calltouch, как на графиках:
Так и в таблицах в виде отдельных столбцов:
А так же в отдельном отчете Журнал заявок:
API-метод для создания заявок
Запрос
Поддерживаемые методы отправки: GET и POST.
API-запрос:
Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
API-токен для создания заявок не требуется.
Параметры запроса:
| Параметр | Описание |
| subject |
Произвольное название формы на Вашем сайте, с которой отправляется заявка в Calltouch. В последствие переданное название формы отображается в одноименном столбце журнала заявок:
В качестве названия формы может быть передано строковое значение до 256 символов. |
| requestNumber |
Уникальный идентификатор заявки на Вашем сайте. В качестве идентификатора может быть передано строковое значение до 256 символов. Переданный идентификатор отображается в столбце "Номер заявки" журнала заявок над названием формы:
Параметр является необязательным, если его не передавать, то вместо него в журнале заявок будет отображаться уникальный идентификатор заявки в Calltouch. |
| requestDate |
Дата и время отправки заявки в формате: dd.mm.yyyy%20hh:mm:ss. Дата и время заявки отображается в одноименном столбце "Журнала заявок":
Параметр является необязательным, если его не передавать, то заявке будет автоматически присвоена текущая дата и время отправки API-запроса на создание заявки. |
| sessionId |
Идентификатор сессии Calltouch. С помощью него Calltouch присвоит переданной заявке источник перехода на сайт посетителя, отправившего ее. Идентификатор сессии Calltouch присутствует в коде сайта, с которого отправляется заявка, если в этом коде установлен скрипт отслеживания Calltouch. Получить идентификатор сессии можно обратившись к глобальной JS-переменной window.call_value, пример из консоли Google Chrome:
Обратите внимание, что в примере выше обращение идет не к переменной window.call_value, а к переменной window.call_value_1. Нестандартные названия переменной (_N в конце имени) возможны, когда Ваш один и тот же сайт отслеживается, например, одновременно в несколько личных кабинетах Calltouch. Если в Вашем случае будет использовать как раз такой нестандартный скрипт Calltouch, обратитесь к Вашему аккаунт-менеджеру Calltouch или на почту info@calltouch.net, чтобы узнать так называемый Specific ID - именно он отображается в качестве _N в конце имени переменной window.call_value.
Если в API-запросе на создание заявки передать в параметре sessionId значение undefined, то API-запрос завершиться с ошибкой и заявка не будет создана. В подобных случаях, когда не удается определить источник перехода посетителя на сайт, не передавайте вовсе параметр sessionId при отправке API-запроса на создание заявки. Определившийся источник заявки (с помощью переданного значения сессии) будет отображен в журнале заявок:
Параметр sessionId является необязательным, но если его не передавать, источник заявки не удасться определить как показано на скриншоте выше. |
| fio |
Произвольное имя пользователя, отправившего заявку. Переданное значение отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете имя клиента, то обязательно должны передать хотя бы номер телефона или почту клиента, для его последующей идентификации в журнале заявок. |
| phoneNumber |
Номер телефона. Можно передавать в любом формате, главное чтобы было 11 цифр. Переданный номер автоматически будет приведен к формату 7XXXXXXXXXX и будет отображаться в журнале заявок:
Параметр является необязательным, но если Вы не передаете номер телефона, то обязательно должны передать хотя бы почту или имя клиента, для его последующей идентификации в журнале заявок.
|
|
Почта клиента. Переданная почта отображается в журнале заявок:
Параметр является необязательным, но если Вы не передаете почту клиента, то обязательно должны передать хотя бы номер телефона или имя клиента, для его последующей идентификации в журнале заявок.
|
|
| comment |
Комментарий к заявке. Необязательный параметр. Произвольный текст, в качестве которого может быть передано любое необходимое значение. Переданный комментарий отображается в журнале заявок ЛК, оставленный от имени "API":
|
Если не указано ни одного входного параметра - заявка не будет создана и будет выведена ошибка "Не возможно создать заявку - не указано ни одного входного параметра". HTTP-код ответа ошибки: 200.
Пример GET-запроса на создание заявки
GET-запрос:
Создаст в ЛК Calltouch сайта с идентификатором 18990 следующую заявку:
Формат тела запроса при использовании метода POST
При использовании метода отправки POST, параметры из таблицы выше должны быть перечислены в формате "application/x-www-form-urlencoded":
При использовании метода POST, одним API-запросом можно создать только одну заявку.
Ответ
После успешной отправки API-запроса на создание заявки, возвращается следующий JSON-ответ:
{
"date": 1522047600000,
"requestType": "CLIENT_ORDER",
"dateStr": "26/03/2018 10:00:00",
"session": {
"keywords": "",
"city": "vladimir",
"ip": "95.66.182.68",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:59.0) Gecko/20100101 Firefox/59.0",
"source": "yandex",
"medium": "cpc",
"ref": "",
"url": "http://filipok.io/calltouch/?utm_source=yandex&utm_medium=cpc&attrs={\"attrh\":1,\"ver\":171110,\"r7k12_si\":1156810694}",
"utmSource": "yandex",
"utmMedium": "cpc",
"utmTerm": "",
"utmContent": "",
"utmCampaign": "",
"guaClientId": null,
"yaClientId": null,
"sessionId": 1845461367,
"additionalTags": [],
"attribution": 1,
"attrs": null
},
"subject": "Моя форма",
"uniqTargetRequest": false,
"uniqueRequest": false,
"yandexDirect": null,
"googleAdWords": null,
"requestNumber": "zi0D8c0c",
"requestId": 5222102,
"client": {
"fio": "Вася",
"clientId": 37633316,
"phones": [
{
"phoneNumber": "79205550055",
"phoneType": "OTHER"
}
],
"contacts": [
{
"contactType": "EMAIL",
"contactValue": "vasya@mail.ru"
}
]
},
"orders": [],
"targetRequest": false,
"status": "NOT_SET",
"order": null
}JSON-объекты:
| Объект | Описание |
| date | Дата и время создания заявки в формате Unix Timestamp в миллисекундах. |
| requestNumber | Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте requestId далее). |
| dateStr | Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. |
| session |
Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null. |
| requestId | Уникальный идентификатор заявки в Calltouch. |
| subject | Название формы на Вашем сайте, которое Вы отправили в запросе. |
| uniqTargetRequest | Уникально-целевая заявка. Может принимать следующие значения:
|
| uniqueRequest | Уникальная заявка. Может принимать следующие значения:
|
| client |
Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:
|
| orders | Здесь будет массив всех сделок, связанных с заявкой. На момент создания заявки пустой. |
| targetRequest | Целевая заявка. Может принимать следующие значения:
|
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
API-метод для выгрузки заявок
Посмотреть создавшиеся заявки можно не только в интерфейсе Calltouch, но и получить их выгрузку в формате JSON через API.
Запрос
Поддерживаемый метод отправки: GET.
API-запрос:
Где X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
Параметры запроса:
| Параметр | Описание |
| clientApiId |
Обязательный параметр. В отличие от API-запроса на создание сделки, в API-запросе на их выгрузку требуется указывать токен доступа к статистике Вашего ЛК через API. Уникальный для каждого логина Вашего ЛК. Получить его можно в разделе "Настройки => API" ЛК Calltouch:
|
| dateFrom | Обязательный параметр. Начальная дата создания заявок, с которой они будут выгружены. Формат mm/dd/yyyy. |
| dateTo | Обязательный параметр. Конечная дата создания заявок, до которой они будут выгружены. Формат mm/dd/yyyy. |
| timeFrom | Время начала периода выгрузки в формате hh:mm:ss. Необязательный параметр. |
| timeTo | Время конца периода выгрузки в формате hh:mm:ss. Необязательный параметр. |
| subject | Необязательный параметр. В качестве его значения можно указать название формы, для выгрузки только тех заявок, которые были сделаны с этой формы. Поиск среди заявок происходит по названию формы, которое "начинается с" указанного значения в параметре subject. |
| keywords | Необязательный параметр. В качестве его значения можно указать ключевой запрос, по которому пользователь совершил переход на отслеживаемый сайт и оставил заявку - в этом случае Поиск среди заявок происходит по ключевому запросу, который "содержит" указанное значение в параметре keywords. |
| city | Необязательный параметр. В качестве его значения можно указать название города, для выгрузки только тех заявок, которые были сделаны пользователем из этого города. Поиск среди заявок происходит по названию города, которое "полностью совпадает" с указанным значением в параметре city. Название городов указываются в формате базы данных Sypex Geo. |
| source | Необязательный параметр. В качестве его значения можно указать название источника, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого источника. Поиск среди заявок происходит по названию источника, которое "полностью совпадает" с указанным значением в параметре source. |
| medium | Необязательный параметр. В качестве его значения можно указать название канала, для выгрузки только тех заявок, которые были сделаны пользователем при переходе на сайт с этого канала. Поиск среди заявок происходит по названию канала, которое "полностью совпадает" с указанным значением в параметре medium. |
| bindTo |
Необязательный параметр. Флаг выгрузки заявок с привязкой к разным метрикам. Возможные значения:
|
| ani.value |
Необязательный параметр. В качестве его значения можно указать телефонный номер, для выгрузки только тех заявок, в которых был указан этот телефонный номер. |
| ani.filterMode |
Режим фильтрации предыдущего параметра по номеру телефона, оставленного в заявке. Описание режимов смотри ниже. |
| email.value |
Необязательный параметр. В качестве его значения можно указать электронную почту, для выгрузки только тех заявок, в которых была указана эта электронная почта. |
| email.filterMode |
Режим фильтрации предыдущего параметра по электронной почте, оставленной в заявке. Описание режимов смотри ниже. |
| withMapVisits |
Флаг истории посещений посетителя, оставившего заявку. Формат: withMapVisits=true - включить в ответ историю посещений, withMapVisits=false или отсутствие параметра - не включать. |
| withRequestTags |
Флаг выгрузки тегов, которые были присвоены заявкам. Формат: withRequestTags=true - включить в ответ теги заявок, withRequestTags=false или отсутствие параметра - не включать. |
| withYandexDirect |
Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Яндекс.Директ. Если входной параметр withYandexDirect = true, то в выгрузке присутствует выходной параметр yandexDirect, если withYandexDirect = false или не указан, то выходной параметр yandexDirect отсутствует. |
| withGoogleAdwords | Необязательный параметр. Флаг выгрузки данных по рекламным кампаниям Google AdWords. Если входной параметр withGoogleAdwords = true, то в выгрузке присутствует выходной параметр googleAdWords, если withGoogleAdwords = false или не указан, то выходной параметр googleAdWords отсутствует. |
| withAttrs | Флаг выгрузки сторонних параметров, переданных заранее в статистику Calltouch. Возможные значения: 1. Флаг withAttrs=false или не указан, по умолчанию. Сторонние параметры не выгружаются, значение выходного параметра attrs=null. 2. Флаг withAttrs=true. Сторонние параметры выгружаются в выходной параметр attrs. Если их нет, то значение выходного параметра attrs=null. |
| manager | Необязательный параметр. В качестве его значения можно указать ФИО менеджера, для выгрузки только тех заявок, которым был присвоен этот менеджер с помощью API-метода присвоения менеджеров к лидам. |
Для выгрузки данных только по одной определенной заявки, используйте API-запрос:
Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {requestNumber} - внешний ID заявки. Указывается без фигурных скобок. Его можно получить в JSON-ответе на API-запрос создания заявки.
В качестве параметров, в нем необходимо указать только токен clientApiId (см. таблицу выше).
Режимы фильтрации
Выборку некоторых параметров выше, имя которых параметр.filterMode, можно дополнительно отфильтровать:
- startwith – начинается с
- contains – содержит
- exact – полное соответствие (по умолчанию если фильтр не задан)
Примеры GET-запросов на выгрузку заявок
- Выгрузка нескольких заявок
Запрос далее выгрузит заявки, созданные за период с 28 марта по 4 апреля 2019 года:
- Выгрузка одной заявки
Запрос далее выгрузит заявку с идентификатором 79825254:
Ответ
После успешной отправки API-запроса на выгрузку заявок, возвращается следующий JSON-ответ:
[
{
"date": 1554382259240,
"comments": [
{
"commentId": 7319,
"requestId": 145507,
"comment": "Колин комментарий",
"partyId": 19688,
"partyName": "API"
}
],
"requestType": "CLIENT_ORDER",
"dateStr": "04/04/2019 15:50:59",
"manager": "Вася",
"session": {
"keywords": "(not set)",
"city": "moscow",
"ip": "95.163.114.76/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"source": "(direct)",
"medium": "(none)",
"ref": "",
"url": "https://alftest.ru/calltouch/supertest/",
"utmSource": "<не указано>",
"utmMedium": "<не указано>",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"utmCampaign": "<не указано>",
"guaClientId": null,
"yaClientId": null,
"sessionId": 16441053,
"additionalTags": [],
"attribution": 1,
"attrs": null
},
"subject": "Заявка на звонок",
"uniqTargetRequest": true,
"mapVisits": [
{
"utmSource": "<не указано>",
"sessionDate": "03/04/2019 16:02:51",
"city": "moscow",
"ip": "95.163.114.76/32",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"sessionId": 15952760,
"source": "(direct)",
"medium": "(none)",
"utmCampaign": "<не указано>",
"url": "https://alftest.ru/calltouch/supertest/",
"ref": "",
"additionalTags": [],
"utmMedium": "<не указано>",
"guaClientId": null,
"keyword": "(not set)"
},
{
"utmSource": "<не указано>",
"sessionDate": "04/04/2019 15:50:34",
"city": "moscow",
"ip": "95.163.114.76/32",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"sessionId": 16441053,
"source": "(direct)",
"medium": "(none)",
"utmCampaign": "<не указано>",
"url": "https://alftest.ru/calltouch/supertest/",
"ref": "",
"additionalTags": [],
"utmMedium": "<не указано>",
"guaClientId": null,
"keyword": "(not set)"
}
],
"uniqueRequest": true,
"requestNumber": "145507",
"requestId": 145507,
"client": {
"fio": "Коля",
"clientId": 640236,
"phones": [
{
"phoneNumber": "79991234567",
"phoneType": "OTHER"
}
],
"contacts": [
{
"contactType": "EMAIL",
"contactValue": "kolya@yandex.ru"
}
]
},
"orders": [
{
"orderId": 119901,
"callId": null,
"dateCreated": 1554382620000,
"status": "PENDING",
"realSum": "2800.0000",
"offered": null,
"sent": "04.04.2019",
"sum": "2800.0000",
"isMarked": null,
"commentsCount": 0,
"currentAmount": 2800,
"orderNumber": "119901",
"orderSum": "2800.0000",
"orderStatus": "PENDING",
"orderComments": "",
"session": {
"keywords": "(not set)",
"city": "moscow",
"ip": "95.163.114.76/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"source": "(direct)",
"medium": "(none)",
"ref": "",
"url": "https://alftest.ru/calltouch/supertest/",
"utmSource": "<не указано>",
"utmMedium": "<не указано>",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"utmCampaign": "<не указано>",
"guaClientId": null,
"yaClientId": null,
"sessionId": 16441053,
"additionalTags": [],
"attribution": 1,
"attrs": null
}
}
],
"targetRequest": true,
"status": "NOT_SET",
"order": {
"orderId": 119901,
"callId": null,
"dateCreated": 1554382620000,
"status": "PENDING",
"realSum": "2800.0000",
"offered": null,
"sent": "04.04.2019",
"sum": "2800.0000",
"isMarked": null,
"commentsCount": 0,
"currentAmount": 2800,
"orderNumber": "119901",
"orderSum": "2800.0000",
"orderStatus": "PENDING",
"orderComments": "",
"session": {
"keywords": "(not set)",
"city": "moscow",
"ip": "95.163.114.76/32",
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/73.0.3683.75 Safari/537.36",
"source": "(direct)",
"medium": "(none)",
"ref": "",
"url": "https://alftest.ru/calltouch/supertest/",
"utmSource": "<не указано>",
"utmMedium": "<не указано>",
"utmTerm": "<не указано>",
"utmContent": "<не указано>",
"utmCampaign": "<не указано>",
"guaClientId": null,
"yaClientId": null,
"sessionId": 16441053,
"additionalTags": [],
"attribution": 1,
"attrs": null
}
}
},
...
{
...
}
]JSON-объекты:
| Объект | Описание |
| date | Дата и время создания заявки в формате Unix Timestamp в миллисекундах. |
| comments |
Комментарии к заявкам. Возможные значения:
Где вложенные объекты элемента массива:
Обратите внимание, в конце комментария comment может присутствовать символ \n. Он означает перенос строки, не забудьте учесть это при парсинге параметров. |
| requestNumber | Уникальный идентификатор заявки на Вашем сайте, который Вы отправили в запросе. Если Вы не отправляли данный параметр, в ответе будет содержаться уникальный идентификатор заявки в Calltouch (он же будет и в объекте Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. далее). |
| dateStr | Дата и время создания заявки в формате dd/mm/yyyy hh:mm:ss. |
| manager | ФИО менеджера, который был присвоен заявке с помощью API-метода присвоения менеджеров к лидам. Если у заявки нет менеджера, передается значение null. |
| session |
Объект будет содержать вложенные объекты с описанием посещения, за которым закрепилась заявка. Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, объект будет равен значению null. |
| requestId | Уникальный идентификатор заявки в Calltouch. |
| subject | Название формы на Вашем сайте, которое Вы отправили в запросе. |
| uniqTargetRequest | Уникально-целевая заявка. Может принимать следующие значения:
|
| uniqueRequest | Уникальная заявка. Может принимать следующие значения:
|
| client |
Объект будет содержать вложенные объекты с описанием клиента, данные по которому Вы отправили в запросе. Описание вложенных объектов:
|
| targetRequest |
Целевая заявка. Может принимать следующие значения:
|
| orders |
Массив всех сделок, связанных с заявкой. Для каждой сделки будет содержать вложенные объекты с описанием сделки, связанной с заявкой, если таковые были созданы (см. статью Управление сделками через API). Описание вложенных объектов:
Если Вы не отправляли идентификатор сессии Calltouch в запросе, массив будет пустой. |
| mapVisits |
История посещений. Параметр присутствует в случае, если указан входной параметр истории посещений withMapVisits=true. Результат будет содержать все посещения пользователя оставившего заявку на сайте,
|
| yandexDirect |
Если источник звонка или заявки рекламная кампания Яндекс.Директ, между Calltouch и Яндекс.Директ включена интеграция, то в данном параметре выводится следующая информация:
"yandexDirect": { "campaignId": 32515134, "adGroupId": 325245212134, "adId": 2546356252, "criteriaId": 254251323 } Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались): "yandexDirect": null |
| googleAdWords | Если источник звонка или заявки рекламная кампания Google AdWords, между Calltouch и Google AdWords включена интеграция, то в данном параметре выводится следующая информация:
"googleAdWords": { "campaignId": 35635656, "adGroupId": 134524245, "creativeId": 23134141, "criteriaId": 4324553542 } Пример ответа, когда у звонка или заявки нет этих данных (не настроена интеграция, либо данные еще не собрались): "googleAdWords": null |
| attrs | Сторонние параметры, переданные заранее в статистику Calltouch. Выгружаются, если во входных параметрах был передан флаг withAttrs=true. Возможные значения:
attrs: {"param1":"value1","param2":"value2"}
|
JSON-объекты, не описанные выше, но присутствующие в ответе - являются устаревшими, их следует игнорировать в ответе.
Данные из Яндекс.Директ и Google AdWords подгружаются в Calltouch на следующий день после фиксирования звонка или заявки. Если данные обновляются на стороне Яндекс.Директ или Google AdWords (они могут обновиться 4 раза в месяц), то они будут изменены и в API-выгрузке.
Подключение к отслеживанию заявок с форм сайта
Суть подключения состоит в том, чтобы по событию отправки формы на Вашем сайте, выполнялся скрипт, который будет отправлять в Calltouch API-запрос на создание заявки. Реализовать подключение можно либо на клиентской стороне, либо на серверной. Оба способа описаны далее.
Реализация на клиентской стороне
Данный способ можно использовать, например, когда на сайте средствами JavaScript уже организован обработчик отправки некоторой формы. При ее отправке в рамках данного обработчика выполняется проверка введенных на форме данных. Если валидация формы пройдена успешно, данный обработчик отправляет введенную информацию из формы в обработчик на сервере, где уже происходит обработка полученных данных, например, отправка данной заявки на email менеджера Вашей компании для ее дальнейшей обработки.
В данном случае оптимальным вариантом будет добавление дополнительного скрипта Calltouch в текущий обработчик формы. Обратите внимание, что скрипт отправки заявки в Calltouch необходимо выполнять только при успешном прохождении валидации формы. Ниже представлен пример скрипта для отправки API-запроса на создание заявки средствами JavaScript, используя функцию AJAX библиотеки jQuery:
var ct_node_id = 'X';
var ct_site_id = '{site_id}';
var ct_data = {
fio: 'Иванов Иван Иванович',
phoneNumber: '79000000000',
email: 'test@test.ru',
subject: 'Заявка с сайта',
sessionId: window.call_value
};
jQuery.ajax({
url: 'https://api-node'+ct_node_id+'.calltouch.ru/calls-service/RestAPI/requests/'+ct_site_id+'/register/',
dataType: 'json',
type: 'POST',
data: ct_data
});Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
- ct_data - массив передаваемых входных параметров API-запроса на создание заявки.
Во входных параметрах fio, phoneNumber, email и subject скрипта выше указаны тестовые данные формы. При написании реального скрипта на сайте для отправки заявок в Calltouch, необходимо настроить передачу данных, введенных клиентом на отправляемой форме, в качестве значений соответствующих входных параметров API-запроса на создание заявки.
По умолчанию AJAX-запрос выполняется асинхронно. Если при отправке формы на сайте происходит редирект или обновление страницы, мы рекомендуем использовать синхронный AJAX-запрос, чтобы избежать случаев, когда редирект при отправке формы выполнится быстрее, чем API-запрос на создание заявки в Calltouch. Для этого в AJAX-функцию необходимо добавить параметр async: false.
В случае, если форма на сайте имеет простой функционал и минимальный набор полей, можно организовать скрипт отправки заявок из формы в Calltouch с помощью отдельного внешнего обработчика. Приведем пример скрипта, реализованном с использованием функций библиотеки jQuery, в котором по событию submit некоторой формы будет производится сбор введенных в форме данных и отправка заявки в Calltouch:
<script type="text/javascript">
/* Вешаем обработчик по событию submit формы с идентификатором myform */
jQuery(document).on('submit', 'form#myform', function() {
/* Записываем в переменную form объект с формой, на которой сработало событие submit */
var form = jQuery(this);
/* Ищем на форме input для ввода номера телефона и получаем его значение, в примере поиск производится по наличию у input атрибута name со значением phone */
var phone = form.find('input[name="phone"]').val();
/* Аналогично собираем другие введенные в поля формы данные, например, ФИО и email */
var fio = form.find('input[name="name"]').val();
var mail = form.find('input[name="email"]').val();
/* Указываем название формы */
var sub = 'Заявка на звонок';
/* Указываем ID сайта внутри Calltouch и адрес API-сервера */
var ct_node_id = 'X';
var ct_site_id = '{site_id}';
/* Формируем массив входных параметров запроса */
var ct_data = {
fio: fio,
phoneNumber: phone,
email: mail,
subject: sub,
sessionId: window.call_value
};
/* При необходимости делаем проверку на корректность собранных с формы данных */
/* Например, обязательным для заполнения на форме является поле с телефоном, проверяем его наличие и не пустое ли оно */
if (typeof(phone)!='undefined' && phone!=''){
/* Выполняем AJAX-запрос */
jQuery.ajax({
url: 'https://api-node'+ct_node_id+'.calltouch.ru/calls-service/RestAPI/requests/'+ct_site_id+'/register/',
dataType: 'json',
type: 'POST',
data: ct_data,
async: false /* Предположим, после отправки формы на сайте настроен редирект на другую страницу, поэтому используем параметр async: false для синхронной отправки запроса */
});
}
});
</script>Скрипт выше является примером и требует адаптации под конкретные формы Вашего сайта. Его использование и внесение в него изменений требует наличие на сайте библиотеки jQuery и навыков ее использования.
Реализация на серверной стороне
В случае, если основной функционал обработки, валидации и отправки формы организован на стороне сервера, то можно встроить функционал отправки заявок в Calltouch скриптом на сервере. Приведем пример реализации скрипта на PHP с использованием CURL:
$call_value = $_COOKIE['_ct_session_id']; /* ID сессии Calltouch, полученный из cookie */
$ct_node_id = 'X';
$ct_site_id = '{site_id}';
$ch = curl_init();
curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: application/x-www-form-urlencoded;charset=utf-8"));
curl_setopt($ch, CURLOPT_URL,'https://api-node'.$ct_node_id.'.calltouch.ru/calls-service/RestAPI/requests/'.$ct_site_id.'/register/');
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS,
"fio=".urlencode($_POST['name'])
."&phoneNumber=".$_POST['phone']
."&email=".$_POST['email']
."&subject=".urlencode('Заявка с сайта')
."".($call_value != 'undefined' ? "&sessionId=".$call_value : ""));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$calltouch = curl_exec ($ch);
curl_close ($ch);Где:
- X - номер API-сервера, где расположен Ваш сайт. Его предварительно можно узнать с помощью отдельного API-метода.
- {site_id} - ID Вашего сайта внутри ЛК Calltouch. Указывается без фигурных скобок. Его можно получить в разделе "Настройки => API":
При использование такого метода, следует обратить внимание на 3 пункта:
- ID сессии Calltouch, который необходимо отправить в качестве параметра sessionId API-запроса на создание заявки, необходимо передавать в PHP-обработчик с клиентской стороны, получая значение ID сессии из соответствующей переменной (по умолчанию window.call_value).
- Для корректной передачи кириллических символов в запросе и обхода проблем с кодировкой, необходимо применять PHP-функцию urlencode ко всем PHP-переменным, передаваемым в качестве входных параметров API-запроса. Т.е., если ФИО клиента находится в $_POST['name'], то в API-запрос ее надо добавить как urlencode($_POST['name']).
- В API-запросе в явном виде должна быть указана кодировка utf-8.
Во входных параметрах fio, phoneNumber, email и subject скрипта выше указаны тестовые данные формы соответственно: $_POST['name'], $_POST['phone'], $_POST['email'] и значение "Заявка с сайта". При написании реального скрипта на сервере для отправки заявок в Calltouch, необходимо настроить передачу данных, введенных клиентом на отправляемой форме, в качестве значений соответствующих входных параметров API-запроса на создание заявки.
Видеоинструкция - как подключить заявки с форм сайта за 5 минут
Кол-во запросов в секунду к API Calltouch ограничено – не более 5 запросов (+5 запросов в очередь) в секунду с одного IP-адреса. Например, если в 1 секунду с одного IP-адреса поступит 11 API-запросов, то 5 выполнятся сразу, 5 поставятся в очередь, и 1 API-запрос завершится с ошибкой.
0 Комментарии