API Centre d'appels

Connectez votre agent aux appels entrants et montrez-lui ce que l'appelant vient de faire : pages consultées, panier en cours, commandes existantes. Les paniers et commandes créés par l'agent sont rattachés à l'appel pour en mesurer la performance.

#1 Introduction

L'API Call Center d'Optico fournit à vos agents les informations en direct sur chaque appel entrant : la page consultée par le visiteur, ses précédentes vues, le panier en cours et les commandes existantes. Elle s'utilise avec l'API Cart pour que vos agents puissent aussi créer ou modifier des commandes et des paniers depuis leur interface.

#Fonctionnement

Lorsqu'un appel arrive dans votre centre d'appels, votre système interroge /agent-api/callStart avec le téléphone de l'appelant, le téléphone de destination et l'heure de début. Optico répond avec l'enregistrement de l'appel correspondant et tout ce qu'il sait du visiteur : son parcours, ses pages vues, le contenu du panier et toute commande ouverte. Votre interface agent peut afficher ces informations dès la sonnerie.

En liant les paniers et les commandes aux agents, Optico produit des statistiques sur la performance des agents : évolution de la valeur du panier après un appel agent, commandes passées via le canal téléphonique, taux de conversion, et plus encore.

#Transport & conventions

#2 Démarrage

1. Créez un compte sur www.optico.fr : vous recevrez un nom d'utilisateur, un mot de passe, la clé API Call Center (rubrique Gérer les API dans l'interface d'administration), et l'accès à la plateforme back-end pour la gestion.
2. Connectez votre agent à l'appel via /agent-api/callStart, en utilisant l'une des deux stratégies de routage décrites ci-dessous.
3. Utilisez l'API Cart pour ajouter ou modifier des paniers et des commandes depuis l'agent, en fournissant les paramètres agent et callId pour rattacher les objets au bon appel.
4. Recevez les mises à jour par webhook : configurez une URL sur laquelle Optico enverra (POST) les nouvelles vues, paniers et commandes pendant l'appel.

#Routage de l'agent : deux stratégies

#3 Authentification

Chaque requête doit inclure votre apiKey en tant que champ POST. La clé API Call Center est unique pour l'ensemble de vos domaines enregistrés et se trouve dans l'admin Optico sous Gérer les API.

apiKey=b7e2c8a14f9d3650a1e7c4d8b2f6a395e

#4 Erreurs

Toutes les réponses incluent un champ status. En cas de succès, il vaut "OK" ; en cas d'échec, il vaut "NOK" et un champ error contient le message.

{ "status": "NOK", "error": "Invalid API key `b7e2c8a14f9d`" }

#5 Endpoints

#6 Concepts

#7 POST /agent-api/callStart

Faites correspondre un appel entrant à son enregistrement Optico et renvoyez le contexte complet du visiteur. Utilisez cet appel comme première requête lorsqu'un appel sonne dans votre centre d'appels.

Flux

Paramètres de la requête

Exemple de requête

curl -X POST https://www.optico.fr/agent-api/callStart \
  -d "apiKey=b7e2c8a14f9d3650a1e7c4d8b2f6a395e" \
  -d "callerPhone=0033612345678" \
  -d "destinationPhone=0033123456789" \
  -d "startDate=2018-02-28 12:57:13" \
  -d "agent=agent1@optico.fr"

<?php
$data = [
  'apiKey'           => 'b7e2c8a14f9d3650a1e7c4d8b2f6a395e',
  'callerPhone'      => '0033612345678',
  'destinationPhone' => '0033123456789',
  'startDate'        => '2018-02-28 12:57:13',
  'agent'            => 'agent1@optico.fr',
];
$ch = curl_init('https://www.optico.fr/agent-api/callStart');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => http_build_query($data),
  CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);

const params = new URLSearchParams({
  apiKey:           'b7e2c8a14f9d3650a1e7c4d8b2f6a395e',
  callerPhone:      '0033612345678',
  destinationPhone: '0033123456789',
  startDate:        '2018-02-28 12:57:13',
  agent:            'agent1@optico.fr',
});

const res = await fetch('https://www.optico.fr/agent-api/callStart', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: params,
});
const data = await res.json();

Réponse en cas de succès

