Pour utiliser la téléphonie TotalVoice dans Mavibot, vous devez obtenir un jeton d'accès depuis le tableau de bord TotalVoice et le saisir dans les paramètres d'intégration. TotalVoice est un service de téléphonie brésilien qui fait désormais partie du groupe Zenvia.

Le bot peut connecter un employé à un client, transférer et terminer des appels, récupérer les enregistrements d'appels et envoyer des événements d'appel à la conversation. TotalVoice fournit également le coût de chaque appel.

Obtention des données requises

  1. Créez un compte Zenvia Voice et ajoutez des fonds à votre solde.

  1. Connectez-vous au tableau de bord. Dans le coin inférieur gauche de l'écran principal, à côté de Access Token, cliquez sur l'icône de copie.

Access Token est la seule clé qui donne accès à l'ensemble de votre compte, y compris la possibilité de passer des appels payants. Ne le publiez pas et ne le partagez pas en dehors de votre entreprise.

Connexion

Dans les paramètres de téléphonie, sélectionnez TotalVoice et saisissez :

  • Access Token — la clé du tableau de bord TotalVoice.
  • Numéro présenté au client — le numéro que le client verra, au format +551140028922. Ce champ est facultatif. S'il est laissé vide, le numéro par défaut de votre compte TotalVoice sera utilisé.


Après l'enregistrement, une URL de notification apparaîtra sur la page de connexion. Vous devez l'ajouter au tableau de bord TotalVoice — voir la section suivante.

L'intégration est maintenant connectée. Pour la déconnecter, effacez le champ Access Token et enregistrez les paramètres.

Configuration des notifications

Contrairement aux autres intégrations téléphoniques, l'URL de notification doit être configurée manuellement car TotalVoice ne permet pas à Mavibot de le faire automatiquement.

  1. Copiez l'URL affichée sur la page de connexion.

  1. Dans le tableau de bord TotalVoice, ouvrez Desenvolvedores → Configurações da API.
  2. Collez la même URL dans les trois champs de webhook :
    • Status Tempo Real — changements de statut de l'appel pendant qu'il est en cours ;
    • Chamada - Fim — fin d'un appel ;
    • DID - Fim de Chamada — fin d'un appel entrant vers votre numéro.

⏳ Les notifications peuvent prendre jusqu'à 20 minutes pour commencer à arriver après l'enregistrement des paramètres. C'est une limitation de TotalVoice. Si aucun événement n'apparaît dans la conversation immédiatement après la configuration, attendez simplement.

Si vous régénérez votre Access Token, l'URL de notification changera. Enregistrez le nouveau jeton dans Mavibot et mettez à jour l'URL dans le tableau de bord TotalVoice, sinon les événements d'appel cesseront d'arriver.

Employés

Dans les paramètres de l'employé, saisissez le numéro TotalVoice de l'employé.


Vous pouvez utiliser soit une extension interne (ramal, généralement 3 à 4 chiffres) soit un numéro mobile régulier au format +5511987654321. C'est l'une des rares intégrations où le format est flexible : si l'employé n'utilise pas d'extension PBX interne, saisissez son numéro mobile.

Appel depuis la fiche client

Un bouton d'appel apparaîtra à côté du numéro de téléphone du client dans la fiche de conversation. TotalVoice appelle d'abord l'employé, et seulement après que l'employé répond, il appelle le client.

Cet ordre est intentionnel : le client n'entendra pas de silence sur la ligne car l'employé est déjà connecté lorsque le téléphone du client commence à sonner.

Fonctions de la calculatrice

Appel employé vers client

totalvoice_employee_call(client_phone, employee_number, bina, gravar_audio)

Paramètres :

  • client_phone — le numéro de téléphone du client au format +5511987654321. Requis.
  • employee_number — le numéro de l'employé : soit une extension interne, soit un numéro mobile. Requis.
  • bina — le numéro que le client verra. Facultatif. S'il est omis, le numéro des paramètres de connexion est utilisé.
  • gravar_audio — indique s'il faut enregistrer l'appel. Facultatif. L'enregistrement est activé par défaut.

Transfert d'appel

totalvoice_transfer_call(number, call_id, leg)

Paramètres :

  • number — le numéro vers lequel l'appel doit être transféré. Requis.
  • call_id — l'identifiant de l'appel. Facultatif. S'il est omis, l'appel le plus récent du client est utilisé.
  • leg — quel côté de l'appel transférer : destino (le client, valeur par défaut) ou origem (l'employé).

Terminer l'appel

totalvoice_hangup_call(call_id)

