API d’équipe #

Votre équipe se compose de toutes les personnes travaillant dans votre compte en dehors de vous — administrateurs, agents et lecteurs en lecture seule — ainsi que des invitations que vous avez envoyées et des départements dans lesquels vous les organisez. L’API d’équipe est la version programmatique de Paramètres → Équipe : ajoutez et supprimez des personnes, définissez ce que chacune d’entre elles peut voir et faire, envoyez et relancez des invitations, et gérez les départements.

Tous les points de terminaison ci-dessous sont relatifs à l’URL de base https://api.youraiconnector.com/v1. Pour la version tableau de bord de tout ce qui figure sur cette page, consultez Gestion d’équipe.

Authentification : ces points de terminaison nécessitent une personne connectée #

C’est la seule partie de l’API qu’une clé API ne peut pas utiliser. Chaque point de terminaison /team, à l’exception de ceux relatifs aux départements, doit être appelé avec un jeton d’ID Firebase provenant d’une session connectée :

Authorization: Bearer <Firebase ID token>

Envoyez une clé API à la place et la requête sera rejetée avec une erreur 401 :

{
  "success": false,
  "error_code": 401,
  "error": "This endpoint requires a Firebase ID token (Authorization: Bearer <token>)."
}

La raison est que ces points de terminaison décident de ce qu’il faut faire en fonction de qui est connecté : votre rôle, la limite de ce que vous êtes autorisé à accorder à quelqu’un d’autre, et si vous travaillez actuellement dans un autre compte. Une clé API est une intégration, pas une personne, il n’y a donc personne à qui ces règles peuvent s’appliquer.

En pratique, cela signifie que l’API d’équipe est destinée à une application propriétaire avec un utilisateur Your AI Connector connecté (voir Authentification → Jeton d’ID Firebase). Une intégration serveur à serveur ne peut pas gérer les membres de l’équipe — il n’y a aucun moyen de générer l’un de ces jetons depuis l’extérieur de l’application.

L’exception : les quatre points de terminaison département sont des points de terminaison d’API ordinaires. Ils acceptent votre clé API exactement comme le reste de l’API, ainsi qu’une session connectée.

Chaque réponse sur cette page suit l’enveloppe habituelle : success: true plus les champs du point de terminaison au niveau supérieur, ou success: false avec error et error_code en cas de problème.

Rôles et autorisations #

Chaque membre de l’équipe a un rôle, qui définit son accès par défaut dans 12 zones de l’application. Vous pouvez ensuite remplacer les paramètres de zones individuelles.

Chaque zone est définie sur l’un des quatre niveaux : none (masqué), view (lecture seule), edit (créer et modifier), full (incluant la suppression).

Pour déroger aux valeurs par défaut du rôle, envoyez permission_overrides — un tableau d’objets { "area": ..., "level": ... }. Chaque entrée remplace la valeur par défaut du rôle pour cette zone spécifique ; tout ce que vous ne listez pas conserve la valeur par défaut du rôle.

"permission_overrides": [
  { "area": "analytics", "level": "full" },
  { "area": "billing", "level": "none" }
]

Qui peut appeler ces points de terminaison

• Le propriétaire du compte peut toujours tout faire.
• Un membre de l’équipe a besoin de team_management au niveau view pour lire la liste des membres et la liste des invitations, et au niveau edit pour ajouter, modifier, suspendre, supprimer, inviter, annuler ou renvoyer. Les administrateurs ont edit par défaut ; les éditeurs et les lecteurs ont none, donc par défaut, seuls les administrateurs peuvent gérer l’équipe.
• Personne ne peut accorder un accès supérieur au sien. Si vous essayez de donner à quelqu’un un niveau que vous ne possédez pas vous-même — ou de modifier, suspendre ou supprimer quelqu’un dont l’accès est déjà plus étendu que le vôtre — la requête est refusée avec 403 et un message nommant la zone.

L’objet membre de l’équipe #

GET /team/members renvoie un de ces objets par membre :

Les membres supprimés ne sont pas renvoyés — la liste ne contient que les membres actifs et suspendus.

Les limites de visibilité sont en écriture seule ici. contact_scope, contact_scope_axes et sub_account_access (voir Limiter ce qu’un membre peut voir) peuvent être définis lors de la création, de la mise à jour et de l’invitation, mais ce point de terminaison ne les renvoie pas.

Lister les membres de l’équipe #

GET /team/members

