Session Link

API développeur

Obtenez depuis vos propres systèmes un lien direct vers la conversation d’un client ; le client et la conversation sont créés s’ils n’existent pas encore.

• WhatsApp
• Instagram
• API REST

Installer depuis MonoStoreVoir sur monochat.ai

Présentation

Un seul appel API avec un canal et le numéro de téléphone ou l’e-mail d’un client renvoie un lien qui ouvre la conversation de ce client dans MonoChat. Si le client ou la conversation n’existe pas encore, ils sont créés.

Placez le lien dans votre CRM, votre help desk ou votre écran de commande et votre équipe passe directement de là au chat.

Points forts

• Ouvrir ou créer. Fonctionne pour un client sur un canal WhatsApp, Instagram ou autre donné, par numéro de téléphone ou e-mail.
• Orientez au passage. Attribuez la conversation à un agent, par identifiant ou e-mail, ou à un groupe de travail dans le même appel.
• Même client, même conversation. Appeler de nouveau pour le même client et le même canal renvoie la conversation existante.

Installation et configuration

1. Installez Session Link depuis Paramètres › MonoStore › Applications, ou ouvrez le lien d’installation app.monochat.ai/apps/vvKJe8Nbp4EQNy2KA. Sans compte MonoChat, le lien vous permet de vous inscrire d’abord, puis installe l’application pour vous.
2. Créez un jeton d’API sous Profil › Jetons d'API. Le jeton n’est affiché qu’une seule fois : copiez-le immédiatement. Consultez Jetons d’API.
3. Ouvrez Paramètres › Session Link API. La documentation qui s’y trouve indique l’adresse exacte du endpoint de votre espace de travail et des exemples de requêtes prêts à copier. Essayez l’exemple avec l’un de vos canaux.
4. Ajoutez un bouton « Discuter sur WhatsApp » à votre CRM, votre help desk ou votre écran de commande, qui appelle l’API et ouvre l’url renvoyée.

remarque

• Le lien ouvre MonoChat pour les personnes connectées et autorisées à voir cette conversation.
• L’appel ne fait qu’ouvrir la conversation ; il n’envoie aucun message au client. Utilisez WhatsApp Template API pour écrire en premier.

Fonctionnalités

Lien de conversation

La réponse fournit le lien qui ouvre la conversation dans MonoChat et l’identifiant de la conversation.

Client créé si nécessaire

Un nouveau client est créé avec le prénom et le nom que vous envoyez ; la réponse indique si le client était déjà connu.

Attribution

Attribuez à un agent par identifiant ou e-mail, ou à un groupe de travail.

Écran de documentation

La référence API avec l’adresse exacte des endpoints de votre espace de travail et des exemples de requêtes prêts à copier.

Référence de l’API

L’appel est une requête POST avec un corps JSON, authentifiée par un jeton d’API.

POST https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js
Authorization: Bearer <API_TOKEN>
Content-Type: application/json

• <slug> est le tenant slug de votre espace de travail, la partie après /tenants/ dans votre adresse MonoChat.
• <app-folder> est le dossier dans lequel l’application a été installée. L’écran Paramètres › Session Link API affiche l’adresse complète avec les deux valeurs renseignées.
• Créez le jeton sous Profil › Jetons d'API. Consultez Jetons d’API.

Champs de la requête

Champ	Obligatoire	Description
connectorBrand	oui	Le type de canal, par exemple whatsapp ou instagram.
channelUsername	oui	Le nom d’utilisateur de votre canal dans MonoChat, par exemple votre numéro WhatsApp sans +.
customer.identityType	oui	phoneNumber ou email.
customer.identity	oui	Le numéro de téléphone du client (indicatif du pays, sans +) ou son adresse e-mail.
customer.firstname, customer.lastname	non	Utilisés lorsque le client est nouveau dans MonoChat. Valeur par défaut : -.
assignment.type	non	agent (identifiant utilisateur de l’agent), agentIdentity (e-mail de l’agent) ou workgroup (identifiant du groupe de travail).
assignment.value	avec assignment.type	L’identifiant ou l’e-mail auquel attribuer la conversation.

Exemple de requête

curl --location 'https://app.monochat.ai/api/<slug>/custom-functions/<app-folder>/methods/session-link.js' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <API_TOKEN>' \
--data '{
  "connectorBrand": "whatsapp",
  "channelUsername": "905334445566",
  "customer": {
    "identityType": "phoneNumber",
    "identity": "905306667788",
    "firstname": "Ayşe",
    "lastname": "Yılmaz"
  },
  "assignment": { "type": "agentIdentity", "value": "sarah@yourcompany.com" }
}'

Réponse

{
  "result": {
    "url": "https://app.monochat.ai/tenants/<slug>?tab=messages&sessionTab=all&filter=…&_id=<sessionId>",
    "sessionId": "Zeii7vpeeFFnsJepZ",
    "isOldUser": true
  }
}

Champ	Description
url	Ouvre la conversation dans MonoChat.
sessionId	L’identifiant de la conversation. Le même client sur le même canal obtient toujours la même conversation.
isOldUser	false lorsque le client a été créé par cet appel.

Erreurs

Un appel qui échoue répond avec un statut d’erreur et un message :

Message	Cause
connectorBrand, channelUsername and customer fields are required	Un champ obligatoire de premier niveau est manquant.
customer.identityType must be one of: phoneNumber, email	identityType est manquant ou a une autre valeur.
customer.identity field is required	Le numéro de téléphone ou l’e-mail du client est manquant.
Channel not found	Aucun canal de ce type avec ce nom d’utilisateur dans votre espace de travail.
Customer Channel not found	Le client n’a pas pu être associé à une identité de canal.
Agent user not found	Aucun agent avec l’e-mail indiqué dans assignment.value.
401	L’en-tête Authorization est manquant ou le jeton est invalide.

Captures d’écran

Un CRM, un help desk et un écran de gestion des commandes ouvrant chacun la bonne conversation dans MonoChatAttribution de la conversation à un agent ou à un groupe de travail dans le même appel APIUn nouveau client et une nouvelle conversation créés automatiquement à partir de la requête APIUn seul appel API renvoie le lien de la conversationUn bouton « Discuter sur WhatsApp » dans un CRM ouvre la conversation du client en un clicAppeler de nouveau l’API pour le même client ouvre la conversation existante

FAQ

Session Link envoie-t-il un message au client ?

Non. Il ouvre ou crée seulement la conversation et renvoie un lien vers celle-ci. Pour écrire d’abord au client, utilisez l’application WhatsApp Template API.

Avec quels canaux fonctionne-t-il ?

WhatsApp, Instagram et les autres canaux connectés à votre espace de travail MonoChat. Vous indiquez dans la requête le type de canal et le nom d’utilisateur de votre canal.

Va-t-il créer des conversations en double ?

Non. Le même client sur le même canal obtient toujours la même conversation.

Qui peut ouvrir le lien ?

Les personnes connectées à MonoChat et autorisées à voir cette conversation.

Voir aussi

• WhatsApp Template API
• Applications MonoStore
• Paramètres du profil
• Groupes de travail