Um die TotalVoice-Telefonie in Mavibot zu nutzen, müssen Sie ein Access Token aus dem TotalVoice-Dashboard abrufen und es in den Integrationseinstellungen eingeben. TotalVoice ist ein brasilianischer Telefoniedienst, der jetzt Teil der Zenvia-Gruppe ist.

Der Bot kann einen Mitarbeiter mit einem Kunden verbinden, Anrufe weiterleiten und beenden, Anrufaufzeichnungen abrufen und Anrufereignisse an die Konversation senden. TotalVoice stellt auch die Kosten für jeden Anruf bereit.

Abrufen der erforderlichen Daten

  1. Erstellen Sie ein Zenvia-Voice-Konto und fügen Sie Ihrem Guthaben Geld hinzu.

  1. Melden Sie sich im Dashboard an. Klicken Sie in der unteren linken Ecke des Hauptbildschirms neben Access Token auf das Kopiersymbol.

Access Token ist der einzige Schlüssel, der Zugriff auf Ihr gesamtes Konto gewährt, einschließlich kostenpflichtiger Anrufe. Veröffentlichen Sie es nicht und teilen Sie es nicht außerhalb Ihres Unternehmens.

Verbindung

Wählen Sie in den Telefonieeinstellungen TotalVoice aus und geben Sie Folgendes ein:

  • Access Token – den Schlüssel aus dem TotalVoice-Dashboard.
  • Client-facing number – die Nummer, die der Kunde sieht, im Format +551140028922. Dieses Feld ist optional. Wenn es leer gelassen wird, wird die Standardnummer aus Ihrem TotalVoice-Konto verwendet.


Nach dem Speichern wird auf der Verbindungsseite eine Notification-URL angezeigt. Sie müssen diese zum TotalVoice-Dashboard hinzufügen – siehe nächster Abschnitt.

Die Integration ist jetzt verbunden. Zum Trennen leeren Sie das Feld Access Token und speichern die Einstellungen.

Benachrichtigungseinrichtung

Im Gegensatz zu anderen Telefonie-Integrationen muss die Benachrichtigungs-URL manuell konfiguriert werden, da TotalVoice keine Möglichkeit bietet, dies automatisch über Mavibot zu tun.

  1. Kopieren Sie die auf der Verbindungsseite angezeigte URL.

  1. Öffnen Sie im TotalVoice-Dashboard Desenvolvedores → Configurações da API.
  2. Fügen Sie dieselbe URL in alle drei Webhook-Felder ein:
    • Status Tempo Real – Anrufstatusänderungen während des Anrufs;
    • Chamada - Fim – Ende eines Anrufs;
    • DID - Fim de Chamada – Ende eines eingehenden Anrufs auf Ihre Nummer.

⏳ Benachrichtigungen können bis zu 20 Minuten nach dem Speichern der Einstellungen benötigen, um anzukommen. Dies ist eine Einschränkung von TotalVoice. Wenn unmittelbar nach der Einrichtung keine Ereignisse in der Konversation erscheinen, warten Sie einfach.

Wenn Sie Ihr Access Token neu generieren, ändert sich die Benachrichtigungs-URL. Speichern Sie das neue Token in Mavibot und aktualisieren Sie die URL im TotalVoice-Dashboard, da sonst keine Anrufereignisse mehr ankommen.

Mitarbeiter

Geben Sie in den Mitarbeitereinstellungen die TotalVoice-Nummer des Mitarbeiters ein.


Sie können entweder eine interne Durchwahl (ramal, normalerweise 3–4 Ziffern) oder eine normale Mobilnummer im Format +5511987654321 verwenden. Dies ist eine der wenigen Integrationen, bei denen das Format flexibel ist: Wenn der Mitarbeiter keine interne PBX-Durchwahl verwendet, geben Sie seine Mobilnummer ein.

Anruf von der Kundendatenkarte

Neben der Telefonnummer des Kunden in der Konversationskarte erscheint eine Anrufschaltfläche. TotalVoice ruft zuerst den Mitarbeiter an, und erst nachdem der Mitarbeiter antwortet, ruft es den Kunden an.

Diese Reihenfolge ist beabsichtigt: Der Kunde hört keine Stille in der Leitung, da der Mitarbeiter bereits verbunden ist, wenn das Telefon des Kunden zu klingeln beginnt.

Rechnerfunktionen

Mitarbeiter-zu-Kunde-Anruf

totalvoice_employee_call(client_phone, employee_number, bina, gravar_audio)

Parameter:

  • client_phone – die Telefonnummer des Kunden im Format +5511987654321. Erforderlich.
  • employee_number – die Nummer des Mitarbeiters: entweder eine interne Durchwahl oder eine Mobilnummer. Erforderlich.
  • bina – die Nummer, die der Kunde sieht. Optional. Wenn nicht angegeben, wird die Nummer aus den Verbindungseinstellungen verwendet.
  • gravar_audio – ob der Anruf aufgezeichnet werden soll. Optional. Die Aufzeichnung ist standardmäßig aktiviert.

Anruf weiterleiten

totalvoice_transfer_call(number, call_id, leg)

Parameter:

  • number – die Nummer, an die der Anruf weitergeleitet werden soll. Erforderlich.
  • call_id – die Anrufkennung. Optional. Wenn nicht angegeben, wird der letzte Anruf des Kunden verwendet.
  • leg – welche Seite des Anrufs weitergeleitet werden soll: destino (der Kunde, Standardwert) oder origem (der Mitarbeiter).

Anruf beenden

totalvoice_hangup_call(call_id)

Parameter:

  • call_id – die Anrufkennung. Optional. Wenn nicht angegeben, wird der letzte Anruf des Kunden verwendet.
totalvoice_get_record_link(call_id)

Normalerweise wird der Aufzeichnungslink automatisch mit dem Anrufende-Ereignis empfangen. Diese Funktion ist nützlich, wenn die Benachrichtigung nicht empfangen wurde oder wenn Sie eine Aufzeichnung eines älteren Anrufs benötigen.

Parameter:

  • call_id – die Anrufkennung. Optional. Wenn nicht angegeben, wird der letzte Anruf des Kunden verwendet.

Callbacks während eines Anrufs

Während des Anrufs werden Callbacks im folgenden Format an die Konversation gesendet:

totalvoice_call_event atendida

Mögliche Ereignisse:

Ereignis Wann es ausgelöst wird
chamando Der Anruf klingelt
preparando Die Leitung wird für die Verbindung vorbereitet
atendida Der Anruf wurde angenommen
sem_resposta Keine Antwort
ocupado Besetzt
cancelada Der Anruf wurde abgebrochen
congestionado Netzüberlastung des Betreibers
falha Der Anruf konnte nicht abgeschlossen werden
nao_existe Die Nummer existiert nicht

Statusnamen werden auf Portugiesisch empfangen, da dies die von TotalVoice verwendeten Statusnamen sind.

Ein typisches Szenario „keine Antwort → Nachricht im Messenger senden“ kann durch Überprüfen der Variablen totalvoice_call_answered erstellt werden.

Benachrichtigungen zum Anrufstatus werden höchstens einmal alle 2 Sekunden pro Anruf gesendet. Bei sehr kurzen Anrufen können einige Zwischenstatus nicht rechtzeitig ankommen. Das Anrufende-Ereignis wird immer gesendet.

Client-Variablen nach einem Anruf

Variable Wert
totalvoice_call_id Anrufkennung
totalvoice_call_status Anrufstatus gemäß TotalVoice
totalvoice_call_answered 1 – der Anruf wurde angenommen, 0 – er wurde nicht angenommen
totalvoice_call_duration Anrufdauer in Sekunden
totalvoice_call_price Anrufkosten in brasilianischen Reais
totalvoice_hangup_reason Grund für das Ende des Anrufs
totalvoice_record_link Link zur Anrufaufzeichnung

Dauer bedeutet tatsächliche Sprechzeit, ohne die Zeit, die auf die Annahme des Anrufs gewartet wurde. Beachten Sie, dass TotalVoice die Abrechnung anders berechnet: Die abrechenbare Zeit wird auf die nächste volle Minute aufgerundet, sodass ein 24-sekündiger Anruf als eine Minute abgerechnet wird. Verwenden Sie zur Überprüfung der Gebühren den Abrechnungsbericht im TotalVoice-Dashboard und nicht diese Variable.

Anrufaufzeichnungen

Die Aufzeichnung wird für jeden Anruf separat konfiguriert und ist standardmäßig aktiviert. Sie können sie für einen bestimmten Anruf mit dem Parameter gravar_audio in der Anruffunktion deaktivieren.

Wenn der Anruf endet, wird der Aufzeichnungslink mit dem Ereignis empfangen und in der Variablen totalvoice_record_link gespeichert. Sie müssen ihn nicht separat anfordern.

Die Aufzeichnung von Anrufen ist gesetzlich geregelt. In Brasilien unterliegt sie den LGPD-Anforderungen: Der Kunde muss darüber informiert werden, dass der Anruf aufgezeichnet wird, und es muss eine rechtmäßige Grundlage für die Speicherung der Daten geben. Der Inhaber des TotalVoice-Kontos ist für die Einhaltung dieser Anforderungen verantwortlich.

Fehlerbehebung

Fehler Ursache / Lösung
Der Anruf wird nicht erstellt und die Fehlermeldung ist auf Portugiesisch TotalVoice gibt den Grund als Text zurück. Die häufigsten Ursachen sind unzureichendes Guthaben oder ein ungültiges Telefonnummernformat.
Anrufe funktionieren, aber keine Callbacks erscheinen in der Konversation Die Benachrichtigungs-URL wurde nicht zum TotalVoice-Dashboard hinzugefügt, nicht zu allen drei Webhooks hinzugefügt, oder seit der Konfiguration sind noch keine 20 Minuten vergangen.
Alles funktionierte vorher, aber Ereignisse hörten plötzlich auf Das Access Token wurde neu generiert, wodurch sich die Benachrichtigungs-URL geändert hat. Speichern Sie das neue Token in Mavibot und aktualisieren Sie die URL im TotalVoice-Dashboard.
„TotalVoice-Nummer ist nicht angegeben“ Die TotalVoice-Nummer des Mitarbeiters fehlt in seinen Einstellungen.
Status nao_existe Die Nummer des Kunden existiert nicht. Überprüfen Sie das Format. Brasilianische Mobilnummern verwenden +55 + DDD + 9 Ziffern.
Status congestionado Es gibt ein Problem mit dem Netzwerk des Betreibers, das nichts mit der Nummer des Kunden zu tun hat. Wenn das Problem weiterhin besteht, kontaktieren Sie den TotalVoice-Support.
Kein Aufzeichnungslink Der Anruf wurde mit deaktivierter Aufzeichnung erstellt, oder der Anruf wurde nicht angenommen.