Вебхуки

С помощью вебхуков вы можете отправлять уведомления о событиях в tawk.to внешним службам и настраивать мощную автоматизацию в режиме реального времени.

Вы можете выбрать отправку события, когда:

чат начался
чат завершился
была создана новая заявка

Ключевые понятия для вебхуков:

URL полезных данных – адрес сайта, на котором будут опубликованы полезные данные.
Одно или несколько инициирующих событий, установленных для запуска вебхука.
Секретный ключ - используется для идентификации отправленных tawk.to полезных данных.

При возникновении события, POST-запрос будет передан на URL-адрес, настроенный вместе с полезной нагрузкой JSON, специфичной для этих событий.

Reference:

Управление вебхуками

Вебхуками можно управлять в панели управления tawk.to в разделе Администрирование.

Доступные поддерживаемые инициирующие события

Функции обратного вызова вызываются при изменении статуса страницы. Функция получит измененный статус: В сети, Нет на месте или Не в сети. Данная функция не поддерживается, если установлено всплывающее окно.

Чат:

Начать
Завершить

Заявка:

Создать

Политика повторных попыток

Вызов вебхука будет повторяться в течение 12 часов, если конечная точка HTTP не отвечает или недоступна (2XX). Если в течение 30 секунд не будет получен ответ, вызов будет считаться неудачным и также будет повторен. Каждое событие вебхука имеет свой идентификатор (Id). Идентификатор события передается вместе с каждым запросом в заголовках как X-Hook-Event-Id. В случае повторных попыток идентификатор события останется прежним.

Проверка подписи вебхука

Каждое событие вебхука подписывается с помощью хеш-кода аутентификации сообщения (HMAC) с использованием секретного ключа. Алгоритм HMAC-SHA1 используется для генерации подписи полезной нагрузки вебхука. Подпись передается вместе с каждым запросом в заголовках как `X-Tawk-Signature`.

Примеры:

Node.js

const WEBHOOK_SECRET = 'webhook secret key';
const crypto = require('crypto');
function verifySignature (body, signature) {
    const digest = crypto
        .createHmac('sha1', WEBHOOK_SECRET)
        .update(body)
        .digest('hex');
    return signature === digest;
};
app.post('/webhooks', function (req, res, next) {
    if (!verifySignature(req.rawBody, req.headers['x-tawk-signature'])) {
        // verification failed
    }
    // verification success
});

PHP

const WEBHOOK_SECRET = 'webhook secret key';
function verifySignature ($body, $signature) {
    $digest = hash_hmac('sha1', $rawPost, WEBHOOK_SECRET);
    return $signature !== $digest ;
}
if (!verifySignature(file_get_contents('php://input'), $_SERVER['HTTP_X_TAWK_SIGNATURE'])) {
    // verification failed
}
// verification success

Ruby

WEBHOOK_SECRET = 'webhook secret key';
post '/payload' do
    request.body.rewind
    body = request.body.read
    signature = request.env['HTTP_X_TAWK_SIGNATURE']
    unless verifySignature(body, signature))
        // verification failed
    end
    // verification success
end
def verifySignature(body, signature)
    digest = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), WEBHOOK_SECRET, body)
    return digest == signature
end

Полезная нагрузка вебхуков

Событие начала диалога в чате.

Генерируется, когда первое сообщение в чате отправляет посетитель или оператор. Функция Шепот и системные уведомления, такие как триггеры, не генерируют это событие.

Полезная нагрузка события начала диалога в чате

Property	Type	Description
event	String	Event name `chat:start`
chatId	String	Chat Id
time	String	Event generation date time in JSON format
message	Object	Message object (See below)
visitor	Object	Visitor object (see below)
property	Object	Property object (see below)

Объект сообщения

Property	Type	Description
text	String	Textual representation of message
type	String	Message type, enum value msg, file, webrtc-call
sender	Object	Sender info object (See below)

Объект информация об отправителе

Property	Type	Description
type	String	Sender type, enum value agent, visitor, system

Объект посетитель

Property	Type	Description
name	String	Visitor name
email	String	Visitor email (Optional)
city	String	Visitor city
country	String	Visitor country in ISO 3166 format

Объект проекта

Property	Type	Description
id	String	Property Id
name	String	Property name

Пример

{
    event: 'chat:start',
    chatId: '70fe3290-99ad-11e9-a30a-51567162179f',
    time: '2019-06-28T14:03:04.646Z',
    message : {
        text : 'Sample message',
        type : 'msg',
        sender : {
            type : 'visitor'
        }
    },
    visitor: {
        name: 'V1561719148780935',
        email : 'hello@test.com',
        city: 'jelgava',
        country: 'LV'
    },
    property: {
        id: '58ca8453b8a7e060cd3b1ecb',
        name: 'Bobs Burgers'
    }
}

Событие окончания диалога в чате.

Создается, когда диалог в чате завершился.

Полезная нагрузка конечного события чата

Property	Type	Description
event	String	Event name chat:end
chatId	String	Chat Id
time	String	Event generation date time in JSON format
visitor	Object	Visitor object (see below)
property	Object	Property object (see below)

Объект посетитель

Property	Type	Description
name	String	Visitor name
email	String	Visitor email (Optional)
city	String	Visitor city
country	String	Visitor country in ISO 3166 format

Объект проекта

Property	Type	Description
id	String	Property Id
name	String	Property name

Пример

{
    event: 'chat:end',
    chatId: '70fe3290-99ad-11e9-a30a-51567162179f',
    time: '2019-06-28T14:04:08.718Z',
    visitor: {
        name: 'V1561719148780935',
        email : 'hello@test.com',
        city: 'jelgava',
        country: 'LV'
    },
    property: {
        id: '58ca8453b8a7e060cd3b1ecb',
        name: 'Bobs Burgers'
    }
}

Событие создания заявки.

Генерируется при создании новой заявки.

Полезная нагрузка создания заявки

Property	Type	Description
event	String	Event name `ticket:create`
time	String	Event generation date time in JSON format
requester	Object	Ticket requester object (see below)
property	Object	Property object (see below)
ticket	Object	Ticket object (see below)

Объект запроса заявки

Property	Type	Description
name	String	Visitor name
email	String	Visitor email (Optional)

Объект проекта

Property	Type	Description
id	String	Property Id
name	String	Property name

Объект заявки

Property	Type	Description
id	String	Ticket Id
humanId	Number	Ticket human Id
subject	String	Ticket subject
message	String	Ticket message content

Пример

{
    event: 'ticket:create',
    time: '2019-06-28T14:07:13.512Z',
    property: {
        id: '58ca8453b8a7e060cd3b1ecb',
        name: 'Bobs Burgers'
    },
    requester: {
        name: 'Martins',
        email: 'martins@tawk.to',
        type: 'agent'
    },
    ticket: {
        id: '02598050-99ae-11e9-8887-97564881b95b',
        humanId: 3,
        subject: 'Testing',
        message: 'Once more through the breach'
    }
}