Comment pouvons-nous vous aider ?

Intégration de Webhooks entrants

TimelinesAI vous permet d'automatiser l'envoi de messages WhatsApp en réponse à des événements ou des actions dans les outils que vous utilisez déjà : CRM, support, systèmes de recrutement, etc.

"Événement "Envoyer un message

Il est possible de demander à TimelinesAI d'envoyer un message (avec ou sans pièce jointe) à un contact spécifique (qui peut être un groupe). Si plusieurs comptes WhatsApp sont connectés dans votre espace de travail, il est également possible de spécifier un compte WhatsApp particulier à utiliser pour l'envoi du message.

Pour configurer l'intégration, le propriétaire d'un espace de travail doit se rendre sur l'écran "Integrations / Inbound Webhooks" et générer une nouvelle URL. Le système externe doit envoyer un message dans un format spécifique (voir détails ci-dessous) à cette URL.

Limites

  • La taille maximale des pièces jointes est de 2 Mo.
  • Il n'y a pas de validation immédiate du format du numéro de téléphone du destinataire ou de sa connexion à WhatsApp. Accédez à l'interface Timelines pour vérifier l'état d'envoi ou de lecture des messages.

Envoi de fichiers via les Webhooks entrants

Envoi d'un fichier : téléchargement direct ou services d'hébergement de fichiers

Il est impératif d'envoyer des fichiers en utilisant des liens de téléchargement direct. Cela permet au destinataire de recevoir effectivement le fichier.

En revanche, il convient d'utiliser un service d'hébergement de fichiers afin qu'il puisse fournir un lien de téléchargement direct. Le meilleur moyen de tester un tel lien est d'utiliser la navigation incognito/privée, en collant le lien dans la barre de recherche. Si le téléchargement du fichier démarre immédiatement, le lien est acceptable. Si, au contraire, une page web quelconque s'affiche, le lien ne peut pas être utilisé pour envoyer des fichiers.

Dans le cas des liens de services d'hébergement de fichiers, les fichiers ne peuvent pas être téléchargés. Ce qui est téléchargé et envoyé à la place, c'est une page web de partage, ce qui peut conduire à un fichier "corrompu".

Cela affecte votre message car les destinataires ne peuvent pas accéder aux médias que vous leur envoyez, ce qui rend les fichiers inutilisables. Il est donc essentiel de veiller à envoyer des liens de téléchargement direct, car cela leur permettra d'accéder au fichier sans problème.

Vous pouvez également effectuer ce test en envoyant un message webhook à l'un de vos numéros de test. Si, après avoir cliqué sur la pièce jointe, vous obtenez un message d'erreur tel que "Fichier corrompu", "Fichier incompatible" ou "Échec du chargement du document X", il s'agit d'un lien de service d'hébergement de fichiers qui doit être remplacé par un lien de téléchargement direct.

Utilisation du crédit

  • L'envoi d'un message consomme 1 crédit du quota d'envoi de messages.
  • L'envoi d'un message avec un texte non vide et une pièce jointe consomme 2 crédits du quota d'envoi de messages.
  • Si un message ne peut pas être envoyé (numéro WhatsApp non valide ou non connecté, erreur du serveur WhatsApp), le quota d'envoi de messages sera rétabli (généralement dans les deux heures qui suivent).

Taux d'envoi des messages

  • Les messages seront envoyés avec un délai aléatoire d'environ 2 secondes entre chaque message (pour éviter les mécanismes de détection de spam de WhatsApp).
  • Si vous activez les webhooks avec une fréquence inférieure à 2 secondes, les messages seront mis en file d'attente et envoyés avec retard. Chaque message mis en file d'attente consommera un crédit d'envoi de message, de sorte que le nombre de messages mis en file d'attente ne peut pas dépasser le quota disponible.

Configuration et actions des webhooks

  • "Webhook enabled" - permet de désactiver le webhook sans le supprimer complètement
  • "Générer une nouvelle URL" - crée une nouvelle URL unique qui acceptera les notifications. L'URL précédente ne sera plus disponible.
  • "Dernières tentatives d'envoi" - état des dernières tentatives d'activation du webhook
  • "Journal de téléchargement" - un journal détaillé des 100 dernières tentatives d'activation, utile pour résoudre les problèmes de formatage.

Format de la requête Webhook

Le Webhook accepte les données au format JSON, au moyen d'une requête POST.

  • "action" (obligatoire) - actuellement, une seule valeur possible "send" est prise en charge
  • "text" (obligatoire) - un message en texte brut encodé en UTF-8 à envoyer (pas de markdown supporté, sauf le séparateur de ligne "\n"), peut être laissé vide si le fichier est spécifié.
  • "file_url" (facultatif) - URL publiquement accessible d'un fichier qui sera téléchargé et envoyé en tant que pièce jointe.
  • "file_name" (facultatif) - un nom pour la pièce jointe (doit être fourni si l'URL est spécifiée).

Le destinataire peut être spécifié en fournissant l'un des paramètres suivants :

  • "chat_id" - un identifiant du chat tel qu'il apparaît dans TimelinesAI (peut être trouvé dans l'URL de la page de chat, ou dans le payload d'un webhook sortant). Cela permet d'envoyer des messages à un groupe.
  • "jid" - un JID WhatsApp qui spécifie le contact ou le groupe
  • "phone" - un numéro de téléphone, formaté selon la norme internationale des numéros de téléphone, c'est-à-dire :
    [+][indicatif de pays][indicatif régional][numéro de téléphone local] (par exemple : +14151231234)
  • "chat_name" - nom exact du chat tel qu'il apparaît dans TimelinesAI

Si plusieurs comptes WhatsApp sont connectés dans l'espace de travail, utilisez le paramètre supplémentaire suivant pour spécifier le compte WhatsApp à utiliser :

  • "whatsapp account phone" (facultatif) - spécifie (sous forme de numéro de téléphone, au format international) le compte WhatsApp à utiliser pour l'envoi. S'il est omis, le compte WhatsApp actif le plus récemment connecté dans l'espace de travail sera utilisé pour l'envoi. Remarque : si le paramètre "chat_id" est spécifié, "whatsapp account phone" ne sera pas pris en compte, car chaque chat est déjà connecté à un compte WhatsApp spécifique.

Réponse au webhook

En cas de succès (la demande a été validée et acceptée pour l'envoi), le Webhook répondra avec le statut HTTP 200 et JSON, contenant l'identifiant du message créé :

{
    "status": "success",
    "data": {
        "message_id": "wa_backend:3EB09FCC85FE99662E46"
    }
}

 

En cas d'erreur, le Webhook répondra avec le statut HTTP 40X et JSON avec les détails de l'erreur, par exemple :

{
"status": 40X,
"data": {},
"message": "Webhook not found"
}

Exemples

Exemple 1 - envoi d'un message via un compte WA spécifique à un numéro de téléphone spécifique :

{
"action": "send",
"whatsapp account phone" : "+15105566777", 
"phone": "+14151231234", 
"text": "lorem ipsum"
}

Exemple 2 - envoi d'un message avec texte et pièce jointe à un chat (ou groupe) spécifié par id :

{
"action": "send", 
"chat_id": "77234", 
"text": "lorem ipsum"
"file_url" : "https://timelines.ai/logo.png",
"file_name" : "logo.png"
}
Table des matières