Какие запросы поддерживает конструктор и как их выполнять.
Некоторые Функции API-запросов можно выполнять в Калькуляторе.
Запросы выполняются методом POST на URL, типа: https://chatter.salebot.pro/api/{api_key}/{action}
Где: api_key ключ доступа к API, который получается в настройках проекта (Рисунок 1)
Получить ключ доступа можно с использованием переменной #{api_key}. В ней хранится актуальный сгенерированный ключ доступа. Не забудьте перед использованием сгенерировать токен.
При копировании url запроса с этой страницы подставляется пробел, который необходимо при вызове удалить.
Пример неправильно скопированной ссылки:
https://chatter.salebot.pro /api/callback
Пробел после .pro не так просто заметить. С ним запрос не будет выполняться
Приотправке запроса методом GET не используйте запрещенные символы. Изучите правильное формирование GET запросов.
Как получать сообщения на Webhook URL, указанный в настройках проекта
Каждое входящее или исходящее сообщение будет приходить следующим json POST запросом:
{
'id': идентификатор сообщения в системе,
'client': {
'id': идентификатор клиента в системе,
'recepient': идентификатор клиента в мессенджере,
'client_type': тип мессенджера,
'name': имя клиента,
'avatar': аватар клиента,
'created_at': дата создания клиента,
'tag': ключ подписки,
'group': бот, к которому привязан клиент,
},
'message': текст сообщения,
'attachments': массив, который содержит ссылки на файлы либо словари ссылок на файлы
'message_id': id блока, из которого было отправлено сообщение
'project_id': идентификатор проекта,
'is_input': 1 если сообщение от клиента, 0 если оно от бота,
'delivered': 1 если сообщение успешно отправлено, 0 если произошла ошибка отправки,
'error_message': текст ошибки отправки сообщения
}
Если запрос вернул ошибку, повторной отправки не будет. Если сервер возвращает ошибки, уведомления продолжат отправляться несмотря на это.
Как написать json-запрос
Переходим в настройки блока, в котором у нас будет осуществляться запись данных таблицу.
Добавляем раздел API-запрос.
Выбираем тип запроса POST-json
Переходим к заполнению полей запроса:
URL запроса - путь к функции для выполнения запроса. Далее в документации всегда в первой строке, рядом с типом запроса:
Сохраняемые значения - перечень параметров ответа запроса с указанием имен переменных, в которые следует сохранить результат в формате:
параметр_из_запроса -> ваша_переменная
Если в ответ получаем параметры сложной структуры, то разбираем их так:
Раньше в наших методах были жестко прописаны параметры, по которым запускались выполнения методов для подписчиков (например client_id и vk_id) и это накладывало некоторые ограничения для использования их со сторонними сервисами.
Теперь вы можете указать, в каком параметре запроса сэйлбот будет искать идентификатор пользователя: для этого используется параметр с префиксом value_, например value_user_id и value_group_id.
А еще метод отправки колбека callback, теперь можно запустить передав электронный адрес (client_email) или телефон (client_phone) клиента.
Методы callback, vk_callback, ok_callback и whatsapp_callback не привязаны к именам параметра. Вы можете указать, в каком параметре будет находиться номер телефона, email или id-клиента.
Это удобно, когда вы настраиваете прием вебхука с какого-то сайта.
Чтобы указать, в какой переменной лежит client_id, необходимо передать параметр value_client_id, в котором указать название параметра с этим значением.
Чтобы указать, в какой переменной лежит phone, необходимо передать параметр value_phone, в котором указать название параметра с этим значением.
Чтобы указать, в какой переменной лежит email, необходимо передать параметр value_email, в котором указать название параметра с этим значением.
Чтобы указать, в какой переменной лежит user_id, необходимо передать параметр value_user_id, в котором указать название параметра с этим значением.
Чтобы указать, в какой переменной лежит group_id, необходимо передать параметр value_group_id, в котором указать название параметра с этим значением.
Как можно заметить, название параметра, в котором лежит имя, отличается припиской value_
Обращаем внимание!
Некоторые события генерируют системное уведомление в проекте.
Например, существуют системные уведомления с message, которые приходят не пустыми, но без текста от клиента.
При этом в проекте также могут генерироваться хуки message с определенным содержанием следующего вида: "message: new_chat_member"
Соответственно, следует обращать внимание на содержание: это либо системное уведомление, либо хук с определенным событием.
Как запускать бота
Запуск бота
POST https://chatter.salebot.pro/api/#{api_key}/callback
URL запроса: https://chatter.salebot.pro/api/#{api_key}/callback
Метод можно использовать для запуска воронки у клиента или подтверждения действия на стороннем ресурсе. Данное сообщение не увидит клиент.
Дополнительно переданные параметры сохранятся в переменные.
Метод отправки колбека, теперь можно запустить передав электронный адрес (client_email) или телефон (client_phone) клиента.
Path
api key* - токен доступа
Body
client_phone - телефон, по которому будет искаться клиент
client_email - email, по которому будет искаться клиент
client_id - id клиента в конструкторе
message - Текст сообщения
resume_bot - True (необязательный параметр). Если бот на паузе, чтобы снять с паузы.
Метод можно использовать для запуска воронки у клиента или подтверждения действия на стороннем ресурсе. Данное сообщение не увидит клиент.
Дополнительно переданные параметры сохранятся в переменные.
Path
api key* - токен доступа
Body
message - Текст сообщения
user_id - id пользователя вконтакте
group_id - id группы вконтакте
resume_bot - True (необязательный параметр). Если бот на паузе, чтобы снять с паузы. Пример: resume_bot = True
Этот метод может запустить вотсап бота, после регистрации клиента на сайте или после того, как он оставит заявку с номером телефона.
Дополнительно переданные параметры сохранятся в переменные.
Path
api key* - токен доступа
Body
name - Имя клиента
message - Текст сообщения
phone - Номер телефона клиента
bot_id - Идентификатор бота
resume_bot - True (необязательный параметр). Если бот на паузе, чтобы снять с паузы. Пример: resume_bot = True
Запуск бота по идентификатору пользователя Одноклассников
POST https://chatter.salebot.pro/api/#{api_key}/ok_callback
Метод можно использовать для запуска воронки у клиента или подтверждения действия на стороннем ресурсе. Данное сообщение не увидит клиент.
Дополнительно переданные параметры сохранятся в переменные.
Path
api key* - токен доступа
Body
name - Имя клиента
message - Текст сообщения
user_id - Идентификатор бота
group_id - ID группы Одноклассников
resume_bot - True (необязательный параметр). Если бот на паузе, чтобы снять с паузы. Пример: resume_bot = True
Запуск бота по идентификатору Telegram
POST https://chatter.salebot.pro/api/#{api_key}/tg_callback
Метод можно использовать для запуска воронки у клиента или подтверждения действия на стороннем сайте. Данное сообщение не увидит клиент.
Дополнительно переданные параметры сохраняются в переменные.
Path
api key* - токен доступа
Body
message - Текст сообщения
user_id - Идентификатор пользователя в Телеграм
group_id - название бота (заканчивается на bot)
resume_bot - True (необязательный параметр). Если бот на паузе, чтобы снять с паузы. Пример: resume_bot = True
Отправка Callback-сообщений списку клиентов по platform_id
POST https://chatter.salebot.pro/api/#{api_key}/send_callback_by_platform_id
При обнаружении в проекте клиентов с platform_id из списка отправит callback с текстом из поля callback_text.
Ограничение: 1 запрос = не более 300 отправлений
Пример параметров запроса:
{"platform_ids":[407184121, "79609879898", "2rwewefw"], "callback_text": "test_callback"}
Path
api key* - токен доступа
Body
platform_ids - список идентификаторов клиентов в мессенджере
callback_text - текст callback
group_id - идентификатор бота
Отправка callback-сообщения email-клиенту
POST https://chatter.Salebot.pro/api/#{api_key}/email_callback
Этот метод может запустить email-бот после регистрации клиента на сайте или после того, как он оставит заявку с email, при этом метод находит email-клиента или создает его, если тот не найден.
Дополнительно переданные параметры сохранятся в переменные
Path
api key* - токен доступа
Body
name - имя клиента
message - текст сообщения
email - адрес почты
email_id_bot - email-адрес бота
resume_bot - True (необязательный параметр).
Если бот на паузе, чтобы снять с паузы.
Пример: resume_bot = True
Как работать с сообщениями
Параметры отправки сообщения
attachment_type может принимать значения: image, video, link, file, audio
При отправке вложения параметр message необязателен
buttons - определяет кнопки, которые будут прикреплены к сообщению. Формат кнопок аналогичен расширенным настройкам кнопок. Возможны два варианта передачи кнопок: с указанием подсказки для мессенджеров без кнопок и без нее.
Этот метод можно использовать для отправки сообщений с уведомлениями. Параметр message обязателен, если вы не отправляете файл. Если вы отправляете файл, текст необязателен.
Path
api key* - токен доступа
Body
message_id - Номер блока для отправки
message - Текст сообщения
client_id - id клиента в конструкторе
attachment_type - Тип отображения файла. Обязательный, если передан attacment_url
attachment_url - url файла
buttons - Кнопки
import requests
import json
params = {"message": "some_text", "client_id": "25554"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.salebot.pro/api/{token}/message'
requests.post(url, json=params)
ЕСЛИ отправляем вложение:
params = {"message": "какое-нибудь сообщение",
"client_id": "1234565", "attachment_type": "video/image/file",
"attachment_url": "https://qwreqw"}
token = 'b551e18c8b8e86bea6f14f38de3f5cc3c31ba1edb4d8'
url = f'https://chatter.salebot.pro/api/{token}/message'
requests.post(url, json=params)
//где в attachment_type указываем либо video, либо image, либо file -
в зависимости от того, какое вложение: видео, картинка или документ
Отправка сообщения в Whatsapp
POST https://chatter.salebot.pro/api/<api_key>/whatsapp_message
Позволяет отправить сообщение от имени подключенного бота на указанный номер
whatsapp_bot_id необходимо взять из раздела мессенджеры и чаты. Каждому подключенному вотсапу конструктор присваивает уникальный идентификатор.
Path
api key* - токен доступа
Body
message_id - Номер блока для отправки
whatsapp_bot_id - Идентификатор вотсап бота, от которого нужно отправить сообщение
attachment_url - url файла
attachment_type - Тип отображения файла. Обязательный, если передан attacment_url
message - Текст сообщения
phone - Номер телефона получателя
Можно использовать один из вариантов, они взаимоисключающие:
1. передан параметр list - рассылка будет произведена по указанному списку клиентов
Метод позволяет запустить рассылку.
2.передан параметр clients - рассылка будет произведена по массиву переданных идентификаторов клиентов
3.передан параметр platform_ids и group_id - рассылка будет произведена по массиву переданных platform_id (идентификатор в мессенджере) указанного бота (group_id)
4.Если не передан ни один из выше перечисленных, рассылка будет произведена по всем клиентам
Обязательный параметр message (и\или attachment_type и attachment_url) ИЛИmessage_id
Path
api key* - токен доступа
Body
list - Номер списка, по которому необходимо разослать
clients - Идентификаторы получателей в конструкторе
message - Текст сообщения
platform_ids - Идентификаторы получателей в мессенджере. Вместе с ним передать обязательный параметр group_id
group_id - Обязательный, работает только с platform_ids. При работе с другими вариантами - игнорируется. Для отправки по platform_ids указанного бота.
attachment_url - url файла
attachment_type - Тип отображения файла. Обязательный, если передан attacment_url
buttons - кнопки
message_id - Номер блока для отправки
shift - Количество секунд между сообщениями. По умолчанию 0.2
Метод позволяет загрузить клиентов в систему. При загрузке клиентов whatsapp можно передавать номер в свободном формате, как с концовкой @s.whatsapp.net, так и без нее.
Идентификатор группы (group_id) можно получить ТУТ через /api/<api_key>/connected_channels
(если client_type=13 (телефония), то group_id="")
Тип мессенджера, откуда пришел клиент (client_type) можно посмотреть ТУТ
offset - Смещение относительно первого элемента
limit - Количество элементов в ответе/ По умолчанию 500, максимальное значение 500.
list - номер списка
reverse - указание обратной сортировки(от самой "старой" записи к самой "новой"). Параметр работает при отсутствии параметра list
Получение информации о клиентах из выбранного мессенджера.
Внимание! метод не возращает переменные!
Path
api key* - токен доступа
Body
page
tag - Tag, который был указан на подписочной странице
group - ID группы вк, к которой привязан подписчик
date_from - После какой даты подписался. timestamp
date_to - До какой даты подписался timestamp
client_type - идентификатор мессенджера, для которого нужно узнать список подписчиков. Если ничего не передать - выведет всех клиентов
Получение информации о клиентах из мессенджера Вконтакте. Метод был написан специально для интеграции с Eresh.
Внимание! метод не возращает переменные!
Path
api key* - токен доступа
Body
page
tag - Tag, который был указан на подписочной странице
group - ID группы вк, к которой привязан подписчик
date_from - После какой даты подписался. timestamp
date_to - До какой даты подписался timestamp
Позволяет сохранить переменные в заявку и в клиента.
Запрос присвоения переменных по умолчанию добавляет в переменные сделок.
И если нужно изменить переменные в профиле, нужно прописывать префикс client. Например, для телефона: client.phone
Update:Параметр clients позволяет массово присваивать переменные.
Этот метод позволяет интегрировать сайт и чат-бота. Например, если человек зашел на страницу с акцией, прислать сразу же сообщение в чат о персональном предложении.
Path
api key* - токен доступа
Body
tag - Тег (метка клиента)
name - Имя клиента
recipient - Идентификатор диалога на сайте
Где взять recipient?
На сайте, где размещен онлайн чат "Salebot.pro" при помощи JS получите свойство SaleBotPro.recipient_id
{ "client_id": 36553 }
Получение client_id по номеру Whatsapp
GET https://chatter.salebot.pro/api/#{api_key}/whatsapp_client_id?phone=
Метод вернет идентификатор клиента для выполнения запросов к API, если вы знаете номер телефона клиента в Whatsapp
Если клиента нет с таким номером, то метод вернет 404
Path
api key* - токен доступа
Body
phone - Номер телефона
group_id - Идентификатор бота
Получение client_id по номеру телефона
GET https://chatter.salebot.pro/api/<api_key>/find_client_id_by_phone?phone=
Метод вернет идентификатор клиента для выполнения запросов к API
Path
api key* - токен доступа
Body
var - Имя переменной, по которой будет поиск
val - Значение переменной
group_id - Идентификатор группы
search_in - Передать значение 'order' для поиска по переменным сделки; Ищет до 3-х переменных у клиентов проекта, возвращает список клиентов, у которых есть все заявленные переменные.
Получение id последнего созданного клиента по значению переменной
GET https://chatter.salebot.pro/api/#{api_key}/find_latest_client_id_by_var?var=&val=
Метод осуществляет поиск по переменным, вернет список идентификаторов клиентов, удовлетворяющих условию запроса.
Примеры параметров: по умолчанию поиск производится по переменным клиента (рекомендуется)
{"q": {"result": "ok", "var": "дом", "var": "60"}} - поиск по переменным клиента, у клиента должны быть все указанные переменные
{"q": {"result": "ok", "var": "дом", "var": "60"}, "search_in": "order", "include_all": False} - поиск по переменным сделок ("search_in": "order"), в сделке должны быть хотя бы одна из указанных переменных ("include_all": False)
{"q": {"name": {"_in": ["Joe", "Jane", "Donald"]}}} - переменная клиента name равна одному из значений списка ["Joe", "Jane", "Donald"]
{"q": {"name": {"_not_in": ["Joe", "Jane", "Donald"]}}} - переменная клиента name НЕ равна одному из значений списка ["Joe", "Jane", "Donald"]
{"q": {"name": {"_not": "Joe"}}} - переменная клиента name не равна Joe
Внимание!
Сравнение чисел возможно только, если у всех клиентов в искомой переменной число. Если хотя бы у одного будет строка, запрос не отработает.
Параметры
Path
api key* - токен доступа
Body
q - обязательный параметр, query условия на поиск переменных
search_in - по переменным какой сущности искать, если не передать ищет по переменным клиента, может принимать значение order
include_all - обязательное выполнение всех условий из параметра q,
False - если одно из условий совпало, отбирает сущность
Успешно
{"status":"success","client_ids":[41203, 5622354, 785212]}
{"status":"success","client_ids":[]}
{"status": "fail", "message": "Parameter "q" required"} {"status": "fail", "message": "Error in parameter format"}
Ошибка
{"status":"fail","message":"Something went wrong"}
Как работать со сделками
Получение идентификатора текущей сделки
GET https://chatter.salebot.pro/api/#{api_key}/get_current_order_id
Ответ в случае успеха:
{"status":"success","state_id":37}, где
state_id - идентификатор состояния в SalebotCRM
Ответ с ошибкой:
{"status":"client_not_found"}
Получение данных сделки
POST https://chatter.salebot.pro/api/#{api_key}/get_order_vars
При запросе необходимо указать один из следующих параметров: client_id, email, phone. Если указать несколько из этих параметров, использоваться будет только один. Приоритет использования в порядке убывания: client_id > phone > email.
Если указан phone или email, и клиента с таким телефоном или почтой нет, будет создан новый клиент.
Успешный ответ: {"status":"success","order_id":40654},
где order_id идентификатор новой активной сделки
Ответ с ошибкой: {"status":"client_not_found"}
Перенос сделки в состояние SalebotCRM
POST https://chatter.salebot.pro/api/#{api_key}/set_order_state
Функция возвращает к каждому мессенджеру параметр group_id, именно его необходимо передавать при загрузке клиентов.
Для Whatsapp также возвращается поле status, которое принимает значения:
NOT_STARTED = 0
STARTED = 1
ASLEEP = 2
STOPPED = 3
?delimiter=1 - параметр со значением. Данное значение разделяет ключи {key1}1{key2}1{key3}
delimiter_value_client_id={key1}1{key2} - получение ID клиента;
delimiter_value_phone={key1}1{key2} - получение номера телефона клиента;
{key1} - ключ, в который вкладывается значение с ЛЮБЫМИ символами, кроме символов, лежащих в параметре. Ключей может быть неограниченное количество:
?delimiter=1&delimiter_value_client_id={key1}1{key2}1{key3}1{key4}1{key5}1{key6}.
Ключ передается БЕЗ фигурных скобок.
Между ключами передавайте заданное значение delimiter!
если delimiter=2, то {key1}2{key2}2{key3}2,
delimiter=5, то {key1}5{key2}5{key3}5.
При присвоении значения delimiter=5, в ключе не должно быть символа 5 и т.д.