Terminologie
Client est utilisé pour identifié un client ou un partenaire peoplefone qui fera l’intégration avec peoplefone CONNECTOR
Phone lookup service est utilisé pour identifié le service du client qui utilise l’interface actuelle afin que peoplefone CONNECTOR puisse acquérir des données.
Résumé
L’API couvre plusieurs cas d’utilisation:
- Recherche de données à des fins de notification
Lorsqu’un appel téléphonique est effectué (entrant ou sortant), peoplefone HOSTED en informera le peoplefone CONNECTOR qui recherchera les données à l’aide de la REST API décrite dans cet article. - Interaction du workflow métier
Lorsque l’utilisateur de peoplefone CONNECTOR clique sur l’un des business workflow, peoplefone CONNECTOR transfert la demande au phone lookup service pour traitement. Le business workflow peut être quelque chose comme la création d’un ticket ou d’un d’appels dans le CRM.
Partie 1 – data lookup
Requête
URL
<root-url>/Lookup (example: https://my-company.com/services/Lookup)
L’URL est définie par le client pour permettre à peoplefone CONNECTOR d’accéder au service de recherche téléphonique. Cette URL ne contient PAS de données privées requises pour la recherche, ces données sont fournies via des en-têtes HTTP.
Query parameters
peoplefone CONNECTOR fournira le numéro de téléphone via les query parameters:
Key: PhoneNumber
Value (exemple): 4178907228
https://clientServiceAddress/someController?PhoneNumber=4178907228
HTTP Headers
Pour l’authentification, peoplefone CONNECTOR doit fournir le jeton suivant via le HTTP Header:
Key: X-Execution-Token
Value: jlvlkdshvövdjhwgjwogjhwg
Les key et value du Header est configurable via le portail client peoplefone sous peoplefone CONNECTOR.
Body
Le body de la demande contient le numéro de téléphone pour lequel le lookup est demandé :
{
"inputs": {
"phoneNumber":"41215522000"
}
}Réponse
Exemple de body
[
{
"name": "Alexa Holiday",
"company": "White Cross Co",
"contactUri": "https://...",
"companyUri": "https://...",
"id": "Crm Identification Number",
"crmName": "Sugar CRM",
"crmLogo": "https://...",
"crmActions":["CallFlow"],
"customData": {
"title1": "Data1",
"title2": "Data2"
}
},
{
...
}
]Layer 1: la liste
Le résultat attendu est un tableau d’objets. Il est recommandé de ne renvoyer qu’un très petit nombre de résultats. La valeur de 5 résultats maximum est la plus appropriée pour un bon équilibre entre performance et précision. L’augmentation de cette valeur peut se provoquer de nombreux retards et problèmes de performances à toutes les étapes du processus.
Si la requête ne renvoie aucune valeur, peoplefone CONNECTOR s’attend à recevoir un tableau vide avec un code d’état 200. Il ne devrait PAS recevoir un code d’état 404 dans ce cas, le code d’état 404 signifie que le phone lookup service n’est pas accessible.
Layer 2: l’objet
Les objets composant la liste représentent une entrée trouvée pour le numéro de téléphone donné dans le/l’un des CRM intégré(s). Cet objet contient quelques champs requis pour que peoplefone CONNECTOR affiche correctement l’entrée ainsi qu’une liste de paires key-value pour toutes les données spécifiques que le client souhaite ajouter.
| Nom du champ | Description |
| name | Nom complet du contact trouvé. Il est utilisé dans l’interface utilisateur pour afficher le nom du contact. |
| company | Nom de l’entreprise à laquelle le contact est lié. Il est utilisé dans l’interface utilisateur pour afficher le nom de l’entreprise. |
| contactUri | The URI to access the contact page on the CRM. This is used in the user interface to add a link to the contact. |
| companyUri | L’URI pour accéder à la page de contact sur le CRM. Il est utilisé dans l’interface utilisateur pour ajouter un lien vers le contact. |
| id | L’ID du contact dans le CRM. Cette valeur n’est pas affichée. |
| crmName | Le nom du CRM. Cette valeur, si elle est fournie, est utilisée pour ajouter une info-bulle sur le logo CRM. |
| crmLogo | L’URL du logo du CRM. Cette valeur, si elle est fournie, est utilisée pour ajouter un logo sur la fiche de contact pour cette entrée. Ceci est facultatif si le client s’intègre à un seul CRM. Cependant, cela devient utile si le client a plusieurs intégrations avec différents CRM. |
| crmActions | Il s’agit d’une liste de string, chaque string étant le nom du workflow disponible applicable à ce contact. Ce nom sera utilisé pour piloter l’ensemble des capacités du workflow de l’entreprise (plus d’informations sur la deuxième partie de l’API). |
| customFields | L’objet CustomFields est un ensemble de paires key-value que le client peut utiliser pour transporter toutes les données dont il a besoin pour l’intégration. Ces données, si elles sont présentes, seront affichées dans l’interface utilisateur de peoplefone CONNECTOR. Il peut s’agir, par exemple, de l’adresse e-mail du contact ou de la langue parlée par le contact ou toute autre chose. |
Partie 2 – Business workflow
Request
URL
<root-url>/<workflow-name>
La <root-url> correspond à la même valeur que pour le for the lookup (voir partie 1). Le <workflow-name>est le nom donné par le lookup dans le tableau CrmActions.
Le <workflow-name> est relativement libre d’utilisation, cependant la valeur est utilisée à deux autres endroits en dehors de peoplefone CONNECTOR API :
- Pour afficher le business workflow dans la page web de peoplefone CONNECTOR. Certaines données prédéfinies seront traduites, autrement elles seront affichées telles quelles.
- Pour la configuration automatique d’un business workflow. Pour le moment, seul les business workflow appelé “CallFlow” peuvent être configurés dans le peoplefone PORTAL. Les autres cas seront traités manuellement.
Query parameters
peoplefone CONNECTOR ne fournira aucun paramètre
HTTP Headers
For authentication, peoplefone CONNECTOR will provide the same headers than for the lookup, as configured in the peoplefone CUSTOMER-PORTAL page.
Pour l’authentification, peoplefone CONNECTOR fournira les mêmes en-têtes que pour le lookup, comme configuré dans la page peoplefone PORTAL.
Body
Le body de la requête contient toutes les informations requises à l’exécution du business workflow. Le payload pourrait être étendue à l’avenir. Il s’agit d’un champ “inputs” contenant un simple objet JSON avec les champs suivants :
| Nom du champ | Description |
| contactCrmId | L’ID du contact dans le CRM (tel que récupéré dans le lookup) |
| userCrmId | L’ID de l’utilisateur lié à l’utilisateur SIP actuel (tel que configuré dans le peoplefone PORTAL) |
| originatorNumber | Le numéro de téléphone ayant initié l’appel |
| originatorName | Le nom de la personne ayant initié l’appel (si connu) |
| destinationNumber | Le numéro de téléphone composé par l’appelant |
| destinationName | Le nom de la personne ayant répondu à l’appel (si connu) |
| direction | La direction de l’appel, soit ‘entrant’ ou ‘sortant’. |
| startedTime | La date/heure du début de l’appel (dès la sonnerie). |
| answeredTime | La date/heure à laquelle l’appel a été répondu. Cette valeur est vide si l’appel n’a pas été répondu. |
| endedTime | La date/heure à laquelle l’appel s’est terminé |
| declinedTime | La date/heure à laquelle l’appel a été interrompu, cette valeur est vide si l’appel a été pris. |
| id | L’ID renvoyé par le CRM lors de la précédente requête du workflow (pour le même appel). Null s’il s’agit de la première demande. |
{
"inputs": {
"contactCrmId":"...",
"userCrmId":"...",
...
}
}Response
La réponse attendue par peoplefone CONNECTOR est un simple objet JSON avec deux champs, la réponse entière, ainsi que chaque champ, sont optionnels. Le but de l’url serait d’ouvrir optionnellement la page CRM directement après la fin du workflow.
| Nom du champ | Description |
| id | L’ID de l’objet créé par le business workflow |
| url | L’URL d’accès à l’objet créé par le business workflow |
{
"id":"...",
"url":"..."
}Problèmes de performance
Le temps de réponse est essentiel pour permettre à l’utilisateur de voir, dès que possible, les informations appropriées dans l’application peoplefone CONNECTOR.
Le phone lookup service doit être aussi rapide que possible pour assurer un temps de réponse court à l’utilisateur de peoplefone CONNECTOR. Si toute fois le phone lookup service devait répondre trop lentement le peoplefone CONNECTOR enverra un timeout et répondra une information de base à l’utilisateur (le numéro de téléphone et le statut de l’appel avec comme nom “inconnu”).