Zoho CRM
Connectez votre CRM Zoho et vos agents vocaux peuvent reconnaître l'appelant, consulter ses contacts, ses pistes et ses deals ouverts, tenir la fiche à jour et consigner les appels aboutis sur le contact, le tout pendant l'appel, dans votre propre Zoho.
Fonctionnement
Connectez votre CRM Zoho une fois, choisissez les agents autorisés à l'utiliser et donnez à chacun un accès en lecture ou en écriture. Aethex stocke la connexion chiffrée et transforme votre CRM en un petit ensemble d'actions qu'un agent peut appeler en cours d'appel, en décidant lui-même quand chacune est nécessaire. L'accès dit tout : la lecture permet à un agent de consulter, l'écriture lui permet de modifier votre CRM et de faire consigner ses appels aboutis. Tout ce qui suit découle de ce seul choix.
Centres de données de l'UE uniquement
Zoho répartit ses clients entre des centres de données indépendants — États-Unis, UE, Inde, Australie, Chine, Japon, Canada et Arabie saoudite — et chacun exploite son propre serveur de comptes. Aethex se connecte via celui de l'UE, accounts.zoho.eu : cette intégration fonctionne donc pour les organisations dont le compte Zoho réside dans le centre de données de l'UE. Vérifiez le vôtre en vous connectant à Zoho CRM et en lisant la barre d'adresse : une organisation de l'UE est servie depuis un domaine en .eu.
Connectez votre CRM Zoho
Zoho se connecte via OAuth : vous ne manipulez donc jamais de clé API. Appelez POST /api/v1/integrations/zoho/authorize avec une clé portant le scope integrations:write, et elle renvoie une authorize_url. Envoyez-y le navigateur du client : il se connecte à Zoho et approuve un écran de consentement qui accorde l'accès à ses contacts, pistes, deals, appels et notes. Zoho redirige ensuite vers Aethex, la connexion est créée, et le navigateur revient sur votre page d'intégrations. Aethex maintient ensuite la connexion, en rafraîchissant le jeton en arrière-plan.Vous obtenez une connexion Zoho active par espace de travail, et se reconnecter la remplace. Se reconsentir conserve vos réglages, les outils restreints et le nom d'affichage, mais pas vos accès d'agent : un nouveau consentement peut viser un autre compte, donc Aethex ne réoriente pas vos agents en silence. Accordez-leur l'accès de nouveau ensuite.
# 1. Start the connect flow. Returns the Zoho consent URL.
curl -X POST https://api.aethexai.com/api/v1/integrations/zoho/authorize \
-H "X-API-Key: $AETHEX_API_KEY"
# Response:
# { "authorize_url": "https://accounts.zoho.eu/oauth/v2/auth?client_id=...&state=..." }
# 2. Send the customer's browser to authorize_url. They sign in to Zoho and
# approve one consent screen. Zoho then redirects back to Aethex, the
# connection is created, and the browser lands on your integrations page.Accordez l'accès aux agents
La connexion stocke le lien ; elle ne le confie à rien. Une connexion sans agent est inerte : aucun appel ne voit ses outils et rien n'est écrit dans votre CRM. Accordez l'accès par agent avec PUT /integrations/{id}/agents. Ce PUT remplace tout l'ensemble : envoyez donc chaque agent qui doit conserver l'accès, pas seulement celui que vous ajoutez. Commencez en lecture (read) ; passez un agent en écriture (write) seulement lorsque vous voulez qu'il modifie des fiches et consigne des appels.
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
Ce qu'un agent peut atteindre est décidé à l'assemblage de l'appel : une action hors de son accès n'est jamais proposée au modèle, si bien qu'un agent en lecture seule n'a aucun moyen de modifier quoi que ce soit. Voici les outils, et l'accès requis par chacun.
| Outil | Ce qu'il fait | Accès |
|---|---|---|
zoho_lookup_contact | Trouve l'appelant par téléphone ou e-mail dans vos contacts et vos pistes, en un seul résultat, pour que l'agent puisse le saluer par son nom et reprendre là où la dernière conversation s'était arrêtée. Recherche à la fois sur les champs téléphone et mobile. | lecture |
zoho_get_contact | Lit le détail complet d'un contact ou d'une piste dont vous avez déjà l'id, lorsque l'agent a besoin de plus que ce que renvoie la recherche d'appelant. | lecture |
zoho_list_stages | Liste les étapes de pipeline que votre CRM utilise pour les deals ou les pistes, afin que l'agent connaisse le pipeline dans lequel il travaille. | lecture |
zoho_search_deals | Trouve les deals ouverts de l'appelant par contact, nom ou étape, pour que l'agent parle de ce qui est réellement en cours. | lecture |
zoho_record_caller | Crée un nouveau contact, ou une piste lorsqu'un nom d'entreprise est fourni, avec le numéro depuis lequel il a appelé déjà renseigné. Renvoie l'id de la nouvelle fiche. | écriture |
zoho_update_contact | Modifie un contact ou une piste précis dont vous avez déjà l'id. Seuls les champs que vous envoyez changent ; les autres restent tels quels. | écriture |
zoho_add_note | Ajoute une note à un contact, une piste ou un deal, pour un détail que l'appelant donne et qui a sa place sur la fiche plutôt que dans le journal d'appel. | écriture |
zoho_move_lead_stage | Déplace une piste ou un deal vers une autre étape de pipeline. Désactivé par défaut ; activez-le par connexion avec config.enabled_tools. | écriture, optionnel |
zoho_move_lead_stage est optionnel, car un changement d'étape est une décision à choisir explicitement. Pour l'activer, envoyez config.enabled_tools avec la liste complète des outils que la connexion doit exposer (c'est une liste blanche exacte, pas un ajout aux valeurs par défaut). Gardez zoho_log_call dans cette liste, ou la consignation automatique des appels ci-dessous s'arrête.Consignation automatique des appels
À la fin d'un appel, Aethex recherche l'appelant et consigne l'appel comme une activité d'appel sur son contact ou sa piste : le sujet, le sens, l'heure de début, la durée et un bref résumé de ce qui a été dit. Aucun appel d'outil ni invite nécessaire.
Importer des contacts comme listes d'appels
Une connexion Zoho peut aussi alimenter des listes d'appels à partir de votre CRM, sans exposer toute votre organisation. Listez ce que vous pouvez importer avec GET /integrations/{id}/imports/entities — Contacts et Leads, et uniquement ceux que cette connexion peut réellement lire — 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é. 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.
Sécurité
Le jeton OAuth est chiffré au repos et n'est jamais renvoyé par aucun endpoint. Aethex dialogue avec Zoho en HTTPS public, ne suit pas les redirections et fixe un délai d'expiration de 9 secondes par requête. Les accès en lecture et en écriture sont appliqués par agent, et les scopes que vous avez approuvés sur l'écran de consentement s'appliquent en plus : un accès ne peut donc que restreindre ce que ce compte Zoho pouvait déjà faire. La connexion est limitée à votre espace de travail : aucun autre locataire ne peut la lister, l'accorder ou l'atteindre.
Erreurs
Les appels de connexion et d'outil renvoient ces statuts.
Zoho a rejeté le jeton d'accès, le plus souvent parce que le consentement a été révoqué dans Zoho ou que le jeton ne peut plus être rafraîchi.
Reconnectez pour relancer le flux de consentement, puis accordez de nouveau l'accès à vos agents.
Le consentement approuvé ne couvre pas l'opération tentée par l'agent : Zoho l'a donc refusée.
Reconnectez et approuvez l'écran de consentement complet, qui accorde les contacts, pistes, deals, appels et notes.
La connexion n'est pas celle de cet espace de travail ou n'est plus active, ou un agent_id de l'appel d'accès n'est pas l'un de vos agents.
Vérifiez l'id de connexion, et que chaque agent_id est un agent de ce locataire. Un id étranger est volontairement indiscernable d'un id manquant.
Le nom du fournisseur n'a pas été reconnu lors de l'appel de connexion.
Lisez le message ; il nomme le problème précis. Utilisez zoho comme fournisseur.
La limite de débit de connexion par locataire a été dépassée.
Patientez et réessayez après la fenêtre Retry-After. La connexion est une configuration ponctuelle : cela signale donc souvent une boucle de tentatives à corriger.
Zoho était injoignable, la clé de chiffrement n'est pas configurée, ou le magasin d'état de connexion est hors ligne.
Transitoire ; réessayez sous peu.
Notes et limites
Quelques points à connaître avant de bâtir dessus.
| Limite | Détail |
|---|---|
| Une connexion par espace de travail | Un espace de travail ne détient qu'une connexion Zoho active : connecter un second compte remplace le premier et emporte ses accès d'agents. |
| Le téléphone n'est pas une clé unique | Aethex recherche sur les champs téléphone et mobile, et renvoie les correspondances ambiguës comme candidats à désambiguïser par l'agent plutôt que de deviner de quelle fiche il s'agit. |
| Reconnectez pour élargir l'accès | Le jeton porte exactement les scopes que vous avez approuvés. Si vous voulez que l'agent atteigne davantage de votre CRM, reconnectez et approuvez le consentement plus large ; un nouveau consentement conserve vos réglages mais pas vos accès d'agent, alors accordez-les de nouveau. |
| L'enregistrement n'est pas un upsert atomique | Enregistrer un appelant est une recherche puis écriture : deux appelants simultanés avec le même nouveau numéro peuvent donc créer des fiches en double. |