{
  "status": "OK",
  "resultsNb": 1,
  "results": [
    {
      "call": {
        "id": 22122563,
        "startDate": "2018-01-02 09:29:27",
        "status": "OK_OUTCALL",
        "source": "Adwords",
        "referrer": null,
        "Keyword": "optico tracking",
        "agent": null
      },
      "views": [
        { "id": 568536624, "pageTitle": "Page title",  "url": "http://www.test.com/test.html",  "createdAt": "2018-01-02 09:25:41" },
        { "id": 568536667, "pageTitle": "Page title 2", "url": "http://www.test.com/test2.html", "createdAt": "2018-01-02 09:25:48" }
      ],
      "currentCart": {
        "id": 80359,
        "externalId": "5a4b477e3a05e",
        "isLoggedIn": true,
        "currency": "EUR",
        "status": 0,
        "totalCost": 1000,
        "productsNb": 2,
        "createdAt": "2018-01-02 09:49:46",
        "products": [
          { "id": 662315, "name": "Product 1", "quantity": 1, "costPerUnit": 896 },
          { "id": 662316, "name": "Product 2", "quantity": 1, "costPerUnit": 104 }
        ]
      },
      "orders": [
        { "id": 18676, "agent": "agent@optico.fr", "status": "Info", "isSale": false, "totalCost": 0, "createdAt": "2018-01-02 09:32:20", "products": [] }
      ]
    }
  ]
}

Réponse en cas d'erreur

#8 POST /agent-api/setAgentToCall

Rattachez un agent à un appel déjà connu d'Optico, identifié par callId. Utilisez cet endpoint lorsque l'agent est assigné après votre appel à callStart.

Flux

Paramètres de la requête

Exemple de requête

curl -X POST https://www.optico.fr/agent-api/setAgentToCall \
  -d "apiKey=b7e2c8a14f9d3650a1e7c4d8b2f6a395e" \
  -d "callId=22122563" \
  -d "agent=agent1@optico.fr"

<?php
$ch = curl_init('https://www.optico.fr/agent-api/setAgentToCall');
curl_setopt_array($ch, [
  CURLOPT_POST           => true,
  CURLOPT_POSTFIELDS     => http_build_query([
    'apiKey' => 'b7e2c8a14f9d3650a1e7c4d8b2f6a395e',
    'callId' => 22122563,
    'agent'  => 'agent1@optico.fr',
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$response = json_decode(curl_exec($ch), true);

const res = await fetch('https://www.optico.fr/agent-api/setAgentToCall', {
  method: 'POST',
  headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  body: new URLSearchParams({
    apiKey: 'b7e2c8a14f9d3650a1e7c4d8b2f6a395e',
    callId: '22122563',
    agent:  'agent1@optico.fr',
  }),
});
const data = await res.json();

Réponse en cas de succès

{
  "status": "OK",
  "resultsNb": 1,
  "results": [
    { "callId": 22122563, "agent": "agent1@optico.fr" }
  ]
}

#9 Webhooks

Configurez une URL de webhook et Optico effectuera un POST dès qu'une nouvelle information est disponible sur un appel en cours : nouvelle vue de page, panier nouveau ou mis à jour, commande nouvelle ou mise à jour.

Livraison

Payload

Exemples de payload

Un exemple par type. Seul le sous-objet correspondant est renseigné ; les deux autres valent null.

type = "view"

{
  "callId": 22122563,
  "type": "view",
  "view": {
    "id": 568536624,
    "pageTitle": "Page title",
    "url": "http://www.test.com/test.html",
    "createdAt": "2018-01-02 09:25:41"
  },
  "cart": null,
  "order": null
}

type = "cart"

{
  "callId": 22122563,
  "type": "cart",
  "view": null,
  "cart": {
    "id": 80359,
    "externalId": "5a4b477e3a05e",
    "isLoggedIn": true,
    "currency": "EUR",
    "status": 0,
    "totalCost": 1000,
    "productsNb": 2,
    "createdAt": "2018-01-02 09:49:46",
    "products": [
      { "id": 662315, "externalId": "SKU-001", "name": "Produit 1", "quantity": 1, "costPerUnit": 896, "details": [] },
      { "id": 662316, "externalId": "SKU-002", "name": "Produit 2", "quantity": 1, "costPerUnit": 104, "details": [] }
    ]
  },
  "order": null
}

type = "order"

{
  "callId": 22122563,
  "type": "order",
  "view": null,
  "cart": null,
  "order": {
    "id": 18676,
    "externalId": "ORD-2018-001",
    "cartId": 80359,
    "externalCartId": "5a4b477e3a05e",
    "agent": "agent1@optico.fr",
    "status": "Completed",
    "isSale": true,
    "currency": "EUR",
    "totalCost": 1000,
    "source": "Adwords",
    "createdAt": "2018-01-02 09:32:20",
    "products": [
      { "id": 662315, "externalId": "SKU-001", "name": "Produit 1", "quantity": 1, "costPerUnit": 896, "details": [] }
    ]
  }
}