Chat API
Chat API отдаёт того же агента, что отвечает в виджете на сайте: та же база знаний, те же инструменты, те же заявки в кабинете и CRM. Вы поднимаете транспорт (WhatsApp, Avito, VK, MAX или свой чат), присылаете сообщение посетителя, получаете ответ и показываете его у себя. Диалоги видны в кабинете в разделе «Диалоги» на вкладке «API», заявки в разделе «Заявки».
Токен выдаётся на сайт в кабинете, раздел «Интеграции», карточка «Chat API». Токен начинается с sk_ и передаётся в заголовке:
Authorization: Bearer sk_ваш_токенТокен серверный. Не вставляйте его в браузерный код и мобильные приложения: любой, кто его увидит, сможет писать агенту от имени вашего сайта и тратить лимит ответов. Перевыпуск токена в той же карточке, старый перестаёт работать сразу.
POST https://aisello.ru/api/v1/chat
Content-Type: application/json
Authorization: Bearer sk_ваш_токен
{
"visitor_id": "wa_79001112233",
"message": "Сколько стоит установка кондиционера?",
"channel": "whatsapp",
"client_msg_id": "3f0c8a2e-1c4b-4a7e-9d2f-0b6a1e5c7d10"
}| Поле | Обязательно | Что это |
|---|---|---|
visitor_id | да | Стабильный идентификатор посетителя в вашем канале, до 64 символов. Диалог ищется по паре visitor_id + channel: тот же id завтра продолжит тот же диалог. Не передавайте телефон в открытом виде, используйте хэш или внутренний id. |
message | да | Текст посетителя. Обрезается до 2000 символов. |
channel | нет | Одно из api, whatsapp, avito, vk, max. Другое значение заменяется на api. Канал виден в кабинете и в аналитике. |
client_msg_id | нет | Ваш уникальный id отправки, до 40 символов. Повтор запроса с тем же id не создаст второго сообщения и не спишет второй ответ, вернётся уже сохранённый ответ. Ставьте всегда, если транспорт может доставить сообщение дважды. |
lang | нет | Язык посетителя в формате BCP 47, например ru-RU. Справочно, агент и так отвечает на языке сообщения. |
page | нет | Адрес страницы вашего сайта, с которой пришёл посетитель. Принимается только URL на домене сайта, остальное отбрасывается. |
{
"reply": "Установка сплит-системы от 5000 рублей, точную сумму подтвердит менеджер. Подскажите, какая площадь помещения?",
"conversation_id": 1042,
"message_id": 58731,
"poll_token": "8De07jreMhrWWNHXkR7iqsI077Q-ysx5",
"lead_saved": false
}| Поле | Что это |
|---|---|
reply | Текст ответа агента. Обычный текст без разметки, ссылки в нём голые. |
conversation_id | Номер диалога в кабинете. |
message_id | Номер ответа агента. Нужен, чтобы передать оценку посетителя. |
poll_token | Секрет диалога. Приходит один раз, в ответе на первое сообщение нового диалога. Сохраните его у себя: по нему читаются ответы менеджера и принимаются оценки. Повторно не выдаётся. |
lead_saved | true, если агент в этом ответе сохранил заявку. Заявка уже в кабинете, письме владельцу и CRM, отдельно ничего слать не нужно. |
operator | true, если диалог передан живому менеджеру. Дальше агент молчит, ответы менеджера читайте опросом (ниже). Если менеджер не ответил за 30 минут, агент возвращается сам. |
products | Список карточек товаров {name, price, url, image}, если у сайта есть каталог и агент решил показать товары. |
payment_url | Ссылка на оплату, если у сайта подключена касса и агент выставил счёт. |
Когда у сайта закончился тариф, исчерпан лимит ответов или дневной бюджет, API отвечает статусом 200 и текстом-заглушкой в reply без conversation_id. Покажите этот текст посетителю как есть.
Менеджер может перехватить диалог в кабинете и отвечать сам. Его реплики не приходят в ответ на /api/v1/chat, их нужно забирать опросом. Разумный интервал 4-5 секунд, пока диалог у менеджера, и реже, когда нет.
GET https://aisello.ru/api/messages?key=PUBLIC_KEY&visitor_id=wa_79001112233&poll_token=...&after=58731key - публичный ключ сайта из кода виджета (начинается с pk_), он же виден в разделе «Виджет». after - номер последнего сообщения, которое вы уже показали. Ответ:
{"messages": [{"id": 58740, "content": "Здравствуйте, это Анна, менеджер. Уточню по срокам."}], "operator": 1}Без верного poll_token ответ всегда пустой, по нему же не узнать, существует ли диалог. С параметром full=1 возвращается вся переписка диалога: {"id", "role", "text", "ts"}, роли user, assistant, operator.
Если в вашем канале есть кнопки «полезно / не полезно», передавайте их сюда: оценки попадают в аналитику владельца.
POST https://aisello.ru/api/rate
{"key": "PUBLIC_KEY", "visitor_id": "wa_79001112233", "poll_token": "...", "message_id": 58731, "rating": 1}rating равен 1 или -1. Ответ {"ok": true}.
visitor_id 20 сообщений в час, дальше 429. Лимит настраивается администратором платформы.visitor_id до 64, client_msg_id до 40. Лишнее обрезается.| Код | Когда | Тело |
|---|---|---|
| 400 | Нет обязательного поля | {"error": "key, visitor_id и message обязательны"} |
| 401 | Нет заголовка или неверный токен | {"error": "неверный api_token"} |
| 429 | Превышен лимит сообщений посетителя | {"error": "Слишком много сообщений подряд..."} |
| 200 | Тариф или лимит ответов исчерпан | {"reply": "Консультант временно недоступен..."} без conversation_id |
curl -s https://aisello.ru/api/v1/chat \
-H "Authorization: Bearer sk_ваш_токен" \
-H "Content-Type: application/json" \
-d '{"visitor_id": "wa_79001112233", "message": "Здравствуйте, вы работаете в субботу?", "channel": "whatsapp"}'import httpx
API = "https://aisello.ru"
TOKEN = "sk_ваш_токен"
def ask(visitor_id: str, text: str, channel: str = "whatsapp") -> dict:
resp = httpx.post(f"{API}/api/v1/chat", timeout=90,
headers={"Authorization": f"Bearer {TOKEN}"},
json={"visitor_id": visitor_id, "message": text, "channel": channel})
resp.raise_for_status()
return resp.json()
data = ask("wa_79001112233", "Сколько стоит установка кондиционера?")
print(data["reply"])
if data.get("poll_token"):
save_poll_token("wa_79001112233", data["poll_token"]) # понадобится для ответов менеджераvisitor_id из идентификатора собеседника в этом канале, одинаковый для всех его сообщений./api/v1/chat и покажите reply собеседнику. Если пришли products или payment_url, добавьте их текстом или карточками канала.poll_token из первого ответа и опрашивайте /api/messages, пока в ответе operator равен 1.