Canaux personnalisés #

Connectez n’importe quelle plateforme de messagerie ou outil de communication à la plateforme en utilisant des canaux personnalisés. Cela vous permet d’intégrer les messages provenant de plateformes telles que des widgets de chat en direct sur site web, des systèmes d’e-mail, des CRM ou tout autre service dans votre boîte de réception — et d’y répondre avec votre agent IA.

Que sont les canaux personnalisés ? #

Les canaux personnalisés étendent la plateforme au-delà de ses plateformes de messagerie intégrées (WhatsApp, SMS, Instagram, Messenger). Avec les canaux personnalisés, vous pouvez :

• Recevoir des messages depuis n’importe quelle plateforme externe dans la boîte de réception unifiée de la plateforme.
• Envoyer des réponses depuis l’application vers votre plateforme externe automatiquement.
• Utiliser un agent IA pour répondre aux messages provenant de n’importe quelle source.
• Suivre toutes les conversations aux côtés de vos autres canaux dans une seule boîte de réception.

C’est idéal pour les entreprises qui utilisent des outils de communication spécialisés, possèdent une plateforme développée sur mesure ou souhaitent centraliser tous les messages clients au même endroit.

Comment ça fonctionne #

Les canaux personnalisés fonctionnent en échangeant des messages entre votre plateforme externe et la plateforme via des webhooks (messages automatisés envoyés entre systèmes via Internet). Voici le flux :

Your Platform  ──(sends message to)──>  The App
                                           |
                                       AI Agent responds
                                       Contact saved
                                       Message stored
                                           |
The App  ──(sends reply to)──>  Your Platform

1. Messages entrants : Votre plateforme externe envoie des messages à une adresse web (URL). Considérez cela comme si votre plateforme « postait » un message dans la boîte aux lettres de la plateforme.
2. Traitement : La plateforme crée ou met à jour le contact, stocke le message et demande à un agent IA de générer une réponse (si activé).
3. Messages sortants : Lorsque la plateforme envoie une réponse (qu’elle provienne de l’IA ou que vous l’ayez saisie), elle envoie le message à une URL sur votre plateforme, où votre système peut le transmettre à l’utilisateur final.

Configuration des messages entrants (De votre plateforme vers l’application) #

Pour envoyer des messages depuis votre plateforme externe vers l’application, votre plateforme doit envoyer des données à l’URL suivante. Votre développeur reconnaîtra ceci comme une requête POST standard (une méthode courante pour qu’un système envoie des données à un autre via Internet).

Où envoyer les messages #

POST https://api.youraiconnector.com/v1/incoming_custom_channel_message?apiKey=YOUR_API_KEY

Remplacez YOUR_API_KEY par votre clé API (un code privé qui prouve à la plateforme que votre plateforme est autorisée à lui envoyer des messages). Trouvez-la ou générez-la sous Paramètres → Intégrations → Clé API.

Format du message #

Envoyez les données du message dans le format suivant (JSON) :

{
  "customData": {
    "messageSid": "unique-message-id-123",
    "fromId": "user-456",
    "toId": "your-business-id",
    "body": "Hello, I have a question about your service.",
    "status": "received",
    "channel": "my-live-chat",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com",
    "mediaUrl": null,
    "mediaContentType": null
  },
  "messageType": "text"
}

Signification de chaque partie :

• messageSid - Un identifiant unique pour ce message spécifique (créé par votre système). Utilisé pour éviter que le même message ne soit traité deux fois.
• fromId - Qui a envoyé le message (peut être un identifiant utilisateur, une adresse e-mail ou un numéro de téléphone de votre système).
• toId - Votre identifiant d’entreprise (peut être n’importe quelle étiquette de votre choix).
• body - Le texte réel du message.
• channel - Une étiquette que vous choisissez pour identifier la provenance du message (par ex. “website-chat”, “email”).

Référence complète des champs #

Réactions par émoji #

Si votre plateforme prend en charge les réactions par émoji (un pouce levé sur un message, par exemple), envoyez-les en tant que réaction plutôt que sous forme de message texte : définissez messageType sur "reaction" et placez uniquement l’émoji dans customData.body.

{
  "messageType": "reaction",
  "customData": {
    "messageSid": "reaction-123",
    "fromId": "user-42",
    "toId": "my-business",
    "body": "👍"
  }
}

L’assistant le traite alors comme vous vous y attendez :

• Une réaction à une question posée par l’assistant (par exemple « Jeudi vous convient ? ») est traitée comme une réponse, et l’assistant répond.
• Une réaction à un message de clôture (par exemple « À bientôt ! ») met fin à la conversation discrètement. Aucune réponse n’est envoyée.