Renvoie la liste des membres ainsi que le nombre de sièges de votre forfait, afin que vous puissiez afficher « 3 sièges sur 5 » et savoir quand une invitation est sur le point d’être refusée.

cURL

curl "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  headers: { Authorization: `Bearer ${idToken}` },
});
const { members, seat_limit, seats_used } = await res.json();

Python

import requests

res = requests.get(
    "https://api.youraiconnector.com/v1/team/members",
    headers={"Authorization": f"Bearer {id_token}"},
)
data = res.json()

Réponse

{
  "success": true,
  "members": [
    {
      "account_owner_uid": "owner_uid_123",
      "member_uid": "uid_alice",
      "member_email": "alice@example.com",
      "member_display_name": "Alice Chen",
      "role": "admin",
      "permission_overrides": [],
      "status": "active",
      "auto_assign_enabled": true,
      "created_by": "owner_uid_123",
      "created_at": "2026-05-01T10:00:00.000Z",
      "updated_at": "2026-06-02T09:15:00.000Z"
    }
  ],
  "seat_limit": 5,
  "seats_used": 3
}

seat_limit est null lorsque votre forfait n’a pas de limite de sièges. seats_used ne compte que les membres actifs — suspendre ou supprimer quelqu’un libère immédiatement son siège.

Ajouter un membre de l’équipe directement #

POST /team/members

Ajoute quelqu’un à votre équipe immédiatement, sans invitation.

Ceci n’envoie aucun e-mail. Personne n’est informé de son ajout, et s’ils ne possèdent pas déjà un identifiant Your AI Connector, le compte créé pour eux n’a aucun mot de passe, ils ne peuvent donc pas se connecter avant de l’avoir réinitialisé. Utilisez Envoyer une invitation sauf si vous avez votre propre moyen d’en informer la personne et de lui permettre de se connecter.

Champs de la requête

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "role": "editor"
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/members", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email: "sam@example.com",
    display_name: "Sam Rivera",
    role: "editor",
  }),
});
const { member_uid } = await res.json();

Réponse — 201 Created

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "member_uid": "uid_sam",
  "message": "Team member created successfully."
}

Ajouter quelqu’un qui a été précédemment suspendu ou supprimé le rétablit au lieu d’échouer.

Mettre à jour un membre de l’équipe #

PATCH /team/members/{memberUid}

Modifie le rôle, les permissions, la visibilité, l’accès client d’un membre, ou sa participation à l’attribution automatique des contacts. Envoyez uniquement les champs que vous souhaitez modifier ; tout ce que vous omettez conserve sa valeur actuelle.

Champs de la requête

Ceci est le seul point de terminaison où null signifie « effacer ». Envoyer "contact_scope": null, "contact_scope_axes": null ou "sub_account_access": null supprime complètement cette limite et permet au membre de tout voir à nouveau. Lors de la création et de l’invitation, null signifie simplement « non fourni ».

cURL

curl -X PATCH "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "admin",
    "permission_overrides": [{ "area": "billing", "level": "none" }]
  }'

Réponse

{
  "success": true,
  "message": "Team member updated successfully."
}

Suspendre un membre de l’équipe #

POST /team/members/{memberUid}/suspend

Suspend quelqu’un : il conserve sa place dans l’équipe mais perd l’accès. Utilisez ceci au lieu de la suppression lorsque la pause est temporaire — ramenez-le avec PATCH /team/members/{memberUid} et {"status": "active"}.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/members/uid_sam/suspend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Réponse

{
  "success": true,
  "message": "Team member suspended successfully."
}

Un membre suspendu libère sa place, vous pouvez donc inviter quelqu’un d’autre à sa place. Son accès prend fin lors du prochain rafraîchissement de son jeton de session actuel, ce qui peut prendre jusqu’à une heure — supprimez-le plutôt si vous avez besoin que ce soit immédiat.

Supprimer un membre de l’équipe #

DELETE /team/members/{memberUid}

Supprime une personne de votre équipe et libère sa licence. Elle est déconnectée et perd l’accès à votre compte ; ses propres identifiants restent inchangés.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/members/uid_sam" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Réponse

{
  "success": true,
  "message": "Team member removed successfully."
}

La suppression est définitive de votre côté : un membre supprimé ne peut pas être réactivé via le point de terminaison de mise à jour — invitez-le à nouveau si vous changez d’avis. Son adresse e-mail est également retirée de la liste de notification de votre compte.

Limiter ce qu’un membre peut voir #

