Smart Routings — Contacts de routage

Les contacts de routage forment l'annuaire que Smart Routings utilise pour reconnaître un appelant et l'orienter vers une destination dédiée. Consultez 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.

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

Paramètre de requête obligatoire : customer_account — le compte client concerné. Voir Choix du compte client.

#Contacts de routage

#L'objet contact

Chaque entrée de fields contient sa valeur et sa définition, ce qui évite une seconde requête pour obtenir les libellés :

#GET /api/smart-routings/contacts

Renvoie la liste paginée des contacts de routage du client, du plus récent au plus ancien.

Paramètres de requête

Réponse 200 — réponse paginée

{
  "data": [
    {
      "id": 57,
      "customer_id": 12,
      "id_code": "CUST-0042",
      "language_code": "fr",
      "company": "Acme Corp",
      "first_name": "Alice",
      "last_name": "Martin",
      "emails": "alice.martin@acme.com",
      "telecoms": "+33612345678",
      "email_destination": null,
      "telecom_destination": "201",
      "created_at": "2024-05-02T14:20:00.000000Z",
      "updated_at": "2024-05-02T14:20:00.000000Z",
      "fields": [
        {
          "code": "vip",
          "label": "VIP",
          "type": "boolean",
          "value": "1",
          "options": null
        },
        {
          "code": "segment",
          "label": "Segment",
          "type": "select",
          "value": "gold",
          "options": [
            { "name": "Gold", "value": "gold" },
            { "name": "Silver", "value": "silver" }
          ]
        }
      ]
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}

#GET /api/smart-routings/contacts/{contact}

Renvoie un contact de routage avec ses fields.

Réponse 200 — objet contact

Réponse 403 — le contact appartient à un autre client ou la permission est manquante

#POST /api/smart-routings/contacts

Crée un contact de routage.

Corps de la requête

Lorsqu'une entrée de fields fait référence à un code sans définition de champ :

• si type vaut telecom ou email, la définition est créée automatiquement ;
• sinon la requête échoue avec une erreur 422. Les champs boolean et select doivent d'abord être créés via les endpoints des définitions de champs.

Exemple

{
  "company": "Acme Corp",
  "first_name": "Alice",
  "last_name": "Martin",
  "telecoms": "+33612345678",
  "telecom_destination": "201",
  "fields": [
    { "code": "segment", "value": "gold" },
    { "code": "backup_line", "value": "+33142000000", "type": "telecom" }
  ]
}

Réponse 201 — l'objet contact créé, avec ses fields

Réponse 422 — code de champ boolean ou select inconnu

{
  "response": "Unknown field code \"vip\". Boolean/select fields must be created via the field-definition endpoint first.",
  "hint": null
}

#PUT /api/smart-routings/contacts/{contact}

Modifie un contact de routage. PATCH est également accepté. Accepte les mêmes champs qu'à la création, tous facultatifs.

Les valeurs envoyées dans fields sont créées ou remplacées une par une ; les champs personnalisés non envoyés conservent leur valeur actuelle.

Réponse 201 — l'objet contact modifié, avec ses fields

#DELETE /api/smart-routings/contacts/{contact}

Supprime un contact de routage.

Réponse 200

{ "response": "element deleted" }

#Opérations en masse

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

Télécharge les contacts de routage du client sous forme de fichier Excel (routing_contacts.xlsx), triés par entreprise.

Le fichier contient les colonnes id, id_code, language_code, company, first_name, last_name, emails, telecoms, email_destination et telecom_destination, suivies d'une colonne par définition de champ du client (active ou non), triées par position et intitulées avec le code de la définition. Chaque cellule contient la valeur du contact pour ce champ, ou reste vide. Toutes les cellules sont écrites en texte : les numéros de téléphone gardent leur + ou leur 0 initial.

Une définition dont le code reprend le nom d'une colonne de base n'est pas exportée.

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

Importe des contacts de routage depuis un tableur. Envoyez la requête en multipart/form-data.

Corps de la requête

La ligne d'en-tête reprend les colonnes de l'export : partez d'un export pour construire le fichier.

• Une ligne avec un id existant met à jour ce contact ; une ligne sans id en crée un nouveau.
• Les lignes dont l'id appartient à un autre client sont ignorées.
• Les lignes sans aucune des valeurs id_code, company, telecoms ou emails sont ignorées.
• Une colonne intitulée avec le code d'une définition de champ renseigne ce champ personnalisé. Une cellule vide supprime la valeur du contact pour ce champ. Un champ sans colonne dans le fichier n'est pas modifié.
• Les colonnes qui ne correspondent à aucune définition de champ sont ignorées : créez d'abord les définitions.
• Les champs boolean acceptent 1, true, yes, oui (enregistrés 1) et 0, false, no, non (enregistrés 0).
• Les champs select acceptent la value d'une option, ou son name, enregistré sous sa valeur.

Tout le fichier est validé avant la moindre écriture. Si une ligne contient une valeur de champ personnalisé invalide, rien n'est importé et l'API répond 422.

Réponse 200

{ "response": "Import successful." }

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

Supprime des contacts de routage en masse, ainsi que les valeurs de leurs champs personnalisés.

Corps de la requête

Sans ids, tous les contacts de routage du client sont supprimés.

Réponse 200

{ "response": "elements deleted" }

#Définitions de champs

Les définitions de champs décrivent les champs personnalisés disponibles sur les contacts de routage du client. Une définition ne peut pas être supprimée, car un flux d'appel peut encore faire référence à son code : passez active à false pour la masquer.

#L'objet définition de champ

#GET /api/smart-routings/contact-field-definitions

Renvoie la liste paginée des définitions de champs du client, avec leurs options, triées par position.

Paramètres de requête

Réponse 200 — réponse paginée

{
  "data": [
    {
      "id": 3,
      "customer_id": 12,
      "code": "segment",
      "label": "Segment",
      "type": "select",
      "position": 1,
      "active": true,
      "created_at": "2024-05-01T09:00:00.000000Z",
      "updated_at": "2024-05-01T09:00:00.000000Z",
      "options": [
        {
          "id": 8,
          "routing_contact_field_definition_id": 3,
          "name": "Gold",
          "value": "gold",
          "created_at": "2024-05-01T09:01:00.000000Z",
          "updated_at": "2024-05-01T09:01:00.000000Z"
        }
      ]
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}

#GET /api/smart-routings/contact-field-definitions/{definition}

Renvoie une définition de champ avec ses options.

Réponse 200 — objet définition de champ

#POST /api/smart-routings/contact-field-definitions

Crée une définition de champ.

Corps de la requête

Réponse 201 — l'objet définition de champ créé

#PUT /api/smart-routings/contact-field-definitions/{definition}

Modifie une définition de champ. PATCH est également accepté. code et type ne sont pas modifiables.

Corps de la requête

Réponse 201 — l'objet définition de champ modifié

#Options de champ

Les options sont les valeurs autorisées d'une définition de champ select. Appeler ces endpoints sur une définition d'un autre type renvoie une erreur 422.

{ "response": "This field cannot have options.", "hint": null }

#GET /api/smart-routings/contact-field-definitions/{definition}/options

Renvoie toutes les options de la définition. Cette liste n'est pas paginée.

Réponse 200

[
  {
    "id": 8,
    "routing_contact_field_definition_id": 3,
    "name": "Gold",
    "value": "gold",
    "created_at": "2024-05-01T09:01:00.000000Z",
    "updated_at": "2024-05-01T09:01:00.000000Z"
  }
]

#GET /api/smart-routings/contact-field-definitions/{definition}/options/{option}

Renvoie une option.

Réponse 200 — objet option

Réponse 403 — l'option n'appartient pas à cette définition

#POST /api/smart-routings/contact-field-definitions/{definition}/options

Ajoute une option à une définition select.

Corps de la requête

Réponse 201 — la liste complète et à jour des options de la définition

#PUT /api/smart-routings/contact-field-definitions/{definition}/options/{option}

Modifie une option. PATCH est également accepté.

Corps de la requête

Réponse 201 — la liste complète et à jour des options de la définition

#DELETE /api/smart-routings/contact-field-definitions/{definition}/options/{option}

Supprime une option.

Réponse 200

{ "response": "element deleted" }