Si votre plateforme transforme les réactions en texte tel que « A réagi avec : 👍 », l’assistant voit un message texte normal et décide lui-même s’il doit répondre. L’envoi du type de réaction permet d’éviter cela.

Ce que vous recevez en retour #

Une requête réussie renvoie :

{
  "success": true,
  "messageId": "1234567890"
}

Si quelque chose ne va pas, vous recevrez un message d’erreur expliquant le problème :

{
  "error": "Message body cannot be empty"
}

Codes de statut #

Si vous définissez customData.status, la seule valeur acceptée est "received" — omettez-la complètement pour utiliser la valeur par défaut plutôt que d’envoyer autre chose, sinon vous recevrez une erreur 400.

Envoi de pièces jointes (images, vidéos, fichiers) #

Vous pouvez inclure des pièces jointes (images, vidéos, audio, documents) avec vos messages. Il existe deux façons de procéder :

Option 1 : Lien vers un fichier #

Si le fichier est déjà hébergé en ligne, fournissez l’URL (adresse web) où la plateforme peut le télécharger :

{
  "customData": {
    "messageSid": "msg-789",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Here is a photo of the issue.",
    "channel": "support-portal",
    "mediaUrl": "https://example.com/uploads/photo.jpg",
    "mediaContentType": "image/jpeg"
  },
  "messageType": "text"
}

Option 2 : Intégrer le fichier directement (Base64) #

Si le fichier n’est pas hébergé en ligne, vous pouvez l’intégrer directement dans le message sous forme de texte encodé (format base64). C’est une pratique courante dans les intégrations techniques où votre système génère des fichiers à la volée. La plateforme décodera et stockera automatiquement le fichier :

{
  "customData": {
    "messageSid": "msg-790",
    "fromId": "user-456",
    "toId": "business-1",
    "body": "Screenshot attached.",
    "channel": "support-portal",
    "mediaUrl": "data:image/png;base64,iVBORw0KGgo...",
    "mediaContentType": "image/png"
  },
  "messageType": "text"
}

Configuration des messages sortants (de la plateforme vers votre plateforme) #

Lorsque la plateforme envoie une réponse sur un canal personnalisé (qu’elle provienne de l’IA ou que vous l’ayez saisie), elle envoie automatiquement cette réponse à une URL sur votre plateforme afin que votre système puisse la transmettre à l’utilisateur final.

Définissez d’abord l’URL du webhook. Vous devez enregistrer l’URL du webhook du canal personnalisé avant que toute réponse puisse être transmise. Si aucune URL n’est enregistrée, les réponses sont toujours générées et stockées, mais elles ne sont jamais envoyées — et elles n’afficheront pas de statut « Échec », donc rien dans votre boîte de réception ne signalera le problème. Configurez toujours l’URL du webhook avant la mise en service.

Indiquer à l’application où envoyer les réponses #

1. Dans la barre latérale gauche, cliquez sur Paramètres près du bas.
2. Dans le menu de gauche des paramètres, sous Canaux, cliquez sur Canaux.
3. Trouvez la carte Canal personnalisé tout en bas de la page (après Passerelle SMS Android, iMessage, le widget de chat du site web, le compte Twilio et la conformité réglementaire).
4. Saisissez l’URL du Webhook — l’URL sur votre plateforme où l’IA doit envoyer les messages sortants (votre développeur configure cela pour recevoir et traiter les réponses). Il doit s’agir d’une URL HTTPS publique — les adresses http:// et les hôtes non publics sont rejetés.
5. Cliquez sur Enregistrer.

Ce que la plateforme envoie à votre plateforme #

Lorsque la plateforme envoie une réponse, votre plateforme reçoit les données suivantes :

{
  "contactId": "abc123",
  "messageId": "msg-456",
  "userId": "your-user-id",
  "body": "Thank you for your message! Here is the information you requested...",
  "toId": "user-456",
  "channel": "my-live-chat"
}

Signification de chaque champ #

Votre plateforme reçoit ces données et les utilise pour transmettre la réponse à l’utilisateur final via votre propre système.

Comment la plateforme suit la livraison #

Après avoir envoyé la réponse à votre plateforme, la plateforme met à jour le statut du message :

• Envoyé - Votre plateforme a reçu le message avec succès.
• Échec - Votre plateforme a renvoyé une erreur ou n’a pas pu être atteinte. La plateforme stocke les détails de l’erreur avec le message afin que vous puissiez résoudre le problème.