Trois champs optionnels, acceptés lors de l’ajout (add), de la mise à jour (update) et de l’invitation (invite), déterminent quelle partie du compte une personne peut voir. Ils se cumulent : un membre limité par plusieurs critères est restreint par l’ensemble de ceux-ci.

contact_scope — all (par défaut : tous les contacts et conversations) ou assigned (uniquement ceux qui leur sont assignés). Avec assigned, ajoutez "contact_scope_unassigned": true pour leur permettre également de voir les contacts qui n’appartiennent encore à personne.

contact_scope_axes — les limite aux agents, canaux ou départements nommés :

Les IDs des agents et des départements ne sont pas vérifiés lors de l’enregistrement — un ID inexistant ne correspond simplement à rien, ce qui se traduit par une boîte de réception vide plutôt que par une erreur. Les noms des canaux sont vérifiés : un nom non reconnu est rejeté avec 400.

Aucun de ces trois éléments ne peut être défini pour le propriétaire du compte — cette requête est refusée avec 400.

Lister les invitations #

GET /team/invites

Les invitations que vous avez envoyées, de la plus récente à la plus ancienne, afin que vous puissiez voir qui n’a pas encore accepté.

Paramètres de requête

cURL

curl "https://api.youraiconnector.com/v1/team/invites?status=pending" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Réponse

{
  "success": true,
  "invites": [
    {
      "id": "inv_abc123",
      "account_owner_uid": "owner_uid_123",
      "account_owner_display_name": "Acme Ltd",
      "invitee_email": "sam@example.com",
      "invitee_uid": null,
      "role": "editor",
      "permission_overrides": [],
      "status": "pending",
      "created_by": "owner_uid_123",
      "created_at": "2026-06-10T12:00:00.000Z",
      "expires_at": "2026-06-17T12:00:00.000Z",
      "responded_at": null
    }
  ]
}

Le jeton d’invitation n’est jamais renvoyé — il n’existe que dans l’e-mail qui a été envoyé.

Envoyer une invitation #

POST /team/invites

Envoie par e-mail une invitation à rejoindre votre équipe. C’est la méthode habituelle pour ajouter un coéquipier : il clique sur le lien, se connecte avec ses propres identifiants et accepte. S’il ne possède pas encore de compte Your AI Connector, un compte est créé pour lui et l’e-mail le guide pour définir un mot de passe.

Champs de la requête

Configurer les autorisations à l’avance signifie que vous n’avez pas à modifier le membre par la suite — tout est copié sur son adhésion lorsqu’il accepte.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "email": "sam@example.com", "role": "editor" }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/invites", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${idToken}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "sam@example.com", role: "editor" }),
});
const { invite_id } = await res.json();

Réponse — 201 Created

{
  "success": true,
  "invite_id": "inv_abc123",
  "message": "Team invite sent successfully."
}

Points à prévoir

• Les invitations expirent après 7 jours. Une invitation expirée peut être renvoyée, ce qui déclenche une nouvelle période de 7 jours.
• Les invitations en attente occupent une place. Contrairement à l’ajout direct d’un membre, la vérification des places ici compte les membres actifs plus les invitations en attente. Ainsi, un compte dont toutes les places sont occupées sera refusé avant l’envoi de l’e-mail.
• 20 invitations par jour, comptées par compte, incluant les envois et les renvois.

Annuler une invitation #

DELETE /team/invites/{inviteId}

Annule une invitation avant qu’elle ne soit acceptée. Le lien dans l’e-mail cesse de fonctionner.

cURL

curl -X DELETE "https://api.youraiconnector.com/v1/team/invites/inv_abc123" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Réponse

{
  "success": true,
  "message": "Team invite cancelled."
}

Les invitations pending et expired peuvent être annulées. Une invitation déjà acceptée, refusée ou annulée renvoie 400 ; une invitation qui n’est pas la vôtre renvoie 403 ; un identifiant inconnu renvoie 404.

Renvoyer une invitation #

POST /team/invites/{inviteId}/resend

Renvoie l’e-mail d’invitation — utile s’il a été manqué ou s’il est arrivé dans les courriers indésirables. Fonctionne pour les invitations pending et expired, et réinitialise la date d’expiration à 7 jours à partir de maintenant.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/inv_abc123/resend" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Réponse

{
  "success": true,
  "message": "Team invite resent successfully."
}

