Suivre et intégrer

Entités

Une entité est une unité de votre compte : un club d'un réseau de franchises, un client d'un centre d'appels, un cabinet d'un groupe. Elle regroupe des agents, des numéros de téléphone et des webhooks. Les éléments qui ne sont rattachés à aucune entité sont partagés, et toutes les entités peuvent les utiliser.

Organisation, pas contrôle d'accès

Les entités séparent les éléments de chaque unité et vous permettent de filtrer par unité. Chaque clé API et chaque membre voit toujours l'ensemble du compte, et la facturation reste unique pour le compte.

Provisionner une entité depuis votre système

Donnez à chaque entité votre propre identifiant comme externalId. Si l'identifiant est déjà pris, l'erreur 409 renvoie l'entité qui le détient : un script de provisionnement peut donc être relancé sans risque.

Terminal

curl -X POST "https://api.callshift.ai/v1/entities" \
  -H "Authorization: Bearer $CALLSHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Lyon Part-Dieu", "externalId": "club-42" }'

# Run again: 409 { "error": "...", "existingEntityId": "550e8400-e29b-41d4-a716-446655440000" }

Placer des éléments dans une entité

Chaque requête qui crée ou modifie un agent, un numéro ou un webhook accepte entityId ou entityExternalId (l'un des deux, pas les deux). null rend l'élément partagé, et si vous omettez le champ, l'élément conserve son entité actuelle.

JSON

{ "entityExternalId": "club-42" }

Ces deux mêmes paramètres filtrent les listes d'agents, de numéros de téléphone, de numéros SIP, de webhooks et de trunks : GET /v1/agents?entityExternalId=club-42.

Les éléments de deux entités ne se mélangent jamais

CallShift refuse tout lien entre deux entités différentes, avec une erreur 409 qui nomme les éléments en cause : un numéro et l'agent qui y répond, l'agent d'une campagne et son numéro, un agent et son webhook. Un élément partagé peut être lié à n'importe quel autre. Un appel de campagne dont l'agent et le numéro se retrouvent dans des entités différentes n'est pas composé (agent-line-entity-mismatch) et la campagne s'arrête.

Fusionner ou fermer une entité

POST/v1/entities/{entityId}/move-items déplace tous les agents, numéros et webhooks d'une entité vers une autre entité, ou les rend partagés. L'entité, désormais vide, peut être supprimée avec DELETE/v1/entities/{entityId} ; tant qu'elle contient des éléments, la suppression est refusée avec la liste de ce qui reste.

Appels par entité

Le webhook de fin d'appel contient l'entity de l'appel. L'API des appels n'a pas encore de filtre par entité : pour une vue par entité, listez les agents de l'entité et filtrez les appels par agentId.