</Gather>

<Gather> Tag Overview

The <Gather> tag in Opentact allows you to create Interactive Voice Response (IVR) systems, enabling you to interact with callers through voice prompts and gather responses using Dual-Tone Multi-Frequency (DTMF) codes. Here's an example of how to use <Gather> to create a multi-level IVR:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Thank you for calling Opentact. Please hold.</Say>

    <Say>Now please enter a 1 to call the support team, 2 to call the tech team, or 0 to enter a private menu</Say>
    <Gather dtmf_length="1" dtmf_stop="#">

        <!-- SUPPORT TEAM -->
        <DTMF value="1">
            <Say>Switching the call to the support team</Say>
            <Dial>
                <To>[e-mail]</To>
                <To>[e-mail]</To>
                <To>[e-mail]</To>
                <Error>
                    <Say>Sorry, our support team is busy right now, please call again later</Say>
                    <Hangup/>
                </Error>
            </Dial>
        </DTMF>

        <!-- TECH TEAM -->
        <DTMF value="2">
            <Say>Switching the call to the tech team</Say>
            <Dial>
                <To>12223334455</To>
                <To>12223334456</To>
                <To>12223334457</To>
                <Error>
                    <Say>Sorry, our tech team is busy right now, please call again later</Say>
                    <Hangup/>
                </Error>
            </Dial>
        </DTMF>

        <!-- PRIVATE MENU -->
        <DTMF value="0">
            <Say text="Now please enter a 4-digit code or # to stop entering a pin"/>
            <Gather length="4" dtmf_stop="#" url="http://private.domain.com/rest/private_menu?token=TOKEN">
                <!-- call URL will be transformed to: http://private.domain.com/rest/private_menu?token=TOKEN&dtmf=<DTMF>&from=<FROM>&tn=<TO>&state=live&sca=<SIP CONTROL APP UUID>&call=<CALL UUID> -->

                <!-- This block would be called if something goes wrong with a remote endpoint response -->
                <Error>
                    <Say>Oops, something is going wrong, please call again later</Say>
                    <Hangup/>
                </Error>
            </Gather>
        </DTMF>

        <!-- DEFAULT BEHAVIOR -->
        <Default>
            <Say>No DTMF code entered. Please call again</Say>
        </Default>

        <Error>
            <Say>Wrong input menu code entered. Please call again</Say>
        </Error>

    </Gather>

    <Say>Thank you for using our service, have a nice day!</Say>
    <Hangup />
</Response>

<Gather> Command Hints:

• , and <Error> blocks are allowed to contain a child <Gather> command.

• The length parameter specifies the number of DTMF codes to wait for.

• The dtmf_stop parameter defines which DTMF code stops listening for additional codes.

• Accepted values for dtmf_stop include: 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, *, #, +.

• Blocks start executing after entering the specified number of DTMF codes or receiving the dtmf_stop code.

Examples:

1. Basic Usage with <DTMF>:

• The example provides a simple use of <Gather> with a single <DTMF> block.

• When the caller enters DTMF code "1," it responds with a "Hello world" message.

<Gather>
  <DTMF value="1">
    <Say text="Hello world"/>
  </DTMF>
</Gather>

2. Gather with <Say> and <Play>:

• This example combines <Say> and <Play> within <Gather> to create a dynamic interaction.

• It prompts the caller to enter "1" for a man or "2" for a woman, playing background music.

• Based on the entered DTMF code, it responds with a personalized greeting or an error message.

<Gather>
  <Say loop="3" text="Enter 1 for man, 2 for woman"/>
  <Play loop="10" url="http://google.com/music.mp3"/>

  <DTMF value="1">
    <Say text="Hello man"/>
  </DTMF>

  <DTMF value="2">
    <Say text="Hello woman"/>
  </DTMF>

  <Default>
    <Say>Wrong DTMF entered</Say>
  </Default>

  <Error>
    <Say>DTMF not found</Say>
  </Error>
</Gather>

3. Gather with Dynamic Length and Stop on DTMF Code:

• This example sets the dtmf_length to 10, expecting a 10-digit PIN.

• The caller is asked to enter a PIN, and they can stop entering at any time by pressing "#."

• If a PIN is entered, it welcomes the caller; otherwise, it prompts an error and hangs up.

<Gather dtmf_length="10" dtmf_stop="#">
  <Say text="Enter pin. To stop entering, enter #"/>
  <Default>
    <Say>Pin code entered, welcome</Say>
  </Default>
  <Error>
    <Say>Pin code not entered</Say>
    <Hangup/>
  </Error>
</Gather>

4. Gather with Nested Options and External Endpoint:

• The example presents a more complex menu with nested options for a support system.

• Callers can enter "1" for tech support or "2" for payment support.

• Depending on the chosen option, it further prompts the caller with specific choices.

• It provides error messages if the selected support team is busy or if an incorrect code is entered.

<Gather dtmf_length="10" dtmf_stop="#">
  <Say text="Enter 1 for support team, 2 for HR department"/>
  <DTMF value="1">
    <Say text="Enter 1 for tech support, 2 for payment support"/>
    <Gather>
      <DTMF value="1">
        <Dial>
          <To to="[e-mail]"/>
          <To to="[e-mail]"/>
          <To to="[e-mail]"/>
        </Dial>
      </DTMF>
      <DTMF value="2">
        <Dial>
          <To to="[e-mail]"/>
          <To to="[e-mail]"/>
          <To to="[e-mail]"/>
        </Dial>
      </DTMF>
      <Error>
        <Say>All our support operators are busy, please call again later</Say>
        <Hangup/>
      </Error>
    </Gather>
  </DTMF>
  <DTMF value="2">
    <Dial to="[e-mail]">
      <Error>
        <Say>HR department is busy right now, please call again later</Say>
        <Hangup/>
      </Error>
    </Dial>
  </DTMF>
  <Error>
    <Say>Wrong DTMF code entered, please call again later</Say>
    <Hangup/>
  </Error>
</Gather>

Call External Endpoint with Entered DTMF Code:

If a URL is provided, all blocks except <Error> will be ignored. The <Gather> URL is updated with parameters such as dtmf, call, sca, state, from, tn.

• This example introduces an external endpoint through the url attribute in <Gather>.

• It instructs the caller to enter a 4-digit PIN, and the entered code is sent to an external endpoint.

• If the PIN is successfully entered, it continues with a looped background music; otherwise, it prompts an error and hangs up.

<Say text="Enter pin. Entering enter # to stop entering the pin"/>
<Gather dtmf_length="4" dtmf_stop="#" url="http://domain.com/endpoint?token=TOKEN">
  <Play loop="10" url="https://google.com/media.mp3"/>
  <Error>
    <Say>Pin code not entered</Say>
    <Hangup/>
  </Error>
</Gather>

The <Gather> tag is a powerful tool for creating dynamic and interactive voice response systems in Opentact. It enables you to engage with callers, collect input through DTMF codes, and execute specific actions based on the received responses.