ConneXML¶

Class 5 ConneXML

Introduction¶

What's ConneXML?¶

ConneXML is a set of instructions you can use to tell Class 5 Applications what to do when you receive an incoming call.

When the customers receive an External or Internal Call, it hits the DID section.

In the DID section you can allocate the calls at different places. Click on Call Destination:

1.URI: Its points to a client's server. You can send the call either to the Destination DID or an IP address.

2.External: Allows you to re-direct the call out back again to the network.

3.Internal: Allows you to route the call internally like a SIP user or a Queue.

Later, the Class5 Applications makes an HTTP request to the URL endpoint you configured for that number. The endpoint will contain instructions telling ConnexML what to do next with the call.

How does ConneXML work?¶

In a general call scenario, the call goes from the Carrier to ConnexCS Class 4 to the Customer.

Now let's understand how ConneXML can control calls.

In this case, the call goes from Carrier to ConnexCS Class 4 to ConnexCS Class 5.

The Class 5 initially doesn't pass the call to the Customer.

The call gets terminated here and instead Class 4 sends a request to the Routing Engine via HTTP and then the HTTP replies back to the Class 4 system.

Class 4 passes the call to Class 5. Then Class 5 asks the Routing Engine how to handle the call.

Further, the Routing Engine questions the same thing to the Customer on how to handle the call. The Customer can ask to collect some information or play a music or something else via a an HTTP Request. The same request is sent to the Class 5 from the Routing Engine. The Class 5 then replies to the requests of the customer.

Another scenario might be when the Routing Engine might talk to the ConnexCS Applications like ScriptForge, ConneXML, Call Flow Builder. In case it hits the ConneXML application, ConneXML can as to direct it (Routing Engine) to a 3^rd party customer and that customer can access the 3^rd party data hit back to ConneXML, then the Routing Engine followed by Class 5 Application and lastly the Customer.

ConneXML uses the standard .xml markup language.

.

How to reach and code the ConneXML Editor?¶

To get ConneXML working you will need to:

1. Go to Class 5 Apps.
2. On the top right click on blue + sign.
3. Add new and make sure you choose App Type = ConneXML. The destination can be alpha-numeric and contains an endpoint, for example "customer_a_connexml".

4.After saving the above information. Click on Go to App to enter the ConneXML editor. Write your code and click Save.

5.If you initially want this to hit a customers server same as before, you can use something like this in the XML field.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Redirect method="POST">https://yourdomain.com/yourscript.php</Redirect>
</Response>

6.Point the DID to internal and then the name of the endpoint that you created (for example customer_a_connexml)

7.Select Code Snippet: Enables you to choose pre-made ConneXML codes for faster and more convenient use. You choose from multiple available options.

ConneXML Components¶

In ConneXML, the XML components can be divided into 4 categories:

1. Response: Its the root element tag that defines the main body of the ConneXML document. All the verbs must be contained inside the Response body.
2. Verbs: Just like in english language, Verbs are action words which tells what action to perform on the received call.
3. Attributes: These are the methods for each Verb. Verbs may have optional XML attributes that override the flow of execution, allowing you customize the verb behavior.
4. Nouns: As the name suggests, a noun can described on which the action has to be performed. For example, it can be a phone number on which a Dial action has to be performed.

<Response> <!--Body of the code>
    <!-- Here, Play and Dial are the Verbs -->
    <Play loop="2">http://www.music.com/fun.wav</Play>
    <Dial>
        <!-- Number is a Dial Noun -->
        <Number>189765441</Number>
    </Dial>
</Response>

In the next section, we shall discuss the various Verbs,Attributes and Nouns.

Verbs, Attributes and Nouns¶

Hangup¶

The current call is terminated with the Hangup verb.

It has no attributes and doesn't include any nouns.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Hangup/>
</Response>

Pause¶

The Pause verb waits silently for a given amount of time, or by default, 5 seconds. Pause doesn't use any nouns, and a self-closing tag is mandatory.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>I will pause default time starting now!</Say>
    <Pause/>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pause length="10"/>
    <Say>I just paused 10 seconds</Say>
</Response>

Say¶

Text to speech is enabled for any application by using the Say verb, which speaks the provided text back to the caller.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>This is better  text to speech.</Say>
</Response>

Reject¶

This verb rejects the current call.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Reject/>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Reject reason="busy"/>
</Response>

Play¶

The Play verb allows you to play back to the caller an MP3 or WAV audio file.

You can use Play as a verb  standalone or as a noun nested inside Gather to play audio while you wait for DTMF tones.

The value of Play can either be:

1. Local files: You can play from default built-in messages. List of default sounds to follow.
2. Remote HTTP: You can play from a remote datasource, the file can be anywhere on the internet; starts with HTTP.
3. User Files: You can play the audio that you have uploaded with ConnexCS. Login to your account Management File Upload.

Redirect¶

The current call gets transferred to another ConnexCS Class 5 application using the Redirect verb.

Redirect doesn't allow for the nesting of nouns.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Redirect>http://yourdomain.com/connex/test.xml</Redirect>
</Response>

<Response>
    <Redirect method="GET">https://yourdomain.com/yourscript.php</Redirect>
</Response>

Gather¶

During a call, the Gather verb accumulates DTMF tones.

You can create an interactive IVR with text-to-speech by nesting Say within Gather.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Gather actionOnEmptyResult="false" action="https://yourdomain.com/youwebserver.php" method="GET" numDigits="6" finishOnKey="*" timeout="120">
        <Play>https://samplelib.com/lib/preview/wav/sample-12s.wav</Play>
    </Gather>
    <Say>Sorry.The entered number in invalid</Say>