Paramètres :

  • call_id — l'identifiant de l'appel. Facultatif. S'il est omis, l'appel le plus récent du client est utilisé.

Obtenir le lien d'enregistrement de l'appel

totalvoice_get_record_link(call_id)

Normalement, le lien d'enregistrement est reçu automatiquement avec l'événement de fin d'appel. Cette fonction est utile si la notification n'a pas été reçue ou si vous avez besoin d'un enregistrement d'un appel plus ancien.

Paramètres :

  • call_id — l'identifiant de l'appel. Facultatif. S'il est omis, l'appel le plus récent du client est utilisé.

Rappels pendant un appel

Au fur et à mesure que l'appel progresse, des rappels sont envoyés à la conversation au format suivant :

totalvoice_call_event atendida

Événements possibles :

Événement Quand il est déclenché
chamando L'appel sonne
preparando La ligne est en cours de préparation pour la connexion
atendida L'appel a été répondu
sem_resposta Pas de réponse
ocupado Occupé
cancelada L'appel a été annulé
congestionado Congestion du réseau de l'opérateur
falha L'appel n'a pas pu être terminé
nao_existe Le numéro n'existe pas

Les noms de statut sont reçus en portugais car ce sont les noms de statut utilisés par TotalVoice.

Un scénario typique "pas de réponse → envoyer un message dans le messager" peut être construit en vérifiant la variable totalvoice_call_answered.

Les notifications de statut d'appel sont envoyées au maximum une fois toutes les 2 secondes par appel. Pour les appels très courts, certains statuts intermédiaires peuvent ne pas arriver à temps. L'événement de fin d'appel est toujours envoyé.

Variables client après un appel

Variable Valeur
totalvoice_call_id Identifiant de l'appel
totalvoice_call_status Statut de l'appel tel que défini par TotalVoice
totalvoice_call_answered 1 — l'appel a été répondu, 0 — il ne l'a pas été
totalvoice_call_duration Durée de l'appel en secondes
totalvoice_call_price Coût de l'appel en réaux brésiliens
totalvoice_hangup_reason Raison de la fin de l'appel
totalvoice_record_link Lien vers l'enregistrement de l'appel

La durée signifie le temps de conversation réel, excluant le temps passé à attendre que l'appel soit répondu. Gardez à l'esprit que TotalVoice calcule la facturation différemment : le temps facturable est arrondi à la minute complète supérieure, donc un appel de 24 secondes sera facturé comme une minute. Pour vérifier les frais, utilisez le rapport de facturation dans le tableau de bord TotalVoice plutôt que cette variable.

Enregistrements d'appels

L'enregistrement est configuré séparément pour chaque appel et est activé par défaut. Vous pouvez le désactiver pour un appel spécifique en utilisant le paramètre gravar_audio dans la fonction d'appel.

Lorsque l'appel se termine, le lien d'enregistrement est reçu avec l'événement et enregistré dans la variable totalvoice_record_link. Vous n'avez pas besoin de le demander séparément.

L'enregistrement des appels est réglementé par la loi. Au Brésil, il est soumis aux exigences de la LGPD : le client doit être informé que l'appel est enregistré, et il doit y avoir une base légale pour stocker les données. Le propriétaire du compte TotalVoice est responsable du respect de ces exigences.

Dépannage

Erreur Cause / Solution
L'appel n'est pas créé et le message d'erreur est en portugais TotalVoice renvoie la raison sous forme de texte. Les causes les plus courantes sont un solde insuffisant ou un format de numéro de téléphone invalide.
Les appels fonctionnent, mais aucun rappel n'apparaît dans la conversation L'URL de notification n'a pas été ajoutée au tableau de bord TotalVoice, n'a pas été ajoutée aux trois webhooks, ou 20 minutes ne se sont pas écoulées depuis la configuration.
Tout fonctionnait avant, mais les événements se sont soudainement arrêtés L'Access Token a été régénéré, ce qui a changé l'URL de notification. Enregistrez le nouveau jeton dans Mavibot et mettez à jour l'URL dans le tableau de bord TotalVoice.
"Numéro TotalVoice non spécifié" Le numéro TotalVoice de l'employé est manquant dans ses paramètres.
Statut nao_existe Le numéro du client n'existe pas. Vérifiez le format. Les numéros mobiles brésiliens utilisent +55 + DDD + 9 chiffres.
Statut congestionado Il y a un problème avec le réseau de l'opérateur et il n'est pas lié au numéro du client. Si le problème persiste, contactez le support TotalVoice.
Pas de lien d'enregistrement L'appel a été créé avec l'enregistrement désactivé, ou l'appel n'a pas été répondu.