Le nouvel e-mail contient un nouveau lien, et l’ancien lien continue également de fonctionner, de sorte qu’une personne qui retrouverait le premier e-mail plus tard ne soit pas bloquée. Le renvoi est comptabilisé dans la même limite de 20 par jour que l’envoi initial, et la réactivation d’une invitation expirée vérifie à nouveau vos sièges — un forfait complet sera refusé avec 429.

Accepter une invitation #

POST /team/invites/accept

Accepte une invitation avec le jeton provenant de l’e-mail d’invitation, ajoutant la personne connectée à l’équipe de ce compte.

Il s’agit d’un acte lié à votre propre identité. Connectez-vous en tant que vous-même — l’action est délibérément refusée avec 403 si vous travaillez au sein du compte de quelqu’un d’autre.

Champs de la requête

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/accept" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Réponse

{
  "success": true,
  "team_member_id": "owner_uid_123_uid_sam",
  "account_owner_uid": "owner_uid_123",
  "message": "Team invite accepted successfully."
}

Refuser une invitation #

POST /team/invites/decline

Refuse une invitation avec le jeton provenant de l’e-mail. Tout comme pour l’acceptation, il s’agit d’un acte lié à votre propre identité et l’action est refusée si vous travaillez au sein d’un autre compte.

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/invites/decline" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "invite_token": "1f4c…" }'

Réponse

{
  "success": true,
  "message": "Team invite declined."
}

Départements #

Un département est un groupe nommé au sein de votre équipe — Ventes, Support client, RH. Il permet d’attribuer une équipe responsable à un prospect, de prendre en charge de nouvelles conversations de manière autonome et peut être utilisé pour limiter ce qu’un membre peut voir.

Ces quatre points de terminaison nécessitent une clé API. Contrairement au reste de cette page, ils s’authentifient comme tout autre point de terminaison de l’API (voir Authentification). Une session connectée fonctionne également : la lecture nécessite contacts sur view, et la création, la modification ou la suppression nécessite team_management sur edit.

L’objet département

Lorsque routing_agents et routing_channels sont tous deux définis, une conversation doit correspondre aux deux pour être classée ici — c’est ainsi que vous pouvez attribuer à une équipe “l’agent de support, mais uniquement sur WhatsApp”.

Un compte peut avoir jusqu’à 50 départements.

Lister les départements #

GET /team/departments

curl "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "departments": [
    {
      "id": "dep_abc123",
      "name": "Sales",
      "color": "#2f6fed",
      "member_uids": ["uid_alice", "uid_bob"],
      "auto_assign_enabled": true,
      "routing_agents": [],
      "routing_channels": ["whatsapp"],
      "created_by": "owner_uid_123"
    }
  ]
}

Créer un département #

POST /team/departments

Champs de la requête

cURL

curl -X POST "https://api.youraiconnector.com/v1/team/departments?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "routing_channels": ["whatsapp"]
  }'

JavaScript

const res = await fetch("https://api.youraiconnector.com/v1/team/departments", {
  method: "POST",
  headers: {
    "X-API-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "Sales",
    color: "#2f6fed",
    member_uids: ["uid_alice", "uid_bob"],
    routing_channels: ["whatsapp"],
  }),
});
const { department } = await res.json();

Python

import requests

res = requests.post(
    "https://api.youraiconnector.com/v1/team/departments",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={
        "name": "Sales",
        "color": "#2f6fed",
        "member_uids": ["uid_alice", "uid_bob"],
        "routing_channels": ["whatsapp"],
    },
)
department = res.json()["department"]

Réponse — 201 Created

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice", "uid_bob"],
    "auto_assign_enabled": true,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

Mettre à jour un département #

PATCH /team/departments/{departmentId}

Modifie un département. Seuls les champs que vous envoyez sont modifiés.

curl -X PATCH "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "member_uids": ["uid_alice"], "auto_assign_enabled": false }'

Réponse

{
  "success": true,
  "department": {
    "id": "dep_abc123",
    "name": "Sales",
    "color": "#2f6fed",
    "member_uids": ["uid_alice"],
    "auto_assign_enabled": false,
    "routing_agents": [],
    "routing_channels": ["whatsapp"],
    "created_by": "owner_uid_123"
  }
}

L’envoi d’aucun champ reconnu renvoie 400 ; un département inconnu renvoie 404 ; un nom qui entre en conflit avec un autre département renvoie 409.

Supprimer un département #

DELETE /team/departments/{departmentId}

curl -X DELETE "https://api.youraiconnector.com/v1/team/departments/dep_abc123?apiKey=YOUR_API_KEY"

