Guide d utilisation CTI / API / TAPI

Transcription

1 Guide d utilisation CTI / API / TAPI Service Quality Assurance Version 1.1

2 Sommaire Portée du document Introduction à la configuration Définition du CTI Définition de l API Le CTI Keyyo Limitations Configuration du CTI Keyyo Buzzee API Keyyo Paramètres de référence Emission d appel Envoi de SMS Notification d appels Gestion des profils Notification d appels entrants Exemple Exemple d utilisation des variables DREF et DREFREPLACE Appels sortants Format des requêtes pour un appel sortant simple Format des requêtes pour une mise en relation Envoi de SMS Format des requêtes pour un envoi de SMS Gestion de profils Authentification Vérification d IP source Authentification HTTP DIGEST Exemples de programmation côté serveur Appel sortant avec authentification par IP source Appel sortant avec authentification HTTP Sans vérification du certificat SSL Avec vérification du certificat SSL Réception et traitement de notifications d appels Envoi de SMS Keyyo TAPI Fonctionnalités principales et compatibilité Installation de Keyyo TAPI 2-20

3 Portée du document Ce document a pour but de guider le partenaire dans la configuration des lignes Keyyo pour utiliser le service de CTI (Couplage Téléphonie-Informatique ou Computer Telephony Integration) Keyyo. Il permet de comprendre le fonctionnement du CTI et surtout des API utilisées dans ce cadre d utilisation pour que les applications clientes puissent être configurées correctement. Nous vous invitons à consulter la page d aide au développeur sur les API Keyyo ici :

4 Introduction à la configuration Définition du CTI Un CTI (Couplage Téléphonie-Informatique ou Computer Telephony Integration) est un dispositif permettant d interfacer le système de téléphonie aux applicatifs informatiques. Il permet notamment de notifier les appels entrants (remontée de fiche par exemple) ainsi que d effectuer des appels sortants de type clic-to-call depuis le système informatique. Définition de l API Une API (Application Programmable Interface) est un ensemble de fonctions régies par des règles d application permettant de s interfacer à un service. Le CTI Keyyo Le CTI Keyyo se repose sur deux possibilités de fonctionnement : Buzzee : si vous possédez un compte Buzzee, il est possible de coupler la téléphonie Keyyo à l outil Buzzee. API Keyyo : les API Keyyo sont disponibles pour toutes les sociétés souhaitant automatiser leurs relations avec Keyyo via un système d'interface. Avec les API, vous pouvez utiliser nos services directement au coeur de votre système d'information. En l occurrence, Keyyo fournit un service de notification des appels entrants et la possibilité d effectuer des appels sortants depuis une application tierce via les API Keyyo. Limitations Les API Keyyo permettent d établir un seul appel par seconde sans mise en queue. En cas de dépassement de cette limite la requête est rejetée avec un code "500 Come Back Later". Cette limitation est également valable pour l envoi de SMS. 4-20

5 Configuration du CTI Keyyo Buzzee Vous pouvez rattacher votre compte Keyyo directement sur votre compte Buzzee en renseignant l URL du serveur que vous utilisez dans le menu de configuration de la ligne : Prenez contact avec Delos qui vous communiquera les informations de connexion. 5-20

6 API Keyyo Il est possible via les API de notifier les appels entrants et d effectuer des appels sortants. Si vous souhaitez développer votre propre application, ou adapter une application existante pour la faire fonctionner avec le CTI Keyyo, il faut respecter les directives données avec les API Keyyo et décrites ci-après. Il faut pour cela remplir les champs adéquats dans l interface Web Keyyo : l URL sur laquelle doivent être notifiés les appels entrants l adresse IP source que vous utilisez lors des appels sortants (si vous ne souhaitez pas vous authentifier via login / password à chaque requête) Les paragraphes suivants détaillent ces deux cas d utilisation. 6-20

7 Paramètres de référence Emission d appel Mot clé Obligatoire Type Taille max Valeur par défaut Description ACCOUNT Oui Numeric 64 - CALLER Non Numeric 64 ACCOUNT CALLEE Oui Numeric 64 - Numéro de la ligne Keyyo (format international) Numéro de l appelant au format international Numéro de l appelé au format international CALLEE_NAME Non Text - - Nom affiché du numéro appelé RECORD Non Boolean 64 - Déclenche l enregistrement de l appel (si =1) et l envoie sur l adresse mail associée à la messagerie Attention : lors d'un appel sortant déclenché via l'api Keyyo, vous ne recevrez pas la notification de cet appel si l'option record (enregistrement d'appel) est utilisée. Envoi de SMS Mot clé Obligatoire Type Taille max Valeur par défaut Description ACCOUNT Oui Numeric 64 - Numéro de la ligne Keyyo au format international CALLEE Oui Numeric 64 - Numéro du destinataire au format international MSG Oui Text 64 - Contenu du SMS à envoyer 7-20