Envoi de messages depuis votre système vers l’application #

En plus de recevoir des messages, vous pouvez également envoyer des messages sortants via un canal personnalisé directement depuis votre propre système. Cela est utile lorsque vous souhaitez entamer une conversation ou envoyer un message proactif.

Exigence de forfait. L’envoi et la synchronisation de messages via l’API nécessitent un forfait incluant l’accès à l’API et au moins un canal de messagerie. Si vous recevez une erreur 403 « permission denied / feature not enabled », votre forfait actuel ne l’inclut pas — mettez à niveau votre forfait ou contactez le support.

Où envoyer #

POST https://api.youraiconnector.com/v1/send_custom_channel_message?apiKey=YOUR_API_KEY

Format du message #

{
  "customData": {
    "fromId": "user-456",
    "customChannel": "my-live-chat",
    "body": "Hello! How can I help you today?",
    "campaignId": "optional-campaign-id",
    "firstName": "John",
    "lastName": "Doe",
    "email": "john@example.com"
  }
}

Champs requis #

Les champs optionnels (campaignId, firstName, lastName, email) fonctionnent de la même manière que pour les messages entrants — ils aident la plateforme à créer ou mettre à jour la fiche contact.

Ce que vous recevez en retour #

{
  "success": true,
  "messageId": "generated-message-id",
  "contactId": "contact-id",
  "message": "Message sent successfully"
}

Enregistrement de messages envoyés depuis un autre système #

Parfois, vous avez déjà envoyé un message à un contact depuis un autre outil (par exemple, un flux de travail dans une autre plateforme), et vous voulez simplement que la plateforme en soit informée afin que l’IA dispose du contexte complet. Ceci est différent de l’envoi : la plateforme enregistre le message mais ne le retransmet pas au contact.

Où envoyer #

POST https://api.youraiconnector.com/v1/sync_custom_channel_message?apiKey=YOUR_API_KEY

Incluez customData.fromId (l’identifiant du contact sur votre plateforme) et customData.body (le texte du message qui a déjà été envoyé).

Comportement #

• Le message est enregistré, pas renvoyé. La plateforme le stocke dans la conversation uniquement pour le contexte.
• L’IA est mise en pause sur ce contact par défaut. Cela évite que le bot ne réponde par-dessus un message déjà traité par un humain. Pour garder le bot actif, passez customData.pauseAi: false.
• De nouveaux contacts peuvent être créés automatiquement. Incluez customData.customChannel et le contact sera créé s’il n’existe pas encore.
• Les doublons sont ignorés. Si vous réutilisez le même messageSid, la plateforme reconnaît que le message a déjà été enregistré et n’effectue aucun changement.

Exigence liée au forfait. Tout comme l’envoi, l’enregistrement de messages via l’API nécessite un forfait incluant l’accès à l’API et au moins un canal de messagerie. Une erreur 403 « permission denied / feature not enabled » signifie que votre forfait actuel ne comprend pas cette fonctionnalité.

Exemples concrets #

Chat en direct sur site web #

Connectez un widget de chat en direct sur votre site web à la plateforme afin que votre agent IA puisse répondre aux questions des visiteurs :

1. Un visiteur saisit un message dans le widget de chat de votre site web.
2. Votre widget de chat envoie le message à la plateforme.
3. L’agent IA génère une réponse.
4. La réponse est renvoyée à votre widget de chat, qui l’affiche au visiteur.

Pourquoi est-ce utile : Les visiteurs de votre site web obtiennent des réponses instantanées générées par l’IA à leurs questions sans que vous ayez besoin d’être en ligne.

E-mail #

Acheminez les conversations par e-mail via la plateforme afin que votre agent IA puisse répondre aux e-mails :

1. Configurez un système qui transfère les e-mails entrants vers la plateforme (en utilisant l’adresse de l’expéditeur de l’e-mail comme fromId, l’objet et le corps de l’e-mail comme body, et "email" comme channel).
2. L’agent IA lit l’e-mail et génère une réponse.
3. La réponse est renvoyée à votre système de messagerie, qui l’envoie comme une réponse e-mail normale.

Pourquoi est-ce utile : Les questions fréquentes par e-mail (tarifs, horaires, disponibilité) obtiennent une réponse instantanée de votre agent IA.

Si votre système de messagerie prend en charge IMAP/SMTP ou OAuth, le canal E-mail intégré peut être plus simple qu’une intégration personnalisée.

Intégration CRM #

Connectez votre système CRM (gestion de la relation client) existant à la plateforme :

