peoplefone CONNECTOR API (REST API)

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.

Quand peut-on utiliser peoplefone CONNECTOR API?

Si le CRM du client n’est pas supporté par peoplefone, nous lui demandons de fournir un phone lookup service.

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 :

To display the business workflow in the peoplefone CONNECTOR web page. For some predefined values it will be translated, otherwise it will be displayed AS-IS.
For automatic business workflow configuration. At the moment only business workflow called “CallFlow” can be configured in the peoplefone CUSTOMER-PORTAL to be set automatic, all other cases will be manual only.

Query parameters

peoplefone CONNECTOR will provide no query parameters

HTTP Headers

For authentication, peoplefone CONNECTOR will provide the same headers than for the lookup, as configured in the peoplefone CUSTOMER-PORTAL page.

Body

The body of the request contains all required information for the business workflow to be executed. This payload could be extended in the future. It is an “inputs” field containing a simple JSON object with the following fields:

Field Name	Description
contactCrmId	The ID of the contact in the CRM (as retrieved from the lookup)
userCrmId	The ID of the user linked to the current SIP user (as configured in the CUSTOMER-PORTAL page)
originatorNumber	The phone number that initiated the call.
originatorName	When available the name of the person who initiated the call.
destinationNumber	The phone number composed by the caller.
destinationName	When available the name of the person which answer the call.
direction	The direction of the call, either ‘incoming’ or ‘outgoing’.
startedTime	The date/time when the call was started (ringing).
answeredTime	The date/time when the call was answered, this value is empty if the call was not answered.
endedTime	The date/time when the call was ended.
declinedTime	The date/time when the call was aborted, this value is empty if the call was answered.

{
    "inputs": {
        "contactCrmId":"...",
        "userCrmId":"...",
        ...
    }
}

Response

The response expected by peoplefone CONNECTOR is a simple JSON object with two fields, the whole response, as well as each fields, are optional. The purpose of the url would be to optionally open the CRM page directly after the workflow is ended.

Field Name	Description
id	The ID of the object created by the business workflow
url	The URL to access the object created by the 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 »).