Réponse

{
  "success": true,
  "deleted": "dep_abc123"
}

La suppression d’un département auquel quelqu’un est limité est refusée. La réponse 400 nomme les membres dont la visibilité est restreinte à celui-ci, afin que vous puissiez d’abord modifier leur périmètre. C’est intentionnel : supprimer silencieusement leur limite leur donnerait accès à toute votre base de clients sans aucune trace de ce qui s’est passé.

Les contacts classés sous un département supprimé ne sont pas réécrits — ils cessent simplement d’afficher un département, et la prochaine fois que vous les classerez, cela sera pris en compte.

Vérifiez vos propres autorisations #

GET /team/permissions

Renvoie ce que la personne connectée est autorisée à faire dans le compte sur lequel elle travaille actuellement. Utilisez-le pour masquer les boutons qu’un membre ne peut pas utiliser, plutôt que de le laisser découvrir la limite par une erreur.

cURL

curl "https://api.youraiconnector.com/v1/team/permissions" \
  -H "Authorization: Bearer FIREBASE_ID_TOKEN"

Réponse — le propriétaire du compte

{
  "success": true,
  "role": "owner",
  "is_team_mode": false,
  "permissions": {
    "campaigns": "full",
    "contacts": "full",
    "messages": "full",
    "appointments": "full",
    "settings": "full",
    "billing": "full",
    "team_management": "full",
    "analytics": "full",
    "phone_numbers": "full",
    "integrations": "full",
    "faqs": "full",
    "daily_summaries": "full"
  }
}

Réponse — un membre de l’équipe travaillant dans un compte

{
  "success": true,
  "role": "editor",
  "is_team_mode": true,
  "permissions": { "campaigns": "edit", "billing": "none", "…": "…" },
  "member": {
    "uid": "uid_sam",
    "email": "sam@example.com",
    "display_name": "Sam Rivera",
    "account_owner_uid": "owner_uid_123"
  }
}

role est owner lorsque la personne connectée est le propriétaire du compte ; sinon, il s’agit de son rôle dans l’équipe. member n’est présent qu’en mode équipe, et contient contact_scope, contact_scope_unassigned et contact_scope_axes lorsque son adhésion les inclut.

Jetons de session #

Cinq points de terminaison génèrent un jeton de connexion à usage unique pour basculer entre les comptes. Ils répondent tous de la même manière :

{
  "success": true,
  "customToken": "eyJhbGciOi…"
}

Le jeton est échangé contre une session avec le SDK client Firebase. Ce n’est pas une clé API et ne peut pas être envoyé comme telle, c’est pourquoi ces points de terminaison ne sont utiles qu’au sein d’une application propriétaire.

Chaque requête échoue avec 403 lorsque la session n’y est pas autorisée : non-membre de ce compte, non-membre du personnel, ce sous-compte n’appartient pas à votre agence ou ne vous a pas été accordé, ou la session n’est pas actuellement dans le mode requis par le point de terminaison.

Attribuer un rôle de plateforme #

POST /team/users/{targetUid}/role

Définit le rôle plateforme d’un utilisateur — User, Dev, Support ou Agency. Il ne s’agit pas de l’appartenance à une équipe : c’est le type de compte Your AI Connector dont dispose une personne.

Ce point de terminaison est réservé au personnel Your AI Connector, et le dernier Dev restant ne peut pas être rétrogradé. Listé par souci d’exhaustivité ; il ne fait pas partie de la gestion de votre propre équipe.

{
  "success": true,
  "targetUid": "uid_sam",
  "role": "Agency",
  "claimUpdated": true
}

Erreurs de l’API d’équipe #

Les points de terminaison d’équipe renvoient l’enveloppe d’erreur standard, toujours avec error_code en plus du statut HTTP :

{
  "success": false,
  "error_code": 403,
  "error": "Cannot grant \"full\" access to \"billing\" — exceeds your own permissions."
}

Les codes partagés que chaque point de terminaison peut renvoyer — 429 (limite de débit) et 500 — sont listés avec des conseils de nouvelle tentative dans Erreurs et pagination.

Connexe #

• Gestion d’équipe — les mêmes fonctionnalités dans le tableau de bord, avec des captures d’écran.
• Authentification — comment envoyer un jeton d’identification Firebase au lieu d’une clé API.
• API Contacts — les contacts auxquels les limites de visibilité d’un membre s’appliquent.