8 Notification d appels Mot clé Type Taille max Description _ACCOUNT_ Numeric 64 Numéro de la ligne Keyyo au format international _CALLER_ Numeric 64 Numéro de l appelant au format international _CALLEE_ Numeric 64 Numéro de l appelé au format international _CALLREF_ Text 64 Identifiant de l appel _N_TYPE_ Text 16 Type de notification : SETUP : Initiation de l appel CONNECT : Connexion de l appel RELEASE : Fin de l appel _N_VERSION_ Integer - Version de l API de notification : 1 _DREF_ Text 32 _DREF_REPLACE_ Text 32 _SESSION_ID_ Text 40 Identifiant du dialogue, présent sur tous les appels et différent du CALLREF Identifiant du dialogue remplacé (présent dans le cas d'une interception ou d'un transfert accompagné et se réfère au _DREF_ de l'appel intercepté ou transféré) Identifiant de session commun à l'ensemble des appels générés par un appel entrant sur un numéro d accueil _IS_ACD_ Boolean - Egal à 1 si l'appel provient d un numéro d accueil _REDIRECTING_NUMBER_ Numeric 64 Lors d'un appel renvoyé, numéro de la ligne qui effectue le renvoi _TSMS_ Numeric 13 Timestamp (en millisecondes) de l'évènement Gestion des profils Mot clé Type Taille max Description ACCOUNT Numeric 64 Numéro de la ligne Keyyo au format international PROFIL Text 64 Nom du profil souhaité 8-20

9 Notification d appels entrants Une fois l interface du Manager correctement configurée, lorsqu un appel entrant arrivera sur la ligne, les serveurs Keyyo enverront une requête de type HTTP GET à l URL que vous avez renseignée dans l interface Web (champ URL de notification ). L URL que vous renseignez doit contenir les mots-clefs (sans les remplacer par leur valeur finale) que nous avons définis. En effet, ces mots clefs seront remplacés lors de l appel de cette URL. Si vous possédez un firewall, vous devrez autoriser l adresse IP source de Keyyo ( à ce jour). Exemple Nous rentrons l URL suivante pour la ligne : &callee=_callee_&type=_n_type_ Le mobile appelle la ligne Keyyo Dès que l appel se présentera sur notre réseau, nous routerons l appel sur le terminal, qui sonnera comme pour tout appel entrant. Nous enverrons également une requête HTTP GET à sous ce format : 9-20

10 /notification.php?account= &caller= &callee= &type =SETUP Au décroché, nous aurons une nouvelle requête sous ce format : /notification.php?account= &caller= &callee= &type =CONNECT Et au raccrochage, nous aurons : /notification.php?account= &caller= &callee= &type =RELEASE Il faudra que l application que vous avez développée puisse interpréter ces informations pour ensuite les traiter. A noter que dans le cas d un appel de Keyyo vers Keyyo qui arrive sur messagerie, le format du numéro décrochant (i.e. la messagerie) est plus long que les habituels 11 digits (22 digits dans ce cas). Exemple d utilisation des variables DREF et DREFREPLACE Nous rentrons l URL suivante pour la ligne : &callee=_callee_&type=_n_type_&dref=_dref_&drefreplace=_dref_replace_ Nous rentrons l URL suivante pour la ligne : &callee=_callee_&dref=_dref_&drefreplace=_dref_replace_ Le mobile appelle la ligne Keyyo Dès que l appel se présentera sur notre réseau, nous routerons l appel sur le terminal, qui sonnera comme pour tout appel entrant. Nous enverrons également une requête HTTP GET à sous ce format : /notification.php?account= &caller= &callee= &type =SETUP&dref= d73ee1ac29fa2a25e42a5f&drefreplace= Nous pouvons voir que pour cet appel seul le DREF est initialisé. L utilisateur du étant absent c est le qui lui vole l appel grâce à l option supervision, voici ce que nous envoyons : /notification.php?account= &caller= &callee= &typ e=setup&dref= f779f01b188c11771a583&drefreplace= d73ee1ac 29fa2a25e42a5f 10-20

11 Nous pouvons voir que : Le DREF de l appel initial est devenu le DREFREPLACE du nouvel appel ce qui permet ensuite par une simple requête SQL (en cas de stockage dans une base de données) de retrouver l appel initial permettant de savoir à qui il a été volé. L utilisateur volant l appel passe en CALLER et le numéro appelant à l origine devient le CALLEE. En effet l utilisateur volant l appel récupère l appel de son collaborateur c est donc lui l initiateur de ce nouvel appel. L utilisateur initial aura donc uniquement 2 notifications : SETUP et RELEASE

12 Appels sortants Format des requêtes pour un appel sortant simple La requête doit être transmise dans le format suivant : CALLEE_NAME=<nom_appelé> Où <ligne_keyyo> doit être remplacé par le numéro de ligne Keyyo émettrice de l appel au format international, <destination> correspond au numéro à appeler et <nom_appelé> correspond au nom de la personne appelée. Format des requêtes pour une mise en relation La requête doit être transmise dans le format suivant : CALLEE_NAME=<nom_appelé>&CALLER=<numéro_mis_en_relation> Où <ligne_keyyo> doit être remplacé par le numéro de ligne Keyyo émettrice de la mise en relation au format international, <destinataire> correspond au numéro à appeler et <nom_appelé> correspond au nom de la personne appelée. <numéro_mis_en_relation> correspond au numéro que l on désire mettre en relation avec <destinataire>. ACCOUNT appelle CALLER en présentant le nom de CALLEE_NAME. Lorsque CALLER décroche, il est transféré vers CALLEE. L appel sonne chez CALLEE comme provenant de CALLER (numéro présenté chez CALLEE). Lorsque CALLEE décroche il est mis en relation directement avec CALLER sans qu aucun des deux correspondants n ait été mis en relation avec la ligne ACCOUNT. Il faut bien noter que la ligne utilisée dans la variable ACCOUNT sera celle qui sera facturée. Elle le sera à hauteur de deux appels sortants. De plus, les règles d appels sortants simultanés de la ligne ACCOUNT s appliquent dans ce cas

13 Envoi de SMS Format des requêtes pour un envoi de SMS La requête doit être transmise dans le format suivant : MSG=<contenu_du_sms> Où <ligne_keyyo> doit être remplacé par le numéro de ligne Keyyo émettrice de la demande au format international, <destinataire> par le numéro du correspondant et <contenu_du_sms> par le texte à envoyer au correspondant. Gestion de profils La demande de modification de profil d une ligne Keyyo s effectue de la manière suivante : Où <ligne_keyyo> doit être remplacé par le numéro de ligne Keyyo émettrice de la demande au format international et <nom_du_profil> correspond au nom du profil que nous souhaitons appliquer sur la ligne

14 Authentification Toutes les actions d appels sortants ou de modification de profil sont soumises à authentification. Deux méthodes d authentification peuvent être utilisées en fonction de votre application : Par vérification de l adresse IP source Par authentification HTTP DIGEST Vérification d IP source Pour utiliser la vérification de l IP source, il faut remplir le champ correspondant dans l interface Web Keyyo Regexp d autorisation sur l IP source en mettant l adresse IP qui sera présentée par votre serveur lors de l envoi de la requête. Il est également possible de renseigner plusieurs adresses IP avec le symbole OU : Si le champ Regexp d autorisation sur l IP source n est pas renseigné ou incorrect, la méthode suivante est appliquée. Authentification HTTP DIGEST Pour utiliser l authentification HTTP DIGEST de la ligne Keyyo, il faut que le nom d utilisateur soit le login SIP (numéro de ligne au format international) et que le mot de passe soit le mot de passe SIP

15 Exemples de programmation côté serveur Dans les exemples de cette documentation, nous utilisons le langage de programmation PHP. De fait, cela nécessite la mise en place d un serveur Web. Dans certains cas, il faudra penser à activer Curl dans le php.ini sous Windows ou à le mettre en place sous Linux (sous Debian par exemple : apt-get install php5-curl ). Appel sortant avec authentification par IP source Voici un exemple de configuration du lien à envoyer pour que l appel soit bien lancé. Nous constatons bien qu aucune information d authentification n est nécessaire car l IP source est vérifiée côté serveur Keyyo. Code <? php $account = " "; $callee = " "; $calleename = "Test"; $url = " $account; $url.= "&CALLEE=". $callee. "&CALLEE_NAME=". $calleename; if ( $fp = fopen ( $url, "r" )) { echo "OK"; } else { echo "Error"; }?> Dans cet exemple, un OK va apparaitre sur votre page pour vous signifier que l appel est lancé. Vous recevez en simultané un appel sur votre ligne

16 Appel sortant avec authentification HTTP Code Sans vérification du certificat SSL <? php $account = " "; $callee = " "; $passsip = "Aaze123"; $ch = curl_init (); curl_setopt ( $ch, CURLOPT_URL, " ACCOUNT=". $account. "&CALLEE=". $callee ); // Adresseàrequêter. curl_setopt ( $ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST ); // Type d'authentification curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, 1 ); curl_setopt ( $ch, CURLOPT_USERPWD, $account. ":". $passsip ); // identifiant SIPKeyyo":" MotdepasseSIP curl_setopt ( $ch, CURLOPT_SSL_VERIFYPEER, false ); // Nepasvérifierle certificatssl $data = curl_exec ( $ch ); curl_close ( $ch ); echo$data ; // onafficheleokdekeyyopourvérification?> Code Avec vérification du certificat SSL <? php $account = " "; $callee = " "; $passsip = "Aaze123"; $ch = curl_init (); curl_setopt ( $ch, CURLOPT_URL, " $account. "&CALLEE=". $callee ); // Adresseàrequêter. curl_setopt ( $ch, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST ); // Type d'authentification curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, 1 ); curl_setopt ( $ch, CURLOPT_USERPWD, $account. ":". $passsip ); // identifiant SIPKeyyo":" MotdepasseSIP curl_setopt ( $ch, CURLOPT_SSL_VERIFYPEER, true ); curl_setopt ( $ch, CURLOPT_SSL_VERIFYHOST, 2 ); curl_setopt ( $ch, CURLOPT_CAINFO, dirname ( FILE ). "\cacert.pem" ); // indiquericilecheminabsoludufichier $data = curl_exec ( $ch ); curl_close ( $ch ); echo$data ; // onafficheleokdekeyyopourvérification?> 16-20

17 Réception et traitement de notifications d appels Nous pouvons reprendre l exemple cité précédemment : le mobile appelle la ligne Keyyo Lors du décrochage, le serveur va recevoir la notification suivante : /notification.php?account= &caller= &callee= &type =CONNECT Sur le serveur, la page notification.php ressemblera à ceci si on souhaite insérer les informations dans une base de données : Code <? php $account = $_GET [ 'account' ]; $caller = $_GET [ 'caller' ]; $callee = $_GET [ 'callee' ]; $type = $_GET [ 'type' ]; $sql = "INSERTINTOvotretable(id,account,caller,callee,type,time) VALUES ( '', '$account', '$caller', '$callee', '$type', NOW ()) "; $req = mysql_query ( $sql ) or die ( 'ErreurSQL: <br/>'. $sql ); echo 'insertionok';?> Il faut bien penser à sécuriser les récupérations de variables afin d éviter tout injection SQL non désirée, via expression régulière par exemple car le format des informations envoyées est toujours le même soit : Account, callee, caller : numéro au format international soit (dans le cas d un numéro étranger il peut y avoir plus de chiffres). Type : SETUP, CONNECT ou RELEASE sont les trois seules informations que vous allez récupérer

18 Envoi de SMS Il est également possible d envoyer des SMS, de la manière suivante : Code <? php $account = " "; $callee = " "; $texte = "Test"; $url = " & CALLEE = ".$call ee." & MSG = ".$texte; $ch = curl_init (); curl_setopt ( $ch, CURLOPT_URL, $url ); curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, true ); curl_setopt ( $ch, CURLOPT_SSL_VERIFYPEER, false ); $data = curl_exec ( $ch ); curl_close ( $ch ); echo$data;?> Un OK apparaîtra sur la page pour signifier que le SMS est bien parti. Si cela n est pas le cas, un message d erreur spécifique apparaîtra

