IVR examples

We've prepared for you several IVR examples covering standard IVR trees.

Note that links to files in play commands are not valid and serve just as examples. Real links will be automatically generated once you'll add and insert your own recordings.

Basic example

online:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=connect-first-available-agent.mp3
  - ring
queue:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=next-in-queue.mp3
offline:   
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=we-are-currently-not-available-check-website.mp3
  - voicemail

In the example above, when nobody is online to take a call, the offline announcement we-are-currently-not-available-check-website.mp3 is played, then the voicemail is recorded.
When agents are online, connect-first-available-agent.mp3 is played and the call will ring to the first available agent. If all agents are occupied, the call is placed in the queue and the next-in-queue.mp3 in queue music is played.

Advanced example

start:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=connect-first-available-agent.mp3
  - choice:
      1:
        name: Sales department
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-one-for-sales.mp3
        do:
          - transfer:
              to: salesDepartmentID
              if:
                online:
                  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=connect-first-available-agent.mp3
                  - ring
                offline:
                  - goto: voicemail
      2:
        name: Technical department
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-two-for-technical-support.mp3
        do:
          - transfer:
              to: techDepID
              if:
                online:
                  - ring
                offline:
                  - goto: offline
      3:
        name: Request calback
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press_2_to_request_callback.mp3
        do:
          - callback
voicemail:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=leave-a-voicemail.mp3
  - voicemail
offline:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=we-are-currently-not-available-check-website.mp3
queue:   
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=next-in-queue.mp3
  - choice:
      0:
        name: Wait
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-zero-to-wait-in-queue.mp3
        goto: queue
      1:
        name: Leave voicemail
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-one-to-leave-a-voicemail.mp3
        goto: voicemail

IVR starts in the start section:
- connect-first-available-agent.mp3 welcome message is played
- press-one-for-sales.mp3 and press-two-for-technical-support.mp3 choice messages are played in a loop (user has to wait for it to be played)
- now the system waits for the user's choice
  - in case of 1, the call is transferred to the Sales department, you must provide correct ID.
   - if there are some agents online in Sales department:
- connect-first-available-agent.mp3 message is played
   - call starts ringing to agents in sales departments
   - if nobody is online in Sales department:
   - the call continues in voicemail section
  - in case of 2, the call is transferred to Technical department
   - if there are some agents online in Technical department:
   - call starts ringing to agents in the tech department
   - if nobody is online in Sales department:
   - the call continues in offline section
  - in case of 3, the call is hung up and transferred to the calls queue where it will wait for an available agent to pick up. Read more about callback usage here.

Offline section plays we-are-currently-not-available-check-website.mp3 message.

Voicemail section plays press-one-to-leave-a-voicemail.mp3 and lets user to record voicemail

If the caller is placed in the queue, the queue music will start to play. After the music is finished, the user is given the choice to continue waiting or leave a voicemail.

Note: There are two ways how to write choice command. One can be seen in start section and second in queue section. You can choose one that is more convenient for you.

Dynamic IVR example

start:
  - fetch:
      url: https://my.dynamic.script
      onError: offline
      params:
        from: {$from_number}
        to: {$to_number}
        ticket: {$conv_code}
offline:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=leave-a-voicemail.mp3
queue:   
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=next-in-queue.mp3

In case you want to generate IVR script dynamically (e.g. based on who is calling) you can use fetch command.
IVR starts in the start section:
- as a first and only step, it fetches IVR from URL https://mydomain.com/scripts/ivr and continues at the start section of this fetched IVR.

You can pass multiple parameters to the script. And ivrs parameter is added automatically. It is list of IVR names from the main script so you can use them in goto commands (in this case it will be: start, offline, queue)

Lets say that our script returns following IVR:

start:
  - play: https://hello.john
  - ring

Your script detected that you know the caller number, so you generate a personalized welcome message. Play it to a customer and then let the call ring to agents.

The fetch command should return plain text reply with correct IVR script, with correct formatting, indents, spaces and so on. Alternatively you can even return a YAML object/file and set the mimetype to ‘application/yaml’.

Note: If your script does not generate valid IVR, a call will hang up.

DTMF input example

start:
  - play: https://enter.your.dtmf.input.and.press.#.to.confirm
  - dtmf:
      url: https://my.dynamic.script
      onError: offline
      params:
        ticket: {$conv_code}
        value: DTMF_VALUE
offline:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=we-are-currently-not-available-check-website.mp3
queue:   
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=next-in-queue.mp3

In case you want to get some input from caller, you can use dtmf command. It waits for the user DTMF input ended by # sign.
When finished, it passes the result to the dynamic ivr script (see section above). DTMF_VALUE placeholder in params will be replaced with actual dtmf input.

Your server should return a dynamic IVR script which is basically the same as general IVR script, but external server can build it based on some logic.
"onError" is called when a request to specified script URL fails or server returns a script that is not valid.

Tips and tricks

If you don't want the customer to press anything to "wait in queue" and press 1 to go to voicemail then you can write the queue section like this:

queue:   
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=next_in_queue.mp3
  - choice:
      0:
        name: Hidden option with music file
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=queue_music.mp3
        goto: queue
      1:
        name: Leave voicemail
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press_one_to_leave_a_voicemail.mp3
        goto: voicemail

When a customer calls and ends up in queue the next_in_queue.mp3 will be played and then the choices will loop, so queue_music.mp3 is played, then the press_one_to_leave_a_voicemail.mp3 is played, then again queue_music.mp3, then again press_one_to_leave_a_voicemail.mp3 and so on. Since you never tell the customer to press anything else than 1, the customer will simply stay on the line until he either presses 1 to leave a voicemail or until there is a free agent available to receive his call.

If you want to offer IVR in multiple languages, eg. English and German, it can look like this example:

start:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=connect-first-available-agent.mp3
  - choice:
      1:
        name: English
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-one-for-english-langauge.mp3
        goto: english
      2:
        name: German
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-two-for-german-language.mp3
        goto: german
english:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=connect-first-available-agent.mp3
  - choice:
      1:
        name: Sales department
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-one-for-sales.mp3
        do:
          - transfer:
              to: SalesDepartmentID
              if:
                online:
                  - ring
                offline:
                  - goto: voicemail
      2:
        name: Technical department
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-two-for-technical-support.mp3
        do:
          - transfer:
              to: TechnicalDepartmentID
              if:
                online:
                  - ring
                offline:
                  - goto: offline
german:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=connect-first-available-agent.mp3
  - choice:
      1:
        name: German Sales department
        play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-one-for-sales.mp3
        do:
          - transfer:
              to: germanSalesDepartmentID
              if:
                online:
                  - ring
                offline:
                  - goto: germanvoicemail
                queue:
                  - goto: germanqueue
      2:
        name: German Technical department
        play:  https://mycompany.ladesk.com/scripts/file.php?view=Y&file=press-two-for-technical-support.mp3
        do:
          - transfer:
              to: germanTechnicalDepartmentID
              if:
                online:
                  - ring
                offline:
                  - goto: germanoffline
                queue:
                  - goto: germanqueue
voicemail:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=leave-a-voicemail.mp3
  - voicemail
offline:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=we-are-currently-not-available-check-website.mp3
queue:   
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=next-in-queue.mp3
germanvoicemail:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=leave-a-voicemail-german-language.mp3
  - voicemail
germanoffline:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=we-are-currently-not-available-check-website-german-language.mp3
germanqueue:
  - play: https://mycompany.ladesk.com/scripts/file.php?view=Y&file=next-in-queue-german-language.mp3