Developer Platform

Developer Platform

Webhooks

Les webhooks vous permettent d’envoyer des notifications d’événements en temps réel au sein de tawk.to à des services externes.

Vous pouvez choisir d’envoyer un événement webhook lorsque:

  • Une discussion commence
  • Une discussion se termine
  • Un ticket est créé
Un Webhook consiste d’:
  • Une URL que vous avez configurée sur laquelle l'événement webhook sera publié
  • Un ou plusieurs événements, qui seront publiés sur une URL spécifique
  • Une clé secrète, qui peut être utilisée pour vérifier que la charge utile du webhook a été envoyée par tawk.to

Lorsqu’un webhook est déclenché, une requête POST sera envoyée à l’URL configurée avec une charge utile JSON spécifique au type d’événement.

Référence:

Gestion des webhooks

Les webhooks peuvent être gérés via le tableau de bord tawk.to dans la section « Administration ».

Événements actuellement soutenues

Les fonctions de rappel sont appelées lorsque le statut de la page change. La fonction recevra le statut modifié qui sera soit en ligne, absent ou hors ligne. Ce rappel n’est pas pris en charge dans la fenêtre de discussion surgissante.

Chat:

  • Démarrer

  • Mettre Fin

Ticket:

  • Créer

Politique de retour

Un appel Webhook sera réessayé pendant 12 heures maximum si le point de terminaison http répond avec autre chose qu’un succès (2XX). Si aucune réponse n’est reçue dans les 30 secondes, l’appel sera considéré comme un échec et fera également l’objet d’une nouvelle tentative. Chaque événement de webhook  se voit attribuer un ID d’événement. L’ID d’événement est transmis avec chaque demande dans les en-têtes sous la forme X-Hook-Event-Id. L’ID d’événement restera le même en cas de tentatives.

Vérification de la signature du webhook

Chaque événement de webhook est signé via un code d’authentification de message basé sur le hachage (HMAC) à l’aide de la clé secrète des webhooks. L’algorithme HMAC-SHA1 est utilisé pour générer la signature de la charge utile du webhook. La signature transmise avec chaque demande dans les en-têtes sous la forme `X -Tawk-Signature`.

Exemples:

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', $body, 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

Charge utile de l’événement Webhook

Événement de début de chat

Généré lorsque le premier message d’un chat est envoyé par un visiteur ou un agent. Les chuchotements et les notifications système comme les déclencheurs ne génèrent pas cet événement.

Charge utile de l’événement de démarrage du chat
Propriété Type Description
Événement Séries Nom de l'événement `chat:démarrer`
ID de chat Séries ID de chat
temps Séries Date et heure de génération de l'événement au format JSON
message Objet L'objet du message (Voir ci-dessous)
visitor Objet L'objet du visiteur (voir ci-dessouss)
Propriété Objet L'objet de la Propriété(voir ci-dessous)

Objet du message

Propriété Type Description
texte Séries Représentation textuelle du message
type Séries Type de message, valeur enum msg, file, webrtc-call
émetteur Objet Objet d'information de l'émetteur(voir ci-dessous)

Objet d'information de l'émetteur

Propriété Type Description
type Séries type émetteur,valeur enum agent, visiteur, système

Objet du visiteur

Propriété Type Description
Nom Séries Nom du visiteur
courriel Séries courriel du visiteur (optionnel)
Ville Séries Ville du visiteur
Pays Séries Pays du visiteur au format ISO 3166

Objet de propriété

Propriété Type Description
id Séries Id de la Propriété
name Séries Nom de la Propriété

Example 
{
    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'
    }
}

Événement de fin de chat

Généré lorsqu’un chat est terminé

Charge utile de l’événement de fin de chat



Propriété Type Description
Événement Séries Nom de l'événement `chat:fin`
ID de chat Séries ID de chat
temps Séries Date et heure de génération de l'événement au format JSON
visiteur Objet Objet du visiteur (voir ci-dessous)
Propriété Objet Objet de Propriété (voir ci-dessous)

Objet du visiteur

Propriété Type Description
Nom Séries Nom du visiteur
courriel Séries courriel du visiteur (optionnel)
Ville Séries Ville du visiteur
Pays Séries Pays du visiteur au format ISO 3166

Objet du Propriété

Propriété Type Description
id Séries Id de la Propriété
Nom Séries Nom de la Propriété

Exemple 
{
    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'
    }
}

Événement créé par un ticket

Généré lorsqu’un nouveau ticket est créé

Charge utile de l’événement de créer un ticket

Propriété Type Description
Événement Séries Nom de l'événement `ticket:créer´
temps Séries Date et heure de génération de l'événement au format JSON
Demandeur Objet Objet demandeur de ticket (voir ci-dessous)
Propriété Objet objet de Propriété (voir ci-dessous)
ticket Objet objet de ticket(voir ci-dessous)

objet demandeur de ticket

Propriété Type Description
name Séries Nom du visiteur
Courriel Séries Courriel du visiteur(Optionnel)

Objet de Propriété

Propriété Type Description
id Séries Id de la Propriété
Nom Séries Nom de la Propriété

Objet du ticket

Propriété Type Description
id Séries Id du Ticket
Identifiant humain Numéro Identifiant humain du ticket
sujet Séries Sujet du Ticket
message Séries Contenu du message du ticket


Exemple 
{
    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'
    }
}
© 2024 tawk.to inc. Tous droits réservés.

Dirigez-vous vers tawk.to