1. Lorsqu’un prospect envoie un message via votre CRM, transférez-le vers la plateforme.
2. L’agent IA répond et suit la conversation.
3. La réponse de l’IA est renvoyée à votre CRM pour livraison.
4. L’historique complet de la conversation est disponible à la fois sur la plateforme et dans votre CRM.

Pourquoi est-ce utile : Votre équipe commerciale bénéficie de réponses assistées par l’IA pour les prospects sans quitter leur CRM.

Système de tickets de support #

Utilisez la plateforme comme premier intervenant assisté par IA pour le support client :

1. Votre système de ticketing transfère les nouveaux tickets de support vers la plateforme.
2. L’agent IA envoie une réponse initiale (par exemple, pour accuser réception du ticket et poser des questions de clarification).
3. La réponse est jointe au ticket dans votre système de support.
4. Votre équipe de support peut examiner ce que l’IA a dit et prendre le relais si nécessaire.

Pourquoi est-ce utile : Les clients reçoivent un accusé de réception immédiat et une aide initiale, même en dehors des heures d’ouverture.

Dépannage #

Messages non reçus par la plateforme #

• Vérifiez que votre clé API est correcte et active (consultez Paramètres → Intégrations → Clé API).
• Assurez-vous d’envoyer une requête POST (et non GET). Votre développeur connaîtra la différence.
• Vérifiez que le champ customData.body n’est pas vide ou composé uniquement d’espaces.
• Vérifiez que le champ customData.fromId est inclus.
• Lisez le message de réponse pour obtenir les détails spécifiques de l’erreur.

Réponses n’atteignant pas votre plateforme #

• Assurez-vous d’avoir saisi l’URL de votre plateforme dans la carte Canal personnalisé sur la page Canaux. Si aucune URL n’est enregistrée, les réponses sont générées et stockées mais jamais envoyées — et elles ne seront pas marquées comme « Échouées », vérifiez donc ce point en premier.
• Vérifiez que l’URL est accessible publiquement (pas derrière une connexion ou un pare-feu) et qu’elle renvoie une réponse de succès.
• Seules les réponses (messages sortants) sont envoyées à votre URL — les messages entrants ne déclenchent pas cela.
• Vérifiez les détails de l’erreur sur le message dans votre boîte de réception.

Contact non créé #

• Assurez-vous que la valeur fromId est cohérente pour le même utilisateur sur tous ses messages. La plateforme utilise cette valeur pour identifier les contacts — si elle change entre les messages, la plateforme créera un nouveau contact à chaque fois.
• Incluez firstName, lastName et email dans le premier message d’un nouveau contact pour créer une fiche contact complète.

Pièces jointes multimédias ne fonctionnant pas #

• Pour les liens de fichiers (URL), assurez-vous que le fichier est accessible publiquement (aucune connexion requise pour y accéder).
• Incluez toujours mediaContentType lorsque vous incluez mediaUrl.
• Pour les fichiers intégrés (base64), vérifiez que le format est data:MIME_TYPE;base64,ENCODED_DATA.
• Assurez-vous que le type de fichier que vous spécifiez correspond au contenu réel du fichier.

Bonnes pratiques #

• Utilisez des valeurs fromId cohérentes. Chaque utilisateur sur votre plateforme doit toujours avoir le même fromId. Cela garantit que la plateforme regroupe tous ses messages dans une seule conversation au lieu de créer des contacts en double.
• Choisissez un nom channel clair. Choisissez quelque chose de descriptif comme "website-chat", "email" ou "zendesk" afin de pouvoir facilement identifier l’origine des messages lors de la consultation de votre boîte de réception.
• Incluez les coordonnées (firstName, lastName, email) dans le premier message d’un nouveau contact. Cela crée immédiatement une fiche contact complète et utile.
• Intégrez une logique de nouvelle tentative. Faites en sorte que votre plateforme réessaie d’envoyer les messages si la plateforme ne répond pas à la première tentative (les problèmes de réseau arrivent).
• Utilisez des valeurs messageSid uniques pour chaque message. Cela évite qu’un même message ne soit traité deux fois si votre système l’envoie plusieurs fois.
• Utilisez campaignId pour acheminer les messages vers différents agents IA lorsque vous avez plusieurs cas d’utilisation (par exemple, demandes commerciales vs questions de support).
• Testez avant la mise en ligne. Envoyez des messages de test dans les deux sens et vérifiez que les contacts, les conversations et les réponses de l’IA fonctionnent tous correctement avant le lancement auprès des utilisateurs réels.