</Response>

Enqueue¶

The current call is enqueued in a call queue using the Enqueue verb.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Enqueue>1000</Enqueue>
</Response>

Dial¶

An existing call is transferred to a different destination using the Dial verb.

Dial will end this call if:

• The called person doesn't answer.
• The number is invalid.
• ConnexCS receives a busy signal.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>123456</Dial>
</Response>

Dynamic Dial¶

Dynamically dial a phone number based on a substring of a variable named Extension.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Number>>{{ substring Extension 5 }}</Number>
    </Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <Number>{{ substring Extension 9 }}</Number>
    </Dial>
</Response>

Press¶

It helps to define on which leg of the call the DTMF will work. For example, dtmf_leg ='a' or dtmf_leg ='b'.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Press dtmf_leg ='b'digit="3" context="A">
        <Transfer>test4</Transfer>
    </Press>
</Response>

Before¶

It initializes variables before executing other commands.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Before><Set name="newHome" value="Adam"/><Set name="headerName" value="Joe"/></Before>
</Response>

Stream¶

Stream is a noun is used in conjunction with either Start or Connect.

When the <Start><Stream> command is used during a call, the call's raw audio stream is streamed to your WebSocket server near real-time.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Start>
        <Stream url="wss://your-websocket-server.com/your-endpoint" />
    </Start>
</Response>

Echo¶

Echo plays back everything that's spoken/played, like voice, audio, DTMF, etc.

It enables loopback on the calling channel.

It's an effective and quicker way to check a customer's audio quality and call path delay.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
   <Echo></Echo>
</Response>

Set¶

Set defines headers to be included in the SIP INVITE and set variables.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Set name="name" value="Adam"/>
    <Set name="{{ x-name }}" value="Water" header="true" />
    <Dial>
        <Number>160</Number>
    </Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Before>
        <Set name="newHome" value="Adam"/>
        <Set name="headerName" value="Joe"/>
    </Before>
    <Set name="name" value="" header="true"/>
    <Set name="{{ x-name }}" value="" header="true" />
    <Say>Hello my name is newHome</Say>
    <Say>Hello my name is headerName</Say>
    <Say>Hello my name is {{ x-name }}</Say>
    <Dial>
        <Number>160</Number>
    </Dial>
</Response>

Adding AI Agents¶

Overview¶

The AI Agent allows integration of AI agents into your call flow using three methods:

• File ID Method: References a pre-configured agent created in the IDE.
• Embedded Instructions Method: Directly embeds instructions for the AI agent within the XML.
• App Script Method: Involves creating an app in the IDE with custom scripts that handles specific functions, such as retrieving information or managing call transfers, combined with XML call flow that invokes the AI agent.

graph TD
    A[AI Agent Integration Methods] --> B[File ID Method]
    A --> C[Embedded Instructions Method]
    A --> D[App Script Method]

    B --> E[References a pre-configured agent created in the IDE]
    C --> F[Embeds instructions for the AI agent within the XML]
    D --> G[Creates an app with custom scripts in the IDE]
    G --> H[Functions like retrieving info or call transfers]
    H --> I[Combined with XML call flow to invoke the AI agent]

How It Works¶

• File ID Method: Uses the agent's file ID from the IDE to engage pre-configured behaviors.
• Embedded Instructions Method: Embeds natural language instructions directly in the XML.
• App Script Method: Uses a custom app built in the IDE with cxLLM to define complex interactions, such as call transfers, and combines this with an AI agent in the XML response.

graph TD
    A[Start Call Flow] --> B[File ID Method]
    A --> C[Embedded Instructions Method]
    A --> D[App Script Method]

    B --> E[Use Agent's File ID from IDE]
    E --> F[Engage Pre-Configured Behaviors]

    C --> G[Embed Natural Language Instructions]
    G --> H[Directly in XML]

    D --> I[Custom App in IDE with cxLLM]
    I --> J[Define Complex Interactions]
    J --> K[Call Transfers and AI Agent in XML Response]

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <LLM-Agent>asst_MTbETp3jyb9tG9eAepFGxgPb</LLM-Agent>
    </Dial>
</Response>

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Dial>
        <LLM-Agent>You are a knowledgeable fitness coach, providing advice on workout routines, nutrition, and healthy habits. Offer personalized guidance based on the user's fitness level, goals, and preferences, and motivate them to stay consistent and make progress toward their objectives.</LLM-Agent>
    </Dial>
</Response>

    const llm = require('cxLLM');
    // Retrieves the current day of the week
    function dayOfWeek() {
        return 'Monday';
    }

    // Transfers the call to a specified person
    function transfer({name}) {
        console.log(`We are going to transfer the call to ${name}`);
        return {action: 'transfer', data: {number: '160'}};
    }

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hi, we are redirecting your call to our revolutionary AI Agent.</Say>
    <Dial>
        <LLM-Agent appId="0506a202-4377-11ef-9324-d05099d1f064">
        You are the friendly and professional receptionist for a company Test Account specializing in revolutionary technology. Begin each conversation by saying 'Hello' and then pausing briefly. Greet callers and provide information, informing them that there are 5 key members in the organization: Jonathan Hulme, Rizwan Syed, Adam Nawaz, Ankit Patel, and Bani Gandhi. Let the caller know that you can transfer them to any of these individuals. However, if none of these names are mentioned, politely inform the caller that you cannot transfer the call and encourage them to continue the conversation. Always be polite, concise, and clear in your responses.
        </LLM-Agent>
    </Dial>
</Response>