Session Link

API для разработчиков

Получайте из своих систем прямую ссылку на диалог клиента; если клиента или диалога ещё нет, они создаются.

• WhatsApp
• Instagram
• REST API

Установить из MonoStoreПодробнее на monochat.ai

Обзор

Один вызов API с каналом и номером телефона или email клиента возвращает ссылку, открывающую диалог этого клиента в MonoChat. Если клиента или диалога ещё нет, они создаются.

Поместите ссылку в CRM, службу поддержки или экран заказа, и ваша команда сразу переходит оттуда в чат.

Основные возможности

• Открыть или создать. Работает для клиента в конкретном канале WhatsApp, Instagram или другом — по номеру телефона или email.
• Маршрутизация на лету. Назначьте диалог сотруднику по идентификатору или email либо рабочей группе в том же вызове.
• Тот же клиент — тот же диалог. Повторный вызов для того же клиента и канала возвращает существующий диалог.

Установка и настройка

1. Установите Session Link в разделе Настройки › MonoStore › Приложения или откройте ссылку для установки app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. Если у вас ещё нет аккаунта MonoChat, по ссылке можно сначала зарегистрироваться, и приложение установится автоматически.
2. Создайте API-токен в разделе Профиль › API-токены. Токен показывается только один раз, поэтому скопируйте его сразу. См. API-токены.
3. Откройте Настройки › Session Link API. В документации там указан точный адрес эндпоинта вашего рабочего пространства и готовые для копирования примеры запросов. Попробуйте пример на одном из ваших каналов.
4. Добавьте в CRM, службу поддержки или на экран заказа кнопку «Написать в WhatsApp», которая вызывает API и открывает возвращённый url.

примечание

• Ссылка открывает MonoChat для тех, кто вошёл в систему и имеет право видеть этот диалог.
• Вызов только открывает диалог и не отправляет клиенту сообщение. Чтобы написать первыми, используйте WhatsApp Template API.

Возможности

Ссылка на диалог

В ответе приходят ссылка, открывающая диалог в MonoChat, и идентификатор диалога.

Клиент создаётся при необходимости

Новый клиент создаётся с указанными вами именем и фамилией; в ответе сказано, был ли клиент уже известен.

Назначение

Назначьте сотруднику по идентификатору или email либо рабочей группе.

Экран документации

Справочник API с точным адресом эндпоинта вашего рабочего пространства и готовыми для копирования примерами запросов.

Справочник API

Вызов — это POST с телом в формате JSON, аутентифицированный с помощью API-токена.

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

• <slug> — идентификатор организации (tenant slug) вашего рабочего пространства, часть адреса MonoChat после /tenants/.
• <app-folder> — папка, в которую было установлено приложение. На экране Настройки › Session Link API показан полный адрес с обоими подставленными значениями.
• Создайте токен в разделе Профиль › API-токены. См. API-токены.

Поля запроса

Поле	Обязательное	Описание
connectorBrand	да	Тип канала, например whatsapp или instagram.
channelUsername	да	Имя пользователя вашего канала в MonoChat, например ваш номер WhatsApp без +.
customer.identityType	да	phoneNumber или email.
customer.identity	да	Номер телефона клиента (с кодом страны, без +) или адрес email.
customer.firstname, customer.lastname	нет	Используются, если клиент новый для MonoChat. По умолчанию -.
assignment.type	нет	agent (идентификатор пользователя-сотрудника), agentIdentity (email сотрудника) или workgroup (идентификатор рабочей группы).
assignment.value	вместе с assignment.type	Идентификатор или email, которому назначается диалог.

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

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

Ответ

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

Поле	Описание
url	Открывает диалог в MonoChat.
sessionId	Идентификатор диалога. Один и тот же клиент в одном и том же канале всегда получает один и тот же диалог.
isOldUser	false, если клиент был создан этим вызовом.

Ошибки

Неудачный вызов возвращает статус ошибки и сообщение:

Сообщение	Причина
connectorBrand, channelUsername and customer fields are required	Отсутствует обязательное поле верхнего уровня.
customer.identityType must be one of: phoneNumber, email	identityType отсутствует или имеет другое значение.
customer.identity field is required	Не указан номер телефона или email клиента.
Channel not found	В вашем рабочем пространстве нет канала такого типа с таким именем пользователя.
Customer Channel not found	Не удалось сопоставить клиента с идентификатором в канале.
Agent user not found	Нет сотрудника с email, указанным в assignment.value.
401	Заголовок Authorization отсутствует или токен недействителен.

Скриншоты

CRM, служба поддержки и экран управления заказами открывают нужный диалог в MonoChatНазначение диалога сотруднику или рабочей группе в том же вызове APIНовый клиент и диалог создаются автоматически из запроса APIОдин вызов API возвращает ссылку на диалогКнопка «Написать в WhatsApp» в CRM открывает диалог клиента в один кликПовторный вызов API для того же клиента открывает существующий диалог

Вопросы и ответы

Отправляет ли Session Link сообщение клиенту?

Нет. Он только открывает или создаёт диалог и возвращает ссылку на него. Чтобы написать клиенту первыми, используйте приложение WhatsApp Template API.

С какими каналами он работает?

С WhatsApp, Instagram и другими каналами, подключёнными к вашему рабочему пространству MonoChat. В запросе вы указываете тип канала и имя пользователя вашего канала.

Создаёт ли он дубликаты диалогов?

Нет. Один и тот же клиент в одном и том же канале всегда получает один и тот же диалог.

Кто может открыть ссылку?

Те, кто вошёл в MonoChat и имеет право видеть этот диалог.

См. также

• WhatsApp Template API
• Приложения MonoStore
• Настройки профиля
• Рабочие группы