Окно чатов (iFrame)

В статье рассказываем, как внедрить окно чатов Wazzup в свою CRM и настроить работу «чемодана» по событиям.

Мы рекомендуем работать с «чемоданом» с помощью вебхуков. А если вебхуки не подходят — по событиям.

Как внедрить окно чатов Wazzup в свою CRM

Чтобы получить ссылку, по которой откроется окно чатов, необходимо вызвать:

 POST https://api.wazzup24.com/v3/iframe
Параметры запроса
Параметр

Обязательные параметры отмечены «звездочкой»

Тип Описание
user* Object Объект, который содержит информацию о пользователе
user.id* String ID пользователя в CRM, который открывает окно с чатами
user.name* String Имя пользователя. Далее будет использовано как имя отправителя
scope* String Контекст, в котором открывается окно, где:

  • global для окна со всеми доступными пользователю чатами,
  • card для чата, который открывают из сделки, контакта или другой карточки.
filter Object (Array) Массив объектов с чатами, которые нужно показать. Обязателен, когда scope = card
filter.chatType String Тип чата. Доступные значения:

  • whatsapp — для индивидуальных чатов в WhatsApp,
  • whatsgroup — для групповых чатов в WhatsApp,
  • instagram — для чатов в Инсте,
  • telegram — для индивидуальных чатов в Telegram,
  • telegroup — для групповых чатов в Telegram,
  • vk — для чатов Вконтакте,
  • avito — для чатов Авито
filter.chatId String ID чата (аккаунт контакта в мессенджере):

  • для whatsapp — только цифры, без пробелов и специальных символов в формате 79011112233,
  • для instagram — аккаунт без @ вначале,
  • для whatsgroup — приходит в вебхуках входящих сообщений,
  • для telegram — приходит в вебхуках входящих сообщений и в ответ на запрос при отправке исходящего с параметрами phone или username. Об этих параметрах пишем далее,
  • для avito и vk приходит в вебхуках входящих сообщений
filter.username String Только для Telegram.

Имя пользователя в Telegram, без @ в начале. Можно использовать при отправке сообщений через Telegram, если неизвестен chatId

filter.phone String Только для Telegram.

Номер телефона в Telegram, без пробелов и специальных символов. Только цифры. Например, 79111234567.

Можно использовать при отправке сообщений через Telegram, если неизвестен chatId

filter.name String Имя контакта
activeChat Object Чат, активный при открытии iFrame
activeChat.channelId String Идентификатор канала, c которым нужно открыть активный чат
activeChat.chatType String Тип чата. Доступные значения:

  • whatsapp — для индивидуальных чатов в WhatsApp,
  • whatsgroup — для групповых чатов в WhatsApp,
  • instagram — для чатов в Инсте,
  • telegram — для индивидуальных чатов в Telegram,
  • telegroup — для групповых чатов в Telegram.
activeChat.chatId String Id чата (аккаунт контакта в мессенджере):

  • для whatsapp — только цифры, без пробелов и специальных символов в формате 79011112233,
  • для instagram — аккаунт без @ вначале,
  • для whatsgroup — приходит в вебхуках входящих сообщений,
  • для telegram — приходит в вебхуках входящих сообщений и в ответ на запрос при отправке исходящего с параметрами phone или username. Об этих параметрах пишем далее.
activeChat.username String Только для Telegram.

Имя пользователя в Telegram, без @ в начале. Можно использовать при отправке сообщений через Telegram, если не известен chatId

activeChat.phone String Только для Telegram.

Номер телефона в Telegram, без пробелов и специальных символов. Только цифры. Например, 79111234567.

Можно использовать при отправке сообщений через Telegram, если неизвестен chatId

options Object Настройки по событиям в iframe. 

Обязателен, если решили создавать контакты и сделки по событиям

options.clientType String Тип CRM. Можно ничего не указывать
options.useDealsEvents Boolean Укажите true, если хотите узнавать от iframe, что надо создать или показать пользователю сделку.

Событие приходит, когда пользователь кликает:

  •  на + в «чемодане», чтобы создать сделку из нашего iframe, 
  •  на сущность в «чемодане», чтобы ее открыть.
options.useMessageEvents Boolean Укажите true, если хотите узнавать от iframe, что надо создать новый контакт.

Событие приходит, когда пользователь отвечает на входящее сообщение из нашего iframe

Если контакта с указанными chatType и chatId нет в базе данных Wazzup — при открытии его в карточке контакта CRM-системы он будет создан. В качестве имени будет использовано значение name или chatId, если первое отсутствует.

Пример запроса
 curl --location --request POST 'https://api.wazzup24.com/v3/iframe' \
--header 'Authorization: Bearer c8cf90554027882f912520f454468d27' \
--header 'Content-Type: application/json' \
--data-raw '
{
"user": {
"id": "222555",
"name": "User Name"
},
"scope": "card",
"filter": [
{
"chatType": "whatsapp",
"chatId": "79998887766"
}
],
"activeChat": {
"chatType": "whatsapp",
"chatId": "79998887766"
}
}
'
Ответ

В ответе придет json со ссылкой для открытия окна чатов.

Если открываете ссылку в iframe, добавьте в тег атрибут allow=”microphone *; clipboard-write *”.

Указать «microphone» нужно, чтобы из окна с чатами можно было записывать голосовые сообщения. Если этого не сделать, пользователь увидит ошибку при нажатии на значок микрофона для записи.

