Посетитель пишет в окне на сайте, реплика приходит вашему приложению уведомлением incomingMessageReceived. Отвечаете вы теми же методами, что в мессенджерах: sendMessage, файлы, правка, реакции. Сверх них у сайта есть подпись автора, кнопки, формы и методы посетителя. Как поставить окно — в статье Чат на сайте.
Посетитель Окно на сайте Gratio Ваше приложение
│ реплика ──────────►│─────────────────────►│── incomingMessage ──────►│
│ │ │◄── sendMessage + author ─│
│◄─ «Алина · ИИ» ────│◄─────────────────────│ │
│ нажал кнопку ─────►│─────────────────────►│── buttonsResponse ──────►│
Что делают общие методы
| Метод | У сайта |
|---|---|
| sendMessage | текст до 4000 знаков, цитата quotedMessageId, подпись author; typingTime — сначала «печатает» до 20 секунд, потом текст |
| sendFileByUpload, sendFileByUrl | JPEG, PNG, GIF, WebP — картинкой в ленте; остальное, в том числе SVG и PDF, — файлом для скачивания. С caption и author |
| editMessage | правка своего сообщения — в окне сразу |
| deleteMessage | у всех: сообщение и его файлы пропадают у посетителя. onlySenderDelete: true — только пометка в журнале |
| sendReaction | реакция компании на любое сообщение чата, один эмодзи; getAllowedReactions отдаёт 10 предложенных |
| sendTyping | «печатает» в окне: typingTime 1000–20000 мс; только у сайта 0 — перестал печатать. С author |
| readChat | вы прочитали реплики посетителя: у него в окне ✓✓ |
| getChatHistory, getMessage | вся переписка с посетителем, вместе с siteMessageData |
| getChats, getContacts | посетители по последней активности, до 1000; имя — как в chatName |
| getContactInfo | имя посетителя из формы или «Посетитель G-7K4MXQ»; номера нет |
Без поддержки, с ответом 501: группы, звонки, истории Telegram, checkAccount, геопозиция, контакт, опрос, пересылка, архив и закреп чатов, поиск и вступление.
Только у сайта
| Что | Где |
|---|---|
| Подпись ответа: ИИ-ассистент, сотрудник или компания | Автор сообщения |
| Кнопки: ответы, ссылки, звонок, копирование | sendInteractiveButtons и sendButtons |
| Форма в ленте: поля, проверка, согласие | sendForm |
| Данные посетителя: страницы, UTM, устройство, согласия | getVisitor |
| Выгрузить и удалить данные посетителя по его просьбе | exportVisitor, deleteVisitor |
| Код вставки и где его видели | getSiteCode |
| Счётчики за 7 дней | getSiteStats |
| Вид окна, тексты, часы работы, согласие | Настройки окна |
Уведомления
| Что пришло | typeMessage |
Формат |
|---|---|---|
| реплика посетителя — текст или файл | textMessage, imageMessage, documentMessage |
Реплика с сайта |
| посетитель нажал кнопку | buttonsResponseMessage |
Ответ кнопкой |
| посетитель отправил форму | formResponseMessage |
Ответ формой |
| ваши кнопки и формы | interactiveButtons, formMessage |
Свои сообщения |
У каждой реплики посетителя есть siteMessageData: номер обращения, страница, UTM, устройство, согласие, «позвал сотрудника».
Статусы своих сообщений (outgoingMessageStatus): sent — записано для окна, delivered — окно посетителя получило, read — посетитель видел: окно открыто, вкладка на экране, лента прокручена вниз. Если окно не открывали, сообщение ждёт следующего визита.
Согласие на обработку данных
По умолчанию галочки нет: под полем ввода и у кнопки формы — строка «Отправляя сообщения в этот чат, вы принимаете политику обработки персональных данных». С первой репликой посетителя Gratio пишет в журнал согласий запись «уведомление принято». Режимы с галочкой и документ согласия — в статье Настройки окна. Журнал согласий посетителя — в getVisitor.
Пределы
| Что | Предел |
|---|---|
| Реплики посетителя | до 10 в минуту и 300 в сутки, текст — до 4000 знаков |
| Файлы посетителя | после первой текстовой реплики; до 10 МБ и до 5 за раз: JPEG, PNG, WebP, GIF, PDF, DOCX, XLSX, PPTX, TXT, CSV |
| Новые посетители с одного адреса | до 20 в час; сверх — первая реплика приходит с suspect: true |
| Посетитель без активности | 90 дней, затем — новый chatId |
Все пределы API — в статье Все лимиты.
Ошибки
| Код | code |
Когда | Что делать |
|---|---|---|---|
400 |
validation |
chatId не вида v…, пустой текст или длиннее 4000, неверный автор, кнопки, форма или настройка, правка чужого сообщения |
исправить запрос |
400 |
not_found |
посетителя или сообщения в этом чате нет | проверить chatId и idMessage |
400 |
not_authorized |
чат снят с сайта | вернуть его в кабинете или siteEnabled: "yes" |
400 |
chat_closed |
посетитель завершил чат в окне или не заходил 90 дней — ответ он не увидит | — |
409 |
idempotency_conflict |
тот же clientMessageId с другим содержимым или автором |
новый ключ для нового сообщения |
501 |
not_supported |
метод, которого у сайта нет | — |
Повтор отправки, принятой раньше, — тот же idMessage даже после chat_closed. Общие правила — в статье Ответы и ошибки.
Что дальше
- Автор сообщения — кто подписан под ответом в окне.
- Реплика с сайта — что приходит в уведомлении.
- JS API окна на сайте — открыть чат и передать данные со страницы.