19 Keyyo TAPI Fonctionnalités principales et compatibilité TAPI permet de contrôler les fonctions de téléphonie depuis vos PC sous Windows. Keyyo TAPI est compatible Microsoft TAPI version 2.x Compatibilité Windows : Windows XP (SP3 Internet Explorer 7) 32bit et 64bit Windows Vista (SP2) 32bit et 64bit Windows 7 (SP1) 32bit et 64bit Windows Server 2003 (SP2 - Internet Explorer 7) 32bit et 64bit Windows Server 2008 (SP2) 32bit et 64bit Principales fonctionnalités : Intégration de la téléphonie Keyyo dans vos applicatifs métiers, CRM & ERP Remontée de fiches clients (notification d appels) Génération d appels sortants : cliquer pour appeler (clic to call) Contrôle d appels (transfert, raccroché...) Installation de Keyyo TAPI L installation se fait via l onglet Applications, dans la rubrique Store du Manager

20 Vous pouvez également installer l application sur une station de travail existante via le Manager (Configurer >Stations de travail) : Une fois installée, l application Keyyo Tapi est visible dans les Keyyo Apps. Cliquez alors sur l icône Ta afin de terminer l installation. Le fichier keyyotapi.tsp contenant les paramètres du compte SIP de l utilisateur est placé dans le répertoire C:\Windows\System32. Dès lors, toutes les applications compatibles TAPI y ont accès. Vous n avez à effectuer cette opération qu une seule fois. Cliquez sur la fenêtre TAPI pour la fermer