Freshdesk
Connectez votre helpdesk Freshdesk pour que les agents répondent aux questions sur les tickets pendant l'appel, ouvrent des tickets pour les appelants, et consignent chaque appel abouti sous forme de ticket.
Comment ça marche
Trois choses deviennent possibles une fois Freshdesk connecté.Un agent à qui vous accordez read peut retrouver l'appelant dans vos contacts, consulter l'un de ses tickets et lister ceux qui restent ouverts — ainsi « où en est mon ticket » trouve une réponse pendant l'appel, au lieu de devenir un ticket de plus.Un agent à qui vous accordez write peut en plus ouvrir un ticket, changer son statut, sa priorité ou son groupe, et laisser une note à celui qui le reprendra.Et chaque appel abouti est consigné comme ticket après le raccrochage, avec le résumé de l'appel dans la description, pour les agents autorisés en write. Vous avez une connexion Freshdesk active par espace de travail, et se reconnecter la remplace.
Connecter Freshdesk
Freshdesk s'authentifie avec une clé API, pas avec OAuth — son flux OAuth n'existe que pour les applications publiées sur la Marketplace Freshworks. Trouvez votre clé dans Freshdesk sous votre photo de profil, Profile settings, dans le panneau *Your API Key*.Envoyez-la avec l'URL du compte à laquelle elle appartient. La clé seule ne dit pas quel helpdesk elle ouvre : base_url est donc obligatoire et doit être votre propre adresse https://votre-sous-domaine.freshdesk.com — rien d'autre n'est accepté. L'appel exige une clé API Aethex portant le scope integrations:write.La clé Freshdesk hérite des permissions de l'agent à qui elle appartient. Quelqu'un qui ne voit pas les tickets d'un groupe dans Freshdesk ne les verra pas ici non plus : c'est le moyen le plus simple de garder cette connexion plus étroite que tout votre helpdesk.
curl -X POST https://api.aethexai.com/api/v1/integrations \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"provider": "freshdesk",
"auth_type": "api_key",
"base_url": "https://acme.freshdesk.com",
"access_token": "'"$FRESHDESK_API_KEY"'"
}'
# Aethex checks the key against your helpdesk before storing it, so a wrong
# key or the wrong account URL comes back as a 422 rather than failing later.Autoriser les agents
Une connexion n'atteint aucun agent avant que vous ne le disiez, et read est la valeur par défaut. Une autorisation read enregistre les quatre outils de consultation ; une autorisation write ajoute l'ouverture de tickets, leur mise à jour et les notes. La liste est déclarative — envoyez tous les agents qui doivent y accéder, car un agent que vous omettez est un agent dont vous retirez l'accès.Les autorisations ne survivent pas à une reconnexion. Rien ne permet de distinguer un simple changement de clé sur le même helpdesk d'un basculement vers un autre : autorisez donc de nouveau ensuite.
curl -X PUT https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID/agents \
-H "X-API-Key: $AETHEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agents": [
{ "agent_id": "<agent-uuid>", "access": "read" }
]
}'Ce qu'un agent peut faire
Neuf outils parviennent à l'agent pendant l'appel, et un dixième est réservé à la consignation de l'appel après coup. Restreignez l'ensemble pour une connexion en nommant les outils souhaités dans config.enabled_tools lors de la connexion ; une liste vide les désactive tous.
| Outil | Ce qu'il fait | Autorisation |
|---|---|---|
freshdesk_lookup_contact | Retrouve l'appelant dans vos contacts par numéro de téléphone ou e-mail. | read |
freshdesk_get_ticket | Lit un ticket par son numéro, avec son statut, sa priorité et son demandeur. | read |
freshdesk_search_tickets | Liste les tickets d'un demandeur, éventuellement ceux d'un seul statut. | read |
freshdesk_list_groups | Liste les groupes vers lesquels router un nouveau ticket. | read |
freshdesk_create_ticket | Ouvre un ticket pour l'appelant et lui en communique le numéro. | write |
freshdesk_update_ticket | Change le statut, la priorité, le groupe ou les tags d'un ticket. | write |
freshdesk_add_note | Ajoute une note à un ticket, privée pour votre équipe sauf indication contraire. | write |
freshdesk_create_contact | Enregistre l'appelant comme contact à partir de son adresse e-mail. Si cette adresse existe déjà, la fiche correspondante est renvoyée plutôt que dupliquée, complétée des informations qui lui manquaient ; celles qu'elle contient déjà sont laissées intactes. Un appelant sans e-mail est enregistré en ouvrant son ticket. | écriture |
freshdesk_update_contact | Corrige le nom, l'e-mail ou le numéro d'un contact. Seuls les champs fournis changent. | écriture |
Consigner les appels aboutis
Chaque appel abouti sur un agent autorisé en write est consigné comme ticket Freshdesk après le raccrochage. L'objet indique le sens de l'appel et le numéro de l'appelant ; la description porte l'heure de début, la durée, le résultat et le résumé de l'appel dès que la transcription est analysée. Le ticket est tagué aethex et voice-call, ce qui vous permet de les exclure d'une vue ou d'en construire une rien que pour eux.La source est toujours Phone, pour que vos propres rapports par source gardent un sens. Le demandeur est le numéro de l'appelant, et Freshdesk le rapproche d'un contact existant ou en crée un — Aethex ne crée jamais de contacts lui-même.Pour désactiver cela sur une connexion, nommez les outils que vous voulez dans config.enabled_tools en laissant freshdesk_log_call de côté.
Importer des contacts comme listes d'appels
Une connexion Freshdesk peut aussi alimenter des listes d'appels à partir des personnes enregistrées dans votre helpdesk. Listez ce que vous pouvez importer avec GET /integrations/{id}/imports/entities, voyez les champs sûrs avec GET /integrations/{id}/imports/fields?entity=contacts, prévisualisez un échantillon validé avec POST /integrations/{id}/imports/preview, et lisez les lignes paginées avec POST /integrations/{id}/imports/page. phone et mobile sont tous deux proposés comme sources d'appel, dans cet ordre de priorité, et vos propres champs de contact personnalisés sont proposés à côté des champs standard. Les champs sensibles comme les coordonnées bancaires, les jetons et les identifiants nationaux ne sont jamais proposés, et le flux est en lecture seule jusqu'à ce que vous lanciez l'import.
Erreurs
Ce que répondent les appels de connexion et d'autorisation, et quoi faire.
Votre clé API Aethex est absente ou incorrecte, ou elle ne porte pas integrations:write.
Envoyez une clé API Aethex valide portant le scope integrations.
Un identifiant d'agent de la liste ne vous appartient pas, ou a été supprimé. Un 404 plutôt qu'un 422, volontairement : un 422 confirmerait que l'identifiant existe dans l'espace de travail de quelqu'un d'autre.
Vérifiez les identifiants d'agents dans votre propre liste d'agents.
Deux appels de connexion Freshdesk se sont croisés, et c'est l'autre qui a créé la connexion.
Consultez votre liste d'intégrations — la connexion y est déjà, il n'y a rien à réessayer.
Freshdesk a rejeté la clé, ou base_url est absente, comporte un chemin, ou n'est pas une adresse .freshdesk.com.
Vérifiez la clé dans Profile settings sur Freshdesk, et envoyez l'URL du compte sans chemin après l'hôte.
Plus de dix tentatives de connexion pour cet espace de travail en une minute.
Attendez l'intervalle Retry-After. Se connecter coûte un aller-retour vers Freshdesk plus une écriture : c'est donc plafonné.
Freshdesk était injoignable ou a renvoyé une erreur serveur, ou une dépendance côté serveur n'est pas configurée.
Réessayez dans un instant. Si cela persiste, Freshdesk est en panne ou le déploiement n'a pas sa clé de chiffrement.
Limites à connaître
Là où cette connexion s'arrête, pour qu'aucune de ces limites ne surprenne plus tard.
| Limite | Détail |
|---|---|
| Clé API uniquement | Il n'y a pas de flux de consentement. Demander une URL d'autorisation Freshdesk est refusé, car son OAuth n'est ouvert qu'aux applications de la Marketplace. |
| Un numéro de téléphone n'identifie pas un appelant | Freshdesk considère une adresse e-mail comme unique : enregistrer un appelant qui en a déjà une renvoie sa fiche au lieu de la dupliquer — et n'y complète que ce qui manquait, l'adresse ayant été entendue au téléphone et pouvant appartenir à quelqu'un d'autre. Corriger une information déjà présente est une étape distincte et volontaire. Freshdesk n'impose aucune contrainte sur les numéros de téléphone, volontairement : standards et lignes familiales figurent sur plusieurs contacts à la fois. Enregistrer un appelant à partir de son seul numéro est donc refusé — Aethex oriente l'agent vers l'ouverture d'un ticket, où Freshdesk rapproche lui-même le numéro d'un contact existant ou en crée un. Un appelant sans e-mail se retrouve ainsi avec une seule fiche. |
| Un helpdesk par connexion | base_url doit être votre propre adresse .freshdesk.com. Un domaine de helpdesk personnalisé n'est pas accepté, ni une URL comportant un chemin. |
| Une connexion par espace de travail | Se reconnecter à Freshdesk retire la connexion précédente, et ses autorisations d'agents avec elle. |
| La source est toujours Phone | Un agent ne peut pas étiqueter un ticket comme e-mail ou chat : les appels restent donc identifiables dans vos rapports. |
| Les appelants sans e-mail sont nommés par leur numéro | Freshdesk exige un nom dès que le seul identifiant du demandeur est un numéro de téléphone. Quand l'agent n'a pas appris le nom de l'appelant, Aethex utilise le numéro comme nom plutôt que de renoncer à créer le ticket. |
| Le rapprochement des contacts est exact | Freshdesk retire les espaces, parenthèses, tirets et points d'un numéro de téléphone lorsqu'il l'enregistre, et le rapproche ensuite à l'identique. Aethex envoie les numéros sous cette même forme, pour qu'une recherche retrouve ce qu'un ticket a créé. Sa recherche de contacts par numéro accuse aussi jusqu'à dix secondes de retard sur un nouveau contact (mesuré) : un appelant ajouté en pleine conversation peut n'être trouvable qu'un instant plus tard — c'est pourquoi rien ne détermine à partir de cette recherche si un appelant est nouveau. La recherche par adresse e-mail n'est pas concernée. |
| Seuls les tickets récents sont listés | La liste des tickets de Freshdesk renvoie les tickets créés au cours du dernier mois environ ; les plus anciens en sont absents. Un agent qui demande ce qu'un appelant a en cours voit donc ses tickets récents, et une réponse vide signifie « rien de récent » plutôt que « rien du tout ». |
| Les quotas sont à l'échelle du compte | Freshdesk autorise de 3 000 à 5 000 appels API par heure selon votre offre, partagés avec vos autres intégrations, et applique la limite par minute — une fenêtre de 50 appels qui se reconstitue en moins d'une minute. Un appel d'outil limité indique à l'agent de s'arrêter plutôt que de retenter contre le même mur. |