Planification

Calendly

Connectez un compte Calendly et vos agents peuvent proposer de vraies disponibilités, réserver le rendez-vous, et relire ce qui est déjà planifié, le tout pendant l'appel.

Comment ça marche

Connectez un compte Calendly une fois, choisissez quels agents peuvent l'utiliser, et donnez à chacun une autorisation read ou write. Pendant un appel, l'agent peut proposer de vraies disponibilités et relire ce qui est déjà réservé, et avec write il peut réserver le rendez-vous, le tout sur votre compte réel. L'invité reçoit l'e-mail de confirmation de Calendly, et le rendez-vous se pose sur l'agenda derrière le type d'évènement. L'autorisation dit tout, et tout ce qui suit en découle.

ÉTAPE 01

Connectez votre compte Calendly

Il y a deux entrées, et les deux aboutissent à la même connexion. Un jeton d'accès personnel est l'intégration entière pour une équipe qui automatise son propre agenda : créez-en un dans les paramètres API de Calendly et envoyez-le. Il n'expire pas. OAuth est la façon dont le Calendly de quelqu'un d'autre devient le compte connecté : appelez l'endpoint d'autorisation, envoyez la personne vers l'URL renvoyée, et le callback termine la connexion en tant que celui qui a consenti. La connexion nécessite une clé API avec integrations:write ; relire les connexions nécessite integrations:read. Reconnecter Calendly remplace votre connexion précédente.

Connexion avec un jeton d'accès personnel

bash

curl -X POST https://api.aethexai.com/api/v1/integrations \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "calendly",
    "auth_type": "api_key",
    "access_token": "<your-calendly-token>",
    "display_name": "Sales calendar"
  }'

# 201 Created. The access token is never returned.
# Note the "id" it returns; every call below takes it.
export CONNECTION_ID=<the "id" from the response>

ÉTAPE 02

Autoriser un agent

Se connecter stocke l'identifiant ; cela ne le donne à personne. Une connexion sans agent est connectée mais inerte, donc aucun appel ne voit ses outils. Autorisez par agent, dans l'appel de connexion ou ensuite avec PUT /api/v1/integrations/{id}/agents, et la requête indique l'ensemble complet plutôt qu'un delta : les agents que vous envoyez sont ceux qui obtiennent l'accès, et une liste vide ne signifie personne. Chaque autorisation porte un niveau : read laisse l'agent citer l'agenda, et write ajoute la réservation. Un id d'agent qui n'est pas le vôtre revient en 404 plutôt qu'en 422, donc une réponse ne confirme jamais les lignes d'un autre. Une connexion accepte jusqu'à 200 agents.

Laisser un agent réserver, pas seulement citer

bash

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": "write" }
    ]
  }'

Ce que votre agent peut faire

Ce qu'un agent peut atteindre dépend du niveau qui lui a été accordé, et c'est fixé quand l'appel est assemblé : une action hors de l'autorisation n'est jamais proposée au modèle. Un agent en lecture seule ne refuse pas de réserver, il n'a aucune notion de réservation à refuser. Voici les outils, et l'autorisation que chacun exige.

Outil	Ce qu'il fait	Autorisation
`calendly_list_event_types`	Liste vos types de rendez-vous actifs avec la durée et la description de chacun. La disponibilité et la réservation partent toutes deux d'un type, donc celui-ci s'exécute en premier.	read
`calendly_list_available_times`	Renvoie les heures de début réservables pour un type de rendez-vous, jusqu'à 7 jours à l'avance. Les heures reviennent en UTC et l'agent les convertit dans le fuseau de l'appelant.	read
`calendly_list_upcoming_meetings`	Liste les rendez-vous encore à venir, du plus proche au plus loin, et peut être restreinte à l'adresse e-mail d'un seul invité.	read
`calendly_book_meeting`	Réserve une de ces heures pour l'appelant, après que l'agent a confirmé l'heure, le nom et l'e-mail à voix haute. Le succès renvoie les liens d'annulation et de replanification de Calendly.	write

Remarque

Dans le niveau accordé, chaque action est proposée par défaut. enabled_tools la restreint, et se règle au moment de la connexion, alors décidez-le au premier connect plutôt que de reconnecter pour l'ajouter plus tard, car reconnecter révoque la connexion déjà autorisée et vous donne un nouvel id.

Restreindre les outils au premier connect

bash

curl -X POST https://api.aethexai.com/api/v1/integrations \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "calendly",
    "auth_type": "api_key",
    "access_token": "<your-calendly-token>",
    "agents": [ { "agent_id": "<agent-uuid>", "access": "write" } ],
    "config": {
      "enabled_tools": [
        "calendly_list_event_types",
        "calendly_list_available_times",
        "calendly_book_meeting"
      ]
    }
  }'

Ce qu'exige une réservation

Calendly refuse une réservation qui ne correspond pas à la configuration du type d'évènement, donc Aethex lit d'abord cette configuration et indique à l'agent quoi recueillir pendant que l'appelant est encore en ligne.

Quoi	Requis	Notes
Nom et e-mail	Toujours	L'e-mail est là où Calendly envoie la confirmation et l'invitation d'agenda.
Fuseau horaire	Optionnel	Par défaut le fuseau de votre profil Calendly, ou UTC. Passez celui de l'appelant quand vous le connaissez.
Lieu	Parfois	Requis quand le type d'évènement offre un choix, ou demande un numéro de téléphone ou une adresse que seul l'appelant peut donner.
Questions requises	Parfois	Toute question configurée sur le type d'évènement doit avoir une réponse, sinon la réservation est refusée.

Astuce

Vérifier avant de réserver n'est pas qu'une politesse : Calendly compte une réservation refusée dans votre quota exactement comme une vraie, donc une requête qu'Aethex aurait pu savoir vouée à l'échec vous coûte autant qu'un rendez-vous.

Relire, et révoquer

Deux questions se posent dès qu'un agent est en service. Pour vérifier qu'une autorisation a pris, relisez-la avec GET /api/v1/integrations/{id}/agents, qui nécessite integrations:read ; aucun des endpoints de lecture ne renvoie jamais l'identifiant. Pour la désactiver, DELETE /api/v1/integrations/{id} nécessite integrations:write, et c'est idempotent, répondant 204 que la connexion ait été active, déjà révoquée, ou jamais la vôtre. La révocation prend effet immédiatement, y compris sur les appels déjà en cours.

Inspecter et révoquer une connexion

bash

# Which agents can use this connection, and at what level
curl https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID/agents \
  -H "X-API-Key: $AETHEX_API_KEY"

# Revoke it. Idempotent: 204 whether it was active or already gone.
curl -X DELETE https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID \
  -H "X-API-Key: $AETHEX_API_KEY"

Quand un appel échoue

Les trois appels ici sont se connecter, définir les agents, et révoquer, et ils n'échouent pas de la même façon, donc lisez l'étiquette de chaque carte. 401 et 403 s'appliquent à tout, lectures comprises, et se déclenchent avant tout traitement. Ensuite, se connecter peut renvoyer 404, 409, 422, 429 ou 503, définir les agents ne renvoie que 404 ou 409, et révoquer est idempotent et répond 204.

401Non autorisé

Chaque appel de cette page, avant tout traitement. Pas d'en-tête X-API-Key, ou une clé invalide, révoquée ou expirée.

Envoyez une clé valide. Missing API key signifie que l'en-tête n'est jamais arrivé ; Invalid or expired API key qu'il n'a pas correspondu.

403Interdit

Chaque appel, avant tout traitement. La clé est valide mais n'a pas le scope requis : integrations:write pour connecter, définir les agents ou révoquer, integrations:read pour les lectures.

Le détail nomme le scope manquant. Les scopes sont fixés à la création de la clé, alors créez une clé qui le porte plutôt que d'élargir celle-ci.

404Introuvable

Se connecter et définir les agents. La connexion n'est pas la vôtre ou n'est plus active, ou un agent_id n'est pas un de vos agents.

Vérifiez l'id de connexion de la réponse de connexion, et que chaque agent_id est un agent de ce tenant. Un id étranger est délibérément indistinct d'un id manquant.

409Conflit

Se connecter et définir les agents. Une requête concurrente a modifié la même connexion ou les mêmes autorisations.

Relisez la connexion, puis renvoyez. Le corps d'autorisation est déclaratif, donc une nouvelle tentative converge au lieu de s'accumuler.

422Entité non traitable

Se connecter, quand Calendly rejette l'identifiant qu'Aethex a validé. Tout appel portant un corps peut aussi renvoyer un 422 de schéma pour un champ mal formé.

Lisez le détail. Un 422 de schéma nomme le champ à corriger ; un 422 de connexion signifie que l'identifiant a été refusé, alors réémettez le jeton d'accès personnel depuis les paramètres API de Calendly.

429Trop de requêtes

Connexion seulement. Plus de 10 tentatives de connexion en 60 secondes depuis un même tenant.

Attendez la fenêtre indiquée dans l'en-tête Retry-After. Se connecter est une opération unique, donc ceci trahit souvent une boucle de tentatives à corriger.

503Service indisponible

Connexion seulement. Calendly était injoignable, la clé de chiffrement manque sur ce déploiement, ou le limiteur de débit est hors service.

Réessayez, et lisez le détail pour savoir lequel des trois. Une panne Calendly se résout seule ; une clé manquante ou un limiteur hors service est de notre côté et continue d'échouer jusqu'à correction.

Notes et limites

Quelques points à connaître avant de bâtir dessus.

Limite	Ce que cela signifie
Sept jours est le plafond	Calendly refuse une recherche de disponibilité plus large qu'une semaine, donc un agent ne peut pas proposer un créneau à trois semaines.
Ni annulation ni replanification	Aucune des deux n'est proposée comme action. L'agent transmet plutôt les liens d'annulation et de replanification de Calendly issus de la réservation.
Reconnecter efface les autorisations	Reconnecter Calendly révoque la connexion précédente et repart sans aucun agent, donc rien n'est conservé. Réautorisez-les ensuite.
Les autorisations s'appliquent au début de l'appel	Retirer une autorisation prend effet au prochain appel, pas à celui déjà en cours. Déconnecter agit immédiatement.
Un compte par connexion	Chaque action s'exécute en tant que l'utilisateur à qui appartient l'identifiant, sur les types d'évènement actifs de cet utilisateur. Une connexion ne voit jamais un second agenda.

Attention

Un créneau peut être pris entre le moment où l'agent le propose et le moment où il réserve. Aethex le signale comme son propre résultat, donc l'agent redemande les disponibilités et propose une autre heure au lieu de réessayer un créneau déjà parti.