Monitorizar e integrar

Entidades

Una entidad es una unidad de tu cuenta: un club de una franquicia, un cliente de un centro de llamadas, una consulta médica de un grupo. Agrupa agentes, números de teléfono y webhooks. Los elementos que no están en ninguna entidad son compartidos, y todas las entidades pueden usarlos.

Organización, no control de acceso

Las entidades mantienen separados los elementos de cada unidad y te permiten filtrar por unidad. Cada clave de API y cada miembro siguen viendo toda la cuenta, y la cuenta tiene una sola factura.

Aprovisionar una entidad desde tu sistema

Da a cada entidad tu propio identificador como externalId. Si el identificador ya está en uso, el 409 devuelve la entidad que lo tiene, así que un script de aprovisionamiento se puede volver a ejecutar sin riesgo.

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" }

Asignar elementos a una entidad

Toda petición que crea o modifica un agente, un número o un webhook acepta entityId o entityExternalId (uno de los dos, no ambos). null hace que el elemento sea compartido, y omitir el campo conserva su entidad actual.

JSON

{ "entityExternalId": "club-42" }

Estos dos mismos parámetros filtran las listas de agentes, números de teléfono, números SIP, webhooks y trunks: GET /v1/agents?entityExternalId=club-42.

Los elementos de dos entidades nunca se mezclan

CallShift rechaza con un 409 cualquier vínculo entre dos entidades distintas e indica los elementos implicados: un número y el agente que lo atiende, el agente de una campaña y su número, un agente y su webhook. Un elemento compartido se puede vincular con cualquiera. Una llamada de campaña cuyo agente y número han acabado en entidades distintas no se marca (agent-line-entity-mismatch) y la campaña se detiene.

Fusionar o cerrar una entidad

POST/v1/entities/{entityId}/move-items mueve todos los agentes, números y webhooks de una entidad a otra, o los convierte en compartidos. La entidad, ya vacía, se puede eliminar con DELETE/v1/entities/{entityId}; mientras aún contenga elementos, la eliminación se rechaza indicando lo que queda.

Llamadas por entidad

El webhook de fin de llamada incluye la entity de la llamada. La API de llamadas aún no tiene filtro por entidad: para una vista por entidad, lista los agentes de la entidad y filtra las llamadas por agentId.