Google Calendar

Bêta

Ce connecteur est en bêta. Il fonctionne de bout en bout et peut servir sur de vrais agendas, mais la surface peut encore changer avant la disponibilité générale, alors ne figez pas d'automatisation sur des noms d'outils ou des formes de réponse précis pour l'instant.

Comment ça marche

Connectez un compte Google une fois, choisissez quels agents peuvent l'utiliser, et donnez à chacun une autorisation read ou write. Pendant un appel, l'agent peut consulter les disponibilités et proposer des créneaux libres, et avec write il peut aussi réserver, replanifier et annuler, le tout comme des évènements ordinaires visibles dans Google Calendar. L'autorisation dit tout, et tout ce qui suit en découle.

Connecter un agenda

La connexion est un flux de consentement OAuth, donc elle nécessite un navigateur une fois : le propriétaire de l'agenda approuve l'accès chez Google. Aethex vous donne l'URL vers laquelle l'envoyer, et vous ne voyez jamais ses identifiants. Les appels authorize et d'autorisation nécessitent une clé API avec integrations:write ; lire les connexions nécessite integrations:read.

1. 01

   Demander une URL de consentement

   Renvoie l'URL Google à ouvrir. Elle est à usage unique et valable 10 minutes, alors générez-la quand la personne est prête à cliquer.

   bash

   curl -X POST https://api.aethexai.com/api/v1/integrations/google_calendar/authorize \
     -H "X-API-Key: $AETHEX_API_KEY"
   
   # { "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth?..." }

2. 02

   L'ouvrir et approuver

   Le propriétaire de l'agenda se connecte chez Google et approuve les deux permissions. Google redirige vers Aethex, qui termine l'échange. Confirmez le résultat depuis l'API, pas depuis l'endroit où le navigateur s'arrête.

3. 03

   Confirmer la connexion

   La connexion est active dès qu'elle apparaît avec status: active. Notez son id, car les appels d'autorisation et de déconnexion le prennent tous les deux. agents revient vide, ce qui signifie qu'aucun agent ne peut encore l'utiliser.

   bash

   # Keep the id: the grant and disconnect calls below both take it.
   CONNECTION_ID=$(curl -s https://api.aethexai.com/api/v1/integrations \
     -H "X-API-Key: $AETHEX_API_KEY" \
     | jq -r '.data[] | select(.provider == "google_calendar") | .id')

Autoriser des agents

Un agenda connecté appartient au compte, pas à un agent, donc il n'atteint un agent que lorsque vous l'autorisez. Donnez à un agent read pour consulter les disponibilités et proposer des créneaux, ou write pour aussi réserver, replanifier et annuler. L'appel d'autorisation est déclaratif : il remplace tout l'ensemble, et une liste vide révoque tout le monde. Les autorisations sont lues au début d'un appel, donc un changement s'applique au prochain appel, pas à celui déjà en cours. Replanifier et annuler n'agissent que sur un rendez-vous que l'agent a réservé pendant le même appel, car ils ont besoin de son id d'évènement et l'agent ne peut pas chercher dans l'agenda un rendez-vous qu'il n'a pas créé.

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": "6b1e...", "access": "write" },
      { "agent_id": "9d02...", "access": "read"  }
    ]
  }'

L'accès approuvé

La connexion demande à Google exactement deux permissions, et rien d'autre. La permission plus large qui pourrait lire la liste de vos agendas, ses paramètres, ou avec qui il est partagé est un scope Google différent, et Aethex ne le demande pas.

Codes de statut à connaître

Ceux que vous rencontrerez le plus en câblant tout cela. 401 et 403 peuvent venir de n'importe quel appel ; 404 et 409 viennent de l'appel d'autorisation ; 422 et 503 viennent de authorize.

Déconnecter

Supprime la connexion et l'accès stocké immédiatement, y compris sur les appels en cours, donc la prochaine action d'agenda dans un appel en direct échoue. Cela ne touche pas l'agenda lui-même, donc les rendez-vous déjà réservés restent en place. La déconnexion est idempotente et renvoie 204 que la connexion ait été active, déjà supprimée, ou jamais existante. Vous pouvez aussi révoquer l'accès depuis les paramètres d'accès tiers du compte Google ; la connexion passe alors à status: error lors de son prochain rafraîchissement de jeton.

curl -X DELETE https://api.aethexai.com/api/v1/integrations/$CONNECTION_ID \
  -H "X-API-Key: $AETHEX_API_KEY"

# 204 No Content

Si quelque chose ne marche pas

Le petit nombre de choses qui expliquent en général un agenda qui semble cassé.