Передавать «clipboard-write» необходимо, чтобы в нашем iframe правильно работало копирование в буфер обмена. Например, пользователь мог по кнопке скопировать код ошибки из уведомления.

<iframe src="ссылка" allow="microphone *; clipboard-write *" ></iframe>
Пример ответа
{
"url": "https://12345678.wazzup24.com/chat/0e812899-e25b-4a18-a3e4-d1f5890f9de7?token=${token}"
}

В случае ошибки в ответе поступит json, который содержит свойство error или http-код 500.
​​Пример ответа с ошибкой
 { "error": { "code": "NO_SUCH_ACCOUNT" } }

Как настроить работу «чемодана» по событиям

Мы рекомендуем работать с «чемоданом» с помощью вебхуков. Но если вебхуки не подходят, используйте события.

События сигнализируют о том, что нужно:

  • создать новую сделку,
  • показать сущность, которую пользователь хочет открыть из «чемодана»,
  • создать новый контакт.

О каких событиях может сообщать iframe:

Что значит: нужно создать новую сделку с теми параметрами, которые передал iframe.

Название события: WZ_CREATE_ENTITY 

Как получать: при генерации ссылки на iframe передайте нам options.useDealsEvents: true

Что содержит:

Поле Тип Описание
type String Название события WZ_CREATE_ENTITY
data Object  Объект, который содержит данные о событии
data.chatType String Тип чата мессенджера: whatsapp, instagram, telegram, vk, avito
data.chatId String ID чата (аккаунт контакта в мессенджере)
data.channelId String Идентификатор канала
data.userId Number ID пользователя в CRM
data.integrationId String ID интеграции

Пример события:

{
  type: 'WZ_CREATE_ENTITY',
  data: {
    chatType: whatsapp,
    chatId: 79998887766,
    channelId: c16tc1c-9f20-4rda-46jd-q92ty4j6s36888,
    userId: test_id,
    integrationId: 608df5ye-45hj-j6k7-l77k-qe5t88j4h1222
  } 
После создания сделки нужно передать данные о новой сделке из CRM в Wazzup.

Что значит: пользователю нужно показать сделку, контакт или другую сущность, с параметрами, которые передает iframe.

Название события: WZ_OPEN_ENTITY

Как получать: при генерации ссылки на iframe передайте нам options.useDealsEvents: true

Что содержит:

Поле Тип Описание
type String Название события WZ_CREATE_ENTITY
data Object  Объект, который содержит данные о событии
data.chatType String Тип чата мессенджера: whatsapp, instagram, telegram, vk, avito
data.chatId String ID чата (аккаунт контакта в мессенджере)
data.channelId String Идентификатор канала
data.userId Number ID пользователя в CRM
data.integrationId String ID интеграции
data.entity Object Объект, который содержит данные о сущности
data.entity.closed Boolean Флаг. Показывает, закрыта или открыта сделка
data.entity.id Number Идентификатор сущности, которую открывает пользователь
data.entity.link String Ссылка на сущность. Может не быть
data.entity.name String Имя сущности
data.entity.responsibleUserName String Имя пользователя, отвественного за сущность

Пример события

{
  type: 'WZ_OPEN_ENTITY',
  data: {
    chatType: whatsapp,
    chatId: 79998887766,
    channelId: c16tc1c-9f20-4rda-46jd-q92ty4j6s36888,
    userId: test_id,
    integrationId: 608df5ye-45hj-j6k7-l77k-qe5t88j4h1222,
    entity: {
      closed: false,
      id: clientId3,
      link: #,
      name: ТестоваяСделка,
      responsibleUserName: ТестовыйПользователь
    }
  } 
}

Что значит: нужно создать контакт с теми параметрами, которые передал iframe.

Событие будет приходить каждый раз, когда продавец отправляет сообщение, а не только тогда, когда впервые пишет клиенту. Поэтому событие может прийти, когда контакт уже создан в CRM.

Название события: WZ_OUTPUT_MESSAGE

Как получать: при генерации ссылки на iframe передайте нам options.useMessageEvents: true

Что содержит:

Поле Тип Описание
type String Название события WZ_CREATE_ENTITY
data Object  Объект, который содержит данные о событии
data.chatType String Тип чата мессенджера: whatsapp, instagram, telegram, vk, avito
data.chatId String ID чата (аккаунт контакта в мессенджере)
data.channelId String Идентификатор канала
data.userId Number ID пользователя в CRM
data.integrationId String ID интеграции
data.messageId String Идентификатор отправленного сообщения
data.name String Имя контакта в мессенджере, соцсети
data.username
String @юзернейм контакта в Telegram
data.telephone String Номер телефона контакта в Telegram

Пример события

{
  type: 'WZ_OUTPUT_MESSAGE',
  data: {
    chatType: whatsapp,
    chatId: 79998887766,
    channelId: c16tc1c-9f20-4rda-46jd-q92ty4j6s36888,
    userId: test_id,
    integrationId: 608df5ye-45hj-j6k7-l77k-qe5t88j4h1222,
    messageId: 7886о490-49df-8hj3-3jkj-wes4xc54fwd
  } 
}
После создания контакта нужно передать данные о нем из CRM в Wazzup.

Сделали html-страницу, которая служит примером того, как можно отлавливать события iframe. Как пользоваться:

  1. Сгенерируйте ссылку на iframe методом API.
  2. Вставить эту ссылку в поле ввода на html-странице.
  3. Отобразится интерфейс чатов. Вы сможете потыкать на нужные кнопки чтобы вызвать событие — над iframe появятся данные, которые в этом событии пришли.