Automate your IVR Menus with a Script-based Digital Receptionist

[KyriakosP]

The Digital Receptionist function includes a little functionality gem to help you add basic automation and integration capabilities to your 3CX PBX. Provided that you have some script coding skills, you can use the \"Launch Script\" option for your IVR to process customer input and deliver the result back to 3CX for further action. The \"Launch Scr...

Continue reading the Original Blog Post.

 

[surenr]

hi all,
is there any documentation available, i checked this also https://www.3cx.com/docs/script-based-ivrs/ .
so to find out the parameters passed by 3cx , i have to var dump argument in shell and see right ?
Thanks.

 

[KyriakosP]

Hi @surenr,

The parameters passed by the IVR to the script are documented here.

It's a good practise to have the script dump the parameters in a log file to verify, as described in the blog post.

 

[triwardhana]

Hello,
Is that possible creating script base IVR as flow below :

user input (ticket_number) -> pass to script -> parsing tiket number to url http://example.com/search?phoneNumber=%ticket_number%

 

[StefanW]

IVRs in this topic just make a small decision to accept a call or where to route the call to. Its a simple form of the CFD which already covers many use cases customers have.

You may send a wget get to the page but what will be the return?
It will not be sent to the user who will pick up the call in the end. For this CRM integration would be needed. Depends on what you need and what result is expected in your workflow.

 

[saint_]

I did a very simple script on the latest V16.0.4.461 in /DEV/test.sh

root@3cx:/DEV> ls -la
total 16
drwxr-xr-x 2 root root 4096 Nov 18 21:09 .
drwxr-xr-x 24 root root 4096 Nov 18 20:50 ..
-rw-r--r-- 1 root root 735 Nov 18 20:51 _parameters.txt
-rw-r--r-- 1 phonesystem phonesystem 0 Nov 18 21:09 test.log
-rwxr-xr-x 1 phonesystem phonesystem 108 Nov 18 21:09 test.sh


with the script content:
root@3cx:/DEV> more test.sh
#!/bin/bash
function log() {
echo date "+%Y.%m.%d %H:%M:%S" "- $1" >> /DEV/test.log
}
log "Received $*"

My digital receptionist options are:
Type: Launch script
Prompt: test.wav

• Collect user input and pass it to the script
• Expect digit length: 1
• Playback user input and request confirmation

Full path to the script: /DEV/test.sh

• Exit code: 0 End call
• Exit code: 1 Call by Name

When I call this IVR, I hear the prompt test.wav , and if I enter 0 or 1 I hear "File not found" repeated twice, then the DTMF entered, then it hangs up on me.

From the log file, I believe the Playback user input and request confirmation wav files are not installed by default:

18/11/2019 21:24:23.281 [000019cd] 15 DTMF buffer: + 1
18/11/2019 21:24:23.281 [000019cd] Unknown prompt id: YOU_HAVE_ENTERED
18/11/2019 21:24:23.281 [000019cd] 15 PLAY id = 2 : #YOU_HAVE_ENTERED = /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/Sets/8210986B-9412-497f-AD77-3A554F4A9BDB/file_not_found.wav
18/11/2019 21:24:23.281 [000019cd] 15 PLAY id = 3 : #NUM_1 = /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/Sets/8210986B-9412-497f-AD77-3A554F4A9BDB/numbers/1.wav
18/11/2019 21:24:23.281 [000019cd] Unknown prompt id: PRESS_POUND_TO_CONFIRM
18/11/2019 21:24:23.281 [000019cd] 15 PLAY id = 4 : #PRESS_POUND_TO_CONFIRM = /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/Sets/8210986B-9412-497f-AD77-3A554F4A9BDB/file_not_found.wav
18/11/2019 21:24:28.090 [000019cd] DR Added session from timer, total 1
18/11/2019 21:24:33.426 [000019c7] Child process has exited with code 0
18/11/2019 21:24:33.426 [000019c7] 15 Process exit code 0
18/11/2019 21:24:33.426 [000019cd] 15 Processing script exit code 0
18/11/2019 21:24:33.426 [000019cd] 15 PLAY id = 5 : #BYE = /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/Sets/8210986B-9412-497f-AD77-3A554F4A9BDB/thankyou_goodbye.wav
18/11/2019 21:24:35.748 [000019c7] DR Session 15 has been ended by PBX, total 0
18/11/2019 21:24:35.748 [000019c7] 15 DELETE





If I remove the confirmation option, I have no luck in the IVR following the script (it says "Thank you, good bye" then hangs up)
18/11/2019 21:27:42.861 [000019c7] 18 NEW IVR : 100 -> 801 (801)
18/11/2019 21:27:42.861 [000019c7] DR Added new session 18, total 1
18/11/2019 21:27:42.861 [000019cd] 18 PLAY id = 1 : test.wav = /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/test.wav

18/11/2019 21:27:47.468 [000019c6] /home/repomaster/workspace/TrunkBuild/Sources/Projects/Common/VoIPFileEngine/RawFile.cpp(23) IRawFileBuffer:refetch : error = 0, Success
18/11/2019 21:27:47.688 [000019cd] DR Added session from timer, total 1

18/11/2019 21:27:49.539 [000019cd] 18 Locked DTMF type to RFC2833
18/11/2019 21:27:49.539 [000019cd] 18 DTMF buffer: + 1
18/11/2019 21:27:49.777 [000019c7] Child process has exited with code 0
18/11/2019 21:27:49.777 [000019c7] 18 Process exit code 0
18/11/2019 21:27:49.777 [000019cd] 18 Processing script exit code 0
18/11/2019 21:27:49.777 [000019cd] 18 PLAY id = 2 : #BYE = /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/Sets/8210986B-9412-497f-AD77-3A554F4A9BDB/thankyou_goodbye.wav
18/11/2019 21:27:52.108 [000019c7] DR Session 18 has been ended by PBX, total 0
18/11/2019 21:27:52.108 [000019c7] 18 DELETE

 

[saint_]

Also, from what I understand, it is only possible for 3CX to call a bash/python script, but not interact with it. What I mean by that is 3CX calls the script. Script process data. Depending on data, script tells 3CX do send the call here or there..?

 

[ivank]

18/11/2019 21:24:23.281 [000019cd] Unknown prompt id: YOU_HAVE_ENTERED
18/11/2019 21:24:23.281 [000019cd] 15 PLAY id = 2 : #YOU_HAVE_ENTERED = /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/Sets/8210986B-9412-497f-AD77-3A554F4A9BDB/file_not_found.wav

Hi!
This suggests that your prompt set 8210986B-9412-497f-AD77-3A554F4A9BDB is not valid (somehow damaged) as it is missing some standard prompts. Try fixing this first before using it in scripts.

The easiest way to do so would be:

• Rename /var/lib/3cxpbx/Instance1/Data/Ivr/Prompts/Sets/8210986B-9412-497f-AD77-3A554F4A9BDB/SetInfo.xml to SetInfo.xml.bak
• In Management Console go to Settings > System Prompts.
• You should see an update available for English prompt set. Install it.

 

[ivank]

Also, from what I understand, it is only possible for 3CX to call a bash/python script, but not interact with it. What I mean by that is 3CX calls the script. Script process data. Depending on data, script tells 3CX do send the call here or there..?

This is correct. The exit code of the script determines the action taken in IVR.

 

[saint_]

Hi!

The fix for the prompt worked, thank you.
On the other hand, my option "1 / Call by name" does not work.
After selecting it, it says "Thank you, good bye". But that's not the point of this thread.
Could you give me a scenario where one would call an external script, without interacting with it?
The other system we sell, and trying to switch away from, actually allows us to interact with the scripting language, where one can call a script, and the call is waiting for an answer from the script before moving on.. Typically black list calls for example where a script is called, ID is checked against a database, and call is handled depending on the result of the scripts.

 

[ivank]

On the other hand, my option "1 / Call by name" does not work.
After selecting it, it says "Thank you, good bye". But that's not the point of this thread.

The problem with your script is that it always returns 0 (and thus goes to End Call). You should return different codes based on decisions the script makes and have these codes assigned for handling by the IVR.

The other system we sell, and trying to switch away from, actually allows us to interact with the scripting language, where one can call a script, and the call is waiting for an answer from the script before moving on.. Typically black list calls for example where a script is called, ID is checked against a database, and call is handled depending on the result of the scripts.

This can be done in 3CX. I am attaching a sample .bat for Windows which calls the python which in turn checks the incoming route against a file with numbers and returns different codes. The comments should also help.
One can quite easily adapt the script for their needs.

 

[saint_]

My apologies, I just understood that you could return an exit code and the IVR could act depending on it. I though this was NOT possible.

The one blog post says:

1. “Exit Code” - with accepted values [0-100] you can add up to 101 unique numeric exit codes for your script-based IVR, with respective actions and destinations. When the script ends, it returns an appropriate exit code to the IVR, which in turn uses it for routing the call.

Is there any documentation on how to handle exit codes?
The blog (unless if I missed it) does not show how to handle them.

Thank you!

 

[ivank]

Is there any documentation on how to handle exit codes?
The blog (unless if I missed it) does not show how to handle them.

Please reread the latest article, at step 5, e & f it is shown how to consume the code returned by script from the invoking IVR.

 

[saint_]

I see where my mistake was. I am so used to use DTMF Input that I did not read the line saying "Enter EXIT Code" (and not DTMF). Therefore, if I understand correctly:

• Lunch script
• Get whatever 3 information sent by the IVR in the script
• Return an exit code which it matched in the IVR
• Move on from there (call another script from another IVR number, or execute a 3CX Action (terminate call, transfer, etc..)

Right?

Thank you!

 

[saint_]

One last question.. Does this work with Standard since it's part of the Digital receptionist, or do we need Pro / Enterprise ?

 

[NateDoc]

Also, any chance we can get the IVR to accept pound and star with launch script? Having something other than a call flow that can read those in a menu would be amazing.

 

[KyriakosP]

Hi @NateDoc,

You can use the * character for caller input in the script, but not the # character as it is used for confirming the DTMF input.

 

[NateDoc]

Hi Kyriakos,

Thanks for that feedback. Since the "playback user input and request confirmation" is optional, is it possible to allow for pound if it's not checked? We really need more options that allow for all DTMF without restriction as it's frequently problematic to migrate a client's IVR without having them to re-record their custom greetings since 'pound' is used often as an option in their IVR. Thanks!

 

[KyriakosP]

Ηι @NateDoc,

I understand your point, but currently the '#' DTMF code handling is hard-coded. For now, you can examine using a CFD call flow app to extend your input options. Also, you can propose your functionality suggestion, in our "Ideas" forum for our development team to consider:
https://www.3cx.com/community/forums/3cx-ideas/

 

[phild-cxcxcx]

Hi Kyriakos,

Using 3cx V18 "hosted by 3cx" 1 year trial 4sc..

I'm a latecomer to this discussion, and have a question about
IVR scripting..I wanted to try your sample bash script..

I created a file with your code, and placed it in a directory off my home folder..
e.g. /home/phild/IVR-scripts/myscript.sh

I went into the MC - Digital receptionists - and chose "launch script" according to your
instructions. I entered the full path to my script file where it is asked for,
and clicked "OK". An error message appeared saying "file cannot be found"

? Do I have to change the owner/permissions on the script before 3cx recognizes it?

Thanks, I hope you can still get this message, given that you are not with 3cx currently..

Phil