---
title: Smart Routings — CTI
excerpt: Gérez les tables CTI qui associent un numéro entrant à une destination, importez et exportez leurs entrées, et recherchez la destination d'un appelant.
order: 10
---

Une CTI est une table de correspondance qui associe une origine (généralement le numéro de l'appelant) à une destination. Consultez [Smart Routings](/fr/docs/cx-api/smart-routings) pour les notions communes à tous les endpoints Smart Routings.

Tous les endpoints de cette section sont **propres à l'espace de travail** et nécessitent le scope OAuth `client`, sauf mention contraire. L'endpoint de recherche accepte aussi le scope `cfd`.

**En-têtes :** `Authorization: Bearer {workspace-token}`

**Paramètre de requête obligatoire :** `customer_account` — le compte client concerné. Voir [Choix du compte client](/fr/docs/cx-api/smart-routings#choix-du-compte-client).

| Permission | Nécessaire pour |
|---|---|
| `cti.view` | Lire les CTI et leurs destinations |
| `cti.create` | Créer des CTI, importer des destinations, supprimer des destinations en masse |
| `cti.edit` | Modifier une CTI, régénérer son jeton, créer, modifier ou supprimer ses destinations |
| `cti.delete` | Supprimer une CTI |
| `cti.lookup` | Rechercher une destination |

---

## CTI

### L'objet CTI

| Champ | Type | Description |
|---|---|---|
| `id` | integer | ID de la CTI |
| `customer_id` | integer | Client auquel appartient la CTI |
| `name` | string | Nom de la CTI |
| `token` | string | Jeton de 80 caractères utilisé par l'endpoint de recherche par jeton (voir [Recherche](#recherche)). Généré par CX-Engine, non modifiable |
| `token_lookup_url` | string | URL de recherche par jeton prête à l'emploi, terminée par le marqueur `%CallerNumber%` |
| `created_at` | string | Date de création (ISO 8601) |
| `updated_at` | string | Date de dernière modification (ISO 8601) |

> [!WARNING]
> Toute personne qui connaît le `token` d'une CTI peut lire ses destinations sans authentification. Traitez-le comme un secret et régénérez-le en cas de fuite.

---

### GET /api/smart-routings/ctis

Renvoie la liste paginée des CTI du client, de la plus récemment modifiée à la plus ancienne. Chaque CTI inclut un champ `destinations_count`.

**Paramètres de requête**

| Paramètre | Description |
|---|---|
| `filter[name]` | Filtrer par nom (correspondance partielle) |
| `filter[token]` | Filtrer par jeton (correspondance partielle) |
| `include` | Relations à inclure, séparées par des virgules : `customer`, `destinations` |
| `sort` | Champ de tri : `id`, `name`, `created_at`, `updated_at`. Préfixez par `-` pour un tri décroissant. Par défaut : `-updated_at` |
| `per_page` | Nombre de résultats par page (20 par défaut) |
| `page` | Numéro de page |

**Réponse `200`** — réponse paginée

```json
{
  "data": [
    {
      "id": 4,
      "customer_id": 12,
      "name": "VIP callers",
      "token": "q8Zb3kV0yR1mN7tXwP2sL5cH9dF4gJ6aE0uI3oK8vB1nM5zQ7xC2yT4rW6eS9pD0hG3jL8fA1kU5iO7mN2b",
      "created_at": "2024-03-04T10:12:00.000000Z",
      "updated_at": "2024-06-18T08:45:00.000000Z",
      "destinations_count": 42,
      "token_lookup_url": "https://acme.cx-engine.app/api/smart-routings/ctis/t/q8Zb3kV0yR1m.../%CallerNumber%"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}
```

---

### GET /api/smart-routings/ctis/{cti}

Renvoie une CTI avec son `customer` et ses `destinations`.

**Réponse `200`**

```json
{
  "id": 4,
  "customer_id": 12,
  "name": "VIP callers",
  "token": "q8Zb3kV0yR1m...",
  "created_at": "2024-03-04T10:12:00.000000Z",
  "updated_at": "2024-06-18T08:45:00.000000Z",
  "token_lookup_url": "https://acme.cx-engine.app/api/smart-routings/ctis/t/q8Zb3kV0yR1m.../%CallerNumber%",
  "customer": { ... },
  "destinations": [
    {
      "id": 101,
      "cti_id": 4,
      "origin": "+33612345678",
      "destination": "201",
      "created_at": "2024-03-04T10:15:00.000000Z",
      "updated_at": "2024-03-04T10:15:00.000000Z"
    }
  ]
}
```

**Réponse `403`** — la CTI appartient à un autre client ou la permission est manquante

---

### POST /api/smart-routings/ctis

Crée une CTI. Son `token` est généré automatiquement.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | oui | Nom de la CTI (50 caractères max.) |

**Réponse `201`** — l'objet CTI créé

---

### PUT /api/smart-routings/ctis/{cti}

Modifie une CTI. `PATCH` est également accepté. Le `token` ne peut pas être modifié ici : utilisez l'endpoint de régénération ci-dessous.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `name` | string | non | Nom de la CTI (50 caractères max.) |

**Réponse `201`** — l'objet CTI modifié

---

### POST /api/smart-routings/ctis/{cti}/regenerate-token

Remplace le jeton de la CTI par un nouveau jeton aléatoire de 80 caractères. L'ancien jeton et son URL de recherche cessent de fonctionner immédiatement.

**Réponse `200`** — l'objet CTI modifié, avec le nouveau `token` et la nouvelle `token_lookup_url`

---

### DELETE /api/smart-routings/ctis/{cti}

Supprime une CTI et toutes ses destinations.

**Réponse `200`**

```json
{ "response": "element deleted" }
```

---

## Destinations

Une destination associe une `origin` à une `destination` au sein d'une CTI.

| Champ | Type | Description |
|---|---|---|
| `id` | integer | ID de la destination |
| `cti_id` | integer | CTI parente |
| `origin` | string | Valeur comparée lors de la recherche, par exemple le numéro de l'appelant |
| `destination` | string | Valeur renvoyée quand l'origine correspond, par exemple un poste ou un numéro |
| `created_at` | string | Date de création (ISO 8601) |
| `updated_at` | string | Date de dernière modification (ISO 8601) |

---

### GET /api/smart-routings/ctis/{cti}/destinations

Renvoie toutes les destinations de la CTI. Cette liste n'est pas paginée.

**Réponse `200`**

```json
[
  {
    "id": 101,
    "cti_id": 4,
    "origin": "+33612345678",
    "destination": "201",
    "created_at": "2024-03-04T10:15:00.000000Z",
    "updated_at": "2024-03-04T10:15:00.000000Z"
  }
]
```

---

### GET /api/smart-routings/ctis/{cti}/destinations/{destination}

Renvoie une destination.

**Réponse `200`** — objet destination

**Réponse `404`** — la destination n'appartient pas à cette CTI

---

### POST /api/smart-routings/ctis/{cti}/destinations

Ajoute une destination à la CTI.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `origin` | string | oui | Origine à comparer (50 caractères max.) |
| `destination` | string | oui | Destination à renvoyer (50 caractères max.) |

**Réponse `201`** — l'objet destination créé

---

### PUT /api/smart-routings/ctis/{cti}/destinations/{destination}

Modifie une destination. `PATCH` est également accepté.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `origin` | string | non | Origine à comparer (50 caractères max.) |
| `destination` | string | non | Destination à renvoyer (50 caractères max.) |

**Réponse `201`** — l'objet destination modifié

---

### DELETE /api/smart-routings/ctis/{cti}/destinations/{destination}

Supprime une destination.

**Réponse `200`**

```json
{ "response": "element deleted" }
```

---

## Opérations en masse

### GET /api/smart-routings/ctis/export

Télécharge les destinations CTI du client sous forme de fichier Excel (`cti_destinations.xlsx`).

**Paramètres de requête**

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `cti_id` | integer | non | N'exporter que les destinations de cette CTI |

Le fichier contient les colonnes `id`, `cti_id`, `origin` et `destination`.

---

### POST /api/smart-routings/ctis/import

Importe des destinations CTI depuis un tableur. Envoyez la requête en `multipart/form-data`.

**Corps de la requête**

| Champ | Type | Obligatoire | Description |
|---|---|---|---|
| `customer_id` | integer | oui | ID du client. Doit correspondre au compte client sélectionné |
| `document` | file | oui | Tableur (Excel, ou CSV avec `;` comme séparateur) avec une ligne d'en-tête |

La ligne d'en-tête reprend les colonnes de l'export : `id`, `cti_id`, `origin`, `destination`.

- Une ligne avec un `id` existant met à jour cette destination ; une ligne sans `id` en crée une nouvelle.
- Les lignes dont la CTI appartient à un autre client, ou dont l'`origin` ou la `destination` est vide, sont ignorées.

**Réponse `200`**

```json
{ "response": "Import successful." }
```

---

### DELETE /api/smart-routings/ctis/bulk

Supprime des destinations CTI en masse. Les CTI elles-mêmes sont conservées.

**Paramètres de requête**

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `cti_id` | integer | non | Ne supprimer que les destinations de cette CTI |

> [!WARNING]
> Sans `cti_id`, les destinations de **toutes** les CTI du client sont supprimées.

**Réponse `200`**

```json
{ "response": "elements deleted" }
```

---

## Recherche

### GET /api/smart-routings/ctis/lookup

Renvoie la destination correspondant à une origine dans une CTI. Accepte le scope OAuth `client` ou `cfd`. Nécessite la permission `cti.lookup`.

**Paramètres de requête**

| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
| `customer_account` | string | oui* | Compte client |
| `customer_id` | integer | oui* | ID du client |
| `cti_id` | integer | oui** | ID de la CTI |
| `cti_name` | string | oui** | Nom de la CTI |
| `cti_token` | string | oui** | Jeton de la CTI |
| `origin` | string | oui | Origine à rechercher, par exemple le numéro de l'appelant |

*L'un des paramètres `customer_account` ou `customer_id` est obligatoire.  
**L'un des paramètres `cti_id`, `cti_name` ou `cti_token` est obligatoire. Si plusieurs sont envoyés, `cti_id` est prioritaire, puis `cti_token`, puis `cti_name`.

**Réponse `200`** — objet destination

```json
{
  "id": 101,
  "cti_id": 4,
  "origin": "+33612345678",
  "destination": "201",
  "created_at": "2024-03-04T10:15:00.000000Z",
  "updated_at": "2024-03-04T10:15:00.000000Z"
}
```

**Réponse `404`** — aucun client, aucune CTI ou aucune destination ne correspond aux paramètres

```json
{ "message": "No destination found matching given parameters." }
```

---

### GET /api/smart-routings/ctis/t/{token}/{origin}

Recherche par jeton, conçue pour les PBX ou outils CTI qui ne savent appeler qu'une URL simple. **Aucun en-tête `Authorization` n'est requis** : le `token` de la CTI authentifie la requête et identifie le client, `customer_account` est donc inutile. Utilisez la `token_lookup_url` de la CTI en remplaçant `%CallerNumber%` par le numéro de l'appelant.

```
GET /api/smart-routings/ctis/t/q8Zb3kV0yR1m.../+33612345678
```

**Réponse `200`**

```json
{
  "id": 101,
  "origin": "+33612345678",
  "destination": "201"
}
```

**Réponse `404`** — jeton inconnu, ou aucune destination pour cette origine