Menu Fermer

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.

Résumé

L’API couvre plusieurs cas d’utilisation:

  1. 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.
  2. 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 champDescription
nameNom complet du contact trouvé. Il est utilisé dans l’interface utilisateur pour afficher le nom du contact.
companyNom de l’entreprise à laquelle le contact est lié. Il est utilisé dans l’interface utilisateur pour afficher le nom de l’entreprise.
contactUriThe URI to access the contact page on the CRM. This is used in the user interface to add a link to the contact.
companyUriL’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.
idL’ID du contact dans le CRM. Cette valeur n’est pas affichée.
crmNameLe nom du CRM. Cette valeur, si elle est fournie, est utilisée pour ajouter une info-bulle sur le logo CRM.
crmLogoL’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.
crmActionsIl 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).
customFieldsL’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 :

  1. 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.
  2. 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 champDescription
contactCrmIdL’ID du contact dans le CRM (tel que récupéré dans le lookup)
userCrmIdL’ID de l’utilisateur lié à l’utilisateur SIP actuel (tel que configuré dans le peoplefone PORTAL)
originatorNumberLe numéro de téléphone ayant initié l’appel
originatorNameLe nom de la personne ayant initié l’appel (si connu)
destinationNumberLe numéro de téléphone composé par l’appelant
destinationNameLe nom de la personne ayant répondu à l’appel (si connu)
directionLa direction de l’appel, soit ‘entrant’ ou ‘sortant’.
startedTimeLa date/heure du début de l’appel (dès la sonnerie).
answeredTimeLa date/heure à laquelle l’appel a été répondu. Cette valeur est vide si l’appel n’a pas été répondu.
endedTimeLa date/heure à laquelle l’appel s’est terminé
declinedTimeLa date/heure à laquelle l’appel a été interrompu, cette valeur est vide si l’appel a été pris.
idL’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 champDescription
idL’ID de l’objet créé par le business workflow
urlL’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”).