VoiceAI campaigns¶
Requires the "Campaigns" permission.
In a VoiceAI campaign the contacts are not called by an operator but by a voice assistant (the phone system's bot). Thelgo dials the numbers automatically, the bot talks to whoever answers and tells Thelgo how it went: outcome, any appointment, any email or SMS to send. If the contact asks to speak to a person, the bot passes the call to a phone system group, and an operator works it in Thelgo.
VoiceAI campaigns are created with the same guided procedure as the other campaigns (see Create and edit a campaign): this page describes only what is specific to the VoiceAI type.
The account must be enabled
The VoiceAI type must be enabled on your account by whoever manages the Thelgo platform. If it is not, in the Basic data step the Type field does not offer VoiceAI (see also Campaign types). If the enablement is removed after VoiceAI campaigns have been created, those campaigns keep showing their type when edited and can still be saved, but you cannot create a new one or turn another campaign into VoiceAI: saving is refused with "VoiceAI campaigns are not enabled for this account." The automatic call engine also does not launch calls for types that are not enabled.
The phone system must also be prepared (bot, time tables, connection with Thelgo): this is done by Thelgo support, not by the company's administrator.
How a call works¶
- The engine chooses a contact with the same rules as the Predictive campaigns: first the callbacks that are due, then the campaign's ordering, only within the Working time slots, within the validity period and, if the database is RPO, with a valid list. There is no operator to wait for: the campaign launches at most Max simultaneous calls calls together (conversations still in progress with the bot count), within the overall call limits set for the account. There is no Percentage nor Silent call control, which apply only to Predictive.
- If the contact answers, the bot chosen in the campaign starts. The bot receives the contact's data and the already composed Welcome message, and decides by itself how to conduct the conversation. If the campaign has Record calls (and, if provided for the account, Call transcription), the call is recorded from the moment of the answer.
- During the conversation the bot can use four tools, described below: propose the agents' free times, record the outcome (with an optional appointment), send an email, send an SMS.
- If a person is needed, the bot transfers the call to the Group for operator forwarding.
- At the end of the call Thelgo closes the call line. If the bot has already recorded the outcome, nothing changes; if the contact answered but the bot did not record any outcome, the VoiceAI call answered but without an outcome setting applies (see General settings).
If the end of the call never arrives
If the phone system never reports the end of a conversation with the bot, 20 minutes after the answer Thelgo considers it ended and applies the same handling ("outcome already recorded" or "answered without an outcome").
Creating a VoiceAI campaign¶
In step 1. Basic data choose Type → VoiceAI: besides Title, Database, Start, End and No end date, the following fields appear. They are Group for operator forwarding, Welcome message with the placeholder buttons and Working time slots, further down than Bot.
| Field | What to enter | Notes |
|---|---|---|
| Phone number to use | Which of the contact's numbers the engine calls: from Phone1 to Phone9, or All | As in Predictive (see Predictive and VoiceAI settings). Default: Phone1. A contact that does not have that number is excluded from calls as unreachable and the engine continues with the others: see Putting contacts without a number back on the list |
| Max simultaneous calls | How many calls the campaign can make together | Minimum 1 (the field does not accept lower values). Default: 1 |
| Bot | The phone system bot that conducts the conversation | Required if your account has a phone system. See below |
| Group for operator forwarding | The phone system group to which the bot passes the call when a person is needed | Optional. See below |
| Welcome message | Opening sentence with the contact's data | Optional. See below |
| Working time slots | When the engine can call | At least one. Same rules as Predictive: see Working time slots |
| Trunk, Numbering | Line and number the calls start from | Required (Other settings box, present if your account has a phone system) |
Record calls, Call transcription and Prefix work as for the other campaigns. The Prefix is placed before the dialed number.
The bot¶
The Bot menu lists the bots of your account's phone system that have been made available to your account, in alphabetical order (on a phone system shared with other companies you see only yours, not those of the others; on your own phone system you see all of them). While it reads them it shows "Loading…"; then the initial entry is Select the bot.
| What you see | Meaning |
|---|---|
| "Unable to read the list of bots from the PBX: please try again later." (in red) | The phone system did not respond. Reopen the step or try again shortly; if it persists, contact Thelgo support |
| "No bot is available for your account: please contact support." | There is no bot available for your account: the bot is not created in Thelgo, contact Thelgo support |
The bot's language (and voice) are not chosen in the campaign: the language is set directly on the bot, in the phone system.
When editing, if the saved bot no longer appears in the list it stays chosen anyway, with the name it had: Thelgo does not replace it by itself.
The group for forwarding to an operator¶
The field indicates who the bot passes the call to when the contact asks for a person.
- It is a menu with the answering groups of the phone system made available to your account. The initial entry is No group, and below you read "Optional. PBX answering group the bot transfers the call to when a human operator is needed."
- The group is not typed by hand, it is chosen from the menu. If Thelgo cannot read the groups from the phone system, "Unable to read the groups from the PBX: please try again later." appears in red under the menu: reopen the page or try again shortly.
- If no group is available for your account, you read "No answer group is available for your account: please contact support." (Thelgo support chooses which phone system resources to make visible to each account that uses a shared phone system).
- When editing, a group already saved that is no longer in the list stays in the menu with its name.
- When you save the campaign with a new group, Thelgo automatically prepares on the phone system the rule that allows the bot to transfer the call to that group.
Messages when saving
If you choose a group or a bot that is no longer available for your account, saving is refused with "The selected answering group is not available for this account." or "The selected bot is not available for this account." Other possible reasons: "The selected answering group is not valid.", "No Wildix PBX is configured for this account: an answering group cannot be used.", "Il gruppo di risposta N non esiste sul centralino." (Answering group N does not exist on the phone system.) and "The forwarding to the answering group could not be prepared on the PBX: …" (after the colon comes the detail). When editing, the check is made only if you change the bot or the group (or turn the campaign into VoiceAI): an existing campaign can be edited even if the phone system is temporarily unreachable or if the provider has removed the bot or the group from the account's availability.
The operators who answer on the group must be enabled for the campaign (see Enabled operators). If you do not set any group, no group to transfer to is communicated to the bot.
The welcome message¶
It is optional. Thelgo composes it for each call, replacing the placeholders with the contact's data, and delivers it to the bot; the bot decides how to use it (usually as an opening sentence). Under the field you read "Optional. Welcome message for the contact, made available to the bot in the VOICEBOT_MSGBENVENUTO variable (the bot decides how to use it). You can use the placeholders shown below, and the name of an additional database field between double curly braces."
To insert a placeholder click the corresponding button in the grey box under the message ("Click to insert a placeholder in the message: the greetings in the various languages (SalutoIT, SalutoEN, … → good morning/good evening in that language, depending on the time) and the contact's data."): it is written where the cursor is. The buttons are:
| Placeholder | Becomes |
|---|---|
{{SalutoIT}}, {{SalutoEN}}, {{SalutoES}}, {{SalutoFR}}, {{SalutoDE}}, {{SalutoCS}}, {{SalutoRO}} |
The greeting for that time of day, in the language indicated by the suffix (see table below) |
{{Nominativo}} |
The contact's first and last name or, if missing, the company name |
{{RagioneSociale}}, {{Nome}}, {{Cognome}} |
The corresponding field of the contact |
{{Indirizzo}}, {{Cap}}, {{Comune}}, {{Provincia}} |
The address fields |
{{Telefono1}}, {{Email}} |
The contact's phone 1 and email |
You can also type by hand the name of an additional database field between double curly braces (for example {{Prodotto}}). A placeholder that has no value for that contact is removed from the message, so the bot does not read "{{Cognome}}" aloud.
Greetings in the various languages¶
The greetings are based on your account's local time: until 15:59 it is morning, from 16:00 onwards it is evening.
| Placeholder | Until 15:59 | From 16:00 |
|---|---|---|
{{SalutoIT}} |
Buongiorno | Buonasera |
{{SalutoEN}} |
Good morning | Good evening |
{{SalutoES}} |
Buenos días | Buenas tardes |
{{SalutoFR}} |
Bonjour | Bonsoir |
{{SalutoDE}} |
Guten Morgen | Guten Abend |
{{SalutoCS}} |
Dobrý den | Dobrý večer |
{{SalutoRO}} |
Bună dimineața | Bună seara |
Example: {{SalutoIT}}, sono l'assistente virtuale di Esempio Srl. Parlo con {{Nominativo}}?
The placeholder without a language
The greeting is chosen by writing the placeholder of the language you want. {{Saluto}} without a suffix works as a greeting in Italian (it is needed for messages already saved and for those imported from the old software), but it is not offered among the buttons.
Validations¶
As long as the required data are missing you see in grey (not in red, because when the form has just opened it is normal for everything to be missing) the hint "VoiceAI campaigns require: at least 1 simultaneous call, the bot and at least one time slot." and Next stays off. In addition you need Trunk and Numbering: if they are missing, "Trunk and numbering are required for Preview, Predictive and VoiceAI campaigns: without them no call can start." appears in red.
The server repeats the checks on saving and, if something is wrong, shows one of these messages at the bottom:
| Message | What to do |
|---|---|
| "Enter how many calls the campaign can make at the same time (at least 1)." | Enter a number from 1 up in Max simultaneous calls |
| "Select the campaign's bot." | Choose the Bot |
| "Trunk and numbering are required for Preview, Predictive and VoiceAI campaigns: without them no call can start." | Choose Trunk and Numbering in Other settings |
| "Select which phone number to dial for VoiceAI campaigns." | Choose Phone number to use |
| "Enter at least one time slot for VoiceAI campaigns." | Add at least one slot with + Add time slot |
| "VoiceAI campaigns are not enabled for this account." | Ask Thelgo support to enable the type |
If the account has no phone system
Without a phone system connected, the Other settings box does not appear and the Bot menu has nothing to read: the campaign is saved with only a valid Max simultaneous calls, but it cannot call until the account has a phone system.
Email and SMS templates the bot can send¶
In the Modules and operators step (see Modules and operators) the Preset Email module and Preset SMS module work as in the other campaigns: you turn them on and tick the templates you want to make available. In a VoiceAI campaign, under the list of ticked templates, a menu also appears to choose the one the bot uses:
| Field | Appears when | Options |
|---|---|---|
| Email template sent by the bot | The Preset Email module is on and at least one template is ticked | One of the ticked templates, or None (the bot will not be able to send) |
| SMS template sent by the bot | The Preset SMS module is on and at least one template is ticked | One of the ticked templates, or None (the bot will not be able to send) |
The bot has one template per channel: it does not choose among several templates. If you untick the template chosen for the bot, or turn the module off, the bot's choice is reset and the bot will no longer be able to send on that channel. Under Enabled operators there is the note about calls transferred by the bot.
Do not use the operator placeholders in the bot's templates
When the bot sends, there is no operator: the placeholders {{Operatore.Nome}}, {{Operatore.Cognome}}, {{Operatore.Username}} and {{Operatore.Email}} stay written as they are. The contact's data work instead and, if the bot scheduled an appointment in the same call, so do the appointment's and the agent's data ({{Agente.…}}, {{Appuntamento.…}}). If the template contains these data but the call has no scheduled appointment (or the agent is missing), Thelgo does not send the message and tells the bot, which can schedule the appointment and try again: the time written is that of the account's time zone.
Enabled operators and calls passed by the bot¶
In VoiceAI campaigns too, the Modules and operators step has the Enabled operators list, with the note "For VoiceAI campaigns, these are the operators who can receive and work the calls transferred by the bot." An operator who is not enabled for the campaign cannot take over the call passed by the bot ("You are not assigned to this campaign."). What the operator sees: Calls passed by the bot.
What the bot does during the call¶
The bot communicates with Thelgo through four tools. What it says to the contact and when it uses them depends on how the bot was written in the phone system; Thelgo only answers its tools with the rules below.
Proposing the agents' free times¶
The bot can ask Thelgo for the agents' availability, from a certain date onwards (by default from now). For there to be times to propose:
- the campaign's Agenda Management module must be active, otherwise the bot receives "L'agenda non è attiva per questa campagna: non si possono fissare appuntamenti." (The calendar is not active for this campaign: appointments cannot be scheduled.);
- there must be enabled agents in the campaign who can receive that contact, with the same rules as Enabled agents (an agent with Associate contacts by database field appears only if the contact matches all fields); otherwise the bot receives "Nessun agente è abilitato a fissare appuntamenti per questo nominativo." (No agent is enabled to schedule appointments for this contact.).
The proposed times follow the Working hours in General settings (days and hours), with intervals as long as the campaign's Average appointment duration (minutes) (30 minutes if not set), starting from the beginning of the working hours of each day. For each agent at most 10 times are proposed in the following 15 days or so; times already taken by other appointments and by the commitments of the agent's external calendar (read for a few seconds at most) are excluded. If there is no free time the bot receives "Nessuna disponibilità nei prossimi 15 giorni a partire dalla data indicata." (No availability in the next 15 days from the indicated date.)
Recording the outcome (with an optional appointment)¶
The bot records the outcome with the same logic as an operator, using one of these outcomes:
| Outcome | Effect |
|---|---|
| Positive | As for an operator. If the campaign has Appointment required for Positive Outcome, an appointment is also needed ("Scheduling an appointment is required for a Positive outcome.") |
| Negative | Final outcome |
| Not authorized | The contact asks not to be called again: they are blocked in all campaigns, as for an operator (see Outcomes and callbacks) |
| Call back | The bot can indicate when to call back. If it does not indicate a date and time, or the date has already passed, the callback is set after a random wait between Minimum wait hours and Maximum wait hours of Busy / no answer. The callback is always Public: anyone working the campaign can take it over, because the bot is not an operator to assign it to |
| Busy / No answer | As for an operator: the contact goes back in the queue after the expected wait, up to the maximum number of attempts |
| Custom outcomes | If active in General settings |
The bot cannot use the Quality Check outcomes. Together with the outcome the bot can indicate the notes and, to schedule an appointment, the time (which must be in the future), the agent and the appointment's notes. If it does not indicate the agent, Thelgo chooses the first enabled agent who is free at that time; if nobody is free the bot receives "Nessun agente è libero nell'orario indicato: proporre un altro orario." (No agent is free at the indicated time: propose another time.) If the bot repeats the same notification, the appointment created the first time is replaced, not duplicated.
How outcomes and appointments appear¶
The outcome (and the appointment) are recorded by the "VoiceAI" system user, which in lists and reports appears as VoiceAI (system). It is not a person nor a deleted user: it is the automatic actor that represents the bot (like Public API for the APIs). You see it, for example:
- in the Operator column of the Calls report and as the operator of appointments in the Calendar;
- in the Predictive/Voice AI report, where the call appears as Handled by the bot.
Sending an email or an SMS¶
- Email: the bot sends the contact the Email template sent by the bot to the address the contact gave it. The Preset Email module must be on and the chosen template must still be among those enabled and have an SMTP configuration. The address used becomes the contact's reference address, as for sending by an operator.
- SMS: the bot sends the SMS template sent by the bot to the number it indicates or, if it does not indicate one, to the dialed number. The Preset SMS module must be on and the template's sender alias must be Verified (see SMS).
Neither the email nor the SMS is sent to an anonymized contact. The sends appear as made by the VoiceAI system user. The bot receives a readable error message in reply when something is missing (for example "Nessun template email è configurato per il bot di questa campagna." (No email template is configured for this campaign's bot.) or "L'alias mittente del template SMS del bot non è ancora stato verificato." (The sender alias of the bot's SMS template has not been verified yet.)): if the bot "says it cannot send", check the template choice and the campaign's modules.
After the call: reports¶
The bot's calls appear in the Predictive/Voice AI report with two dedicated categories:
- Handled by the bot: the number answered and the bot recorded an outcome, without an operator stepping in;
- No outcome from the bot: the number answered but the call ended without the bot recording an outcome.
The end day is included
The last day of a campaign with an end date is included in automatic calls, both Predictive and VoiceAI: the engine calls until the end of that day (within the time slots).
What the operator sees¶
VoiceAI campaigns are not worked like the others: in the Your campaigns list the operator sees them greyed out with VoiceAI · coming soon and cannot use Access. The operator steps in only when the bot passes them a call: see Calls passed by the bot.