Migrating from Plivo to CarrierX

This article will describe how to migrate from Plivo to CarrierX, what difficulties you can meet, and the ways to solve the issues.

The main steps to start working with CarrierX are to create an account and write applications in FlexML, the CarrierX markup language. You can update your existing Plivo XML applications so that they worked with CarrierX.

Migrating Plivo Account to CarrierX

First, you need to register an account with CarrierX. To do that, fill the form at the Contact Us page. Once the account is created, you will get access to the CarrierX portal and API.

You can also read the following quick start articles to learn the basics of work with CarrierX:

Setting Applications URLs

Plivo stores the links to the associated applications in the phone number configuration. In CarrierX, it is possible to set up the applications URLs in two places:

Migrating Applications That Use Client Library

When posting requests from Plivo, users can use the client library provided by Plivo to form these requests.

Requests to and from CarrierX FlexML endpoints do not require to install any additional libraries and can use the standard requests methods, available in various programming languages (e.g., in Python):

Plivo Python Request Example

import plivo

client = plivo.RestClient('PLIVO_AUTH_ID', 'PLIVO_AUTH_TOKEN')

call = client.calls.create(
                        from_='+14151234567',
                        to_='+14157654321',
                        answer_url='https://example.com/path/to/handler',
                        answer_method='GET',
                    )

Corresponding CarrierX Python Syntax

import requests, json

url = 'https://api.carrierx.com/flexml/v1/calls'
headers = {'Content-Type':'application/json'}
payload = {"calling_did":"15017122661", "called_did":"15558675310", "url":"https://example.com/path/to/handler", "method":"POST"}

requests.post(url, auth=('CARRIERX_FLEXML_EP_USER_NAME', 'CARRIERX_FLEXML_EP_PASSWORD'), data=json.dumps(payload), headers=headers)

Migrating Plivo XML Applications to FlexML

Plivo uses Plivo XML, and CarrierX uses FlexML as sets of instructions. You can use these instructions to tell the services what they must do when they receive a call. They both use verbs and nouns as a base for their markup language and have similar syntax. FlexML retains certain compatibility with Plivo XML so that your migration could be easier.

You can use most of the main verbs (as well as the Number noun), which you normally use in Plivo XML, in CarrierX FlexML. They have similar attributes, and you can either use them in FlexML as is, or adapt them changing some of their values. Some of the attributes though are different or missing in FlexML, so you will need to exclude them from your code or replace them with the corresponding ones. Some of the verbs in FlexML have additional attributes, which you can use to expand the application capabilities.

The following sections list the Plivo XML verbs and nouns that are supported in FlexML and provide the FlexML syntax that corresponds to the Plivo XML code which uses the Plivo libraries.

Dial

The Dial verb connects the calling party with the dialed party. Refer to the Plivo XML and FlexML documentation sections for more information on Dial.

You can use the following Plivo XML Dial verb attributes without any changes in FlexML:

The action attribute exist both in FlexML and Plivo XML, but requires fully qualified URL in Plivo XML, while in FlexML you can use both absolute and relative URLs.

The timeLimit and timeout attributes are similar both in FlexML and Plivo XML, they only differ in their default values:

The confirmSound attribute also exist both in FlexML and Plivo XML. In Plivo XML, it must contain the link to another set of instructions written also in Plivo XML markup language. In CarrierX FlexML, this attribute can contain an URL to an audio file.

The sipHeaders attribute is not available in FlexML, but you can set the required SIP headers inside the Number noun and nest it within the Dial verb like this:

<Response>
    <Dial>
        <Number>15162065340?X-CustomHeader1=ABC&amp;X-CustomHeader2=DEF</Number>
    </Dial>
</Response>

The dialMusic attribute in Plivo XML functions similar to ringing in CarrierX FlexML:

All the other attributes present in Plivo XML Dial are currently unsupported in FlexML.

Code Examples

Below is a Python code sample of the PlivoXML Dial verb and a corresponding Python syntax of the FlexML Dial code:

Plivo XML Dial Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.DialElement(action='https://example.com/path/to/handler', method='POST').add(
        plivoxml.NumberElement('15671234567')))
print(response.to_string())

Corresponding FlexML Dial Verb Python Syntax

print('''<Response>
             <Dial action="https://example.com/path/to/handler" method="POST">15671234567</Dial>
         </Response>''')

DTMF

The DTMF verb enters the symbols within its tags. Refer to the Plivo XML and FlexML documentation sections for more information on DTMF.

Currently, the Dtmf verb does not support any attributes in FlexML.

Code Examples

Below is a Python code sample of the Plivo XML DTMF verb and a corresponding Python syntax of the FlexML Dtmf code:

Plivo XML DTMF Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.DTMFElement('1234'))
print(response.to_string())

Corresponding FlexML Dtmf Verb Python Syntax

print('''<Response>
             <Dtmf>1234</Dtmf>
         </Response>''')

GetDigits/ GetInput

The GetDigits/ GetInput verbs collect the digits that a caller enters into the phone keypad. Refer to the Plivo XML GetDigits/ GetInput and FlexML documentation sections for more information on Gather.

You can use the following Plivo XML GetDigits/ GetInput verbs attributes without any changes in FlexML:

All the other attributes present in Plivo XML GetDigits/ GetInput are currently unsupported in FlexML.

Code Examples

Below is a Python code sample of the Plivo XML GetDigits/ GetInput verb and a corresponding Python syntax of the FlexML Gather code:

Plivo XML GetDigits/ GetInput Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.GetDigitsElement(
        action='https://www.foo.com/gather_pin/', method='POST').add(
            plivoxml.SpeakElement(
                'Enter your 4-digit PIN, followed by the hash key')))
response.add(plivoxml.SpeakElement('Input not received.'))
print(response.to_string())

Corresponding FlexML Gather Verb Python Syntax

print('''<Response>
             <Gather action="https://www.foo.com/gather_pin/" method="POST">
                 <Say>
                     Enter your 4-digit PIN, followed by the hash key
                 </Say>
             </Gather>
             <Say>Input not received.</Say>
         </Response>''')

Hangup

The Hangup verb answers the call and then immediately hangs up. Refer to the Plivo XML and FlexML documentation sections for more information on Hangup.

The Hangup verb has no attributes in FlexML.

Code Examples

Below is a Python code sample of the Plivo XML Hangup verb and a corresponding Python syntax of the FlexML Hangup code:

Plivo XML Hangup Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.HangupElement())
print(response.to_string())

Corresponding FlexML Hangup Verb Python Syntax

print('''<Response>
             <Hangup/>
         </Response>''')

If you use the Plivo XML Hangup verb to reject the call rather than to simply hang up, you can substitute it with the FlexML Reject verb. In this case, you should use the reject attribute to specify the reject reason:

Plivo XML Hangup Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.HangupElement(reason='rejected'))
print(response.to_string())

Corresponding FlexML Reject Verb Python Syntax

print('''<Response>
             <Reject reason="rejected"></Reject>
         </Response>''')

Message

The Message verb sends a message to a phone number. In FlexML, it has a corresponding Sms verb. Refer to the Plivo XML and FlexML documentation sections for more information on Message/Sms.

The attribute names differ in Plivo XML Message and in FlexML Sms. You can make the following replacements:

The type attribute is not present in CarrierX FlexML Sms and you can simply drop it.

Code Examples

Below is a Python code sample of the Plivo XML Message verb and a corresponding Python syntax of the FlexML Sms code:

Plivo XML Message Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.MessageElement(
        'Store Location: 123 Easy St.',
        src='+12023222222',
        dst='+15671234567',
        type='sms'))
print(response.to_string())

Corresponding FlexML Sms Verb Python Syntax

print('''<Response>
             <Sms from="12023222222" to="15671234567">
                 Store Location: 123 Easy St.
             </Sms>
         </Response>''')

Number

The Number noun contains the phone number to be dialed. Refer to the Plivo XML and FlexML documentation sections for more information on Number.

The only attribute of the Number noun in Plivo XML that has the corresponding FlexML field is sendDigits. All the other attributes present in Plivo XML Number are currently unsupported in FlexML.

Code Examples

Below is a Python code sample of the Plivo XML Number noun and a corresponding Python syntax of the FlexML Number code:

Plivo XML Number Noun Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.DialElement().add(
    plivoxml.NumberElement('15671234567', send_digits='wwww2410')))
print(response.to_string())

Corresponding FlexML Number Noun Python Syntax

print('''<Response>
             <Dial>
                 <Number sendDigits=",,,,2410">
                     15671234567
                 </Number>
             </Dial>
         </Response>''')

Play

The Play verb plays an audio file back to the caller. Refer to the Plivo XML and FlexML documentation sections for more information on Play.

You can use the loop Plivo XML Play verb attribute without any changes in FlexML.

No other attributes are present in Plivo XML Play, although there are more attributes in FlexML Play which you can use.

Code Examples

Below is a Python code sample of the Plivo XML Play verb and a corresponding Python syntax of the FlexML Play code:

Plivo XML Play Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.PlayElement('https://example.com/path/to/media.mp3', loop=10))
print(response.to_string())

Corresponding FlexML Play Verb Python Syntax

print('''<Response>
             <Play loop="10">
                 https://example.com/path/to/media.mp3
             </Play>
         </Response>''')

PreAnswer

The PreAnswer verb responds to the incoming call before it is answered. Refer to the Plivo XML and FlexML documentation sections for more information on PreAnswer.

The PreAnswer verb has no attributes either in Plivo XML or in CarrierX FlexML.

Code Examples

Below is a Python code sample of the Plivo XML PreAnswer verb and a corresponding Python syntax of the FlexML PreAnswer code:

Plivo XML PreAnswer Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(plivoxml.PreAnswerElement().add(
    plivoxml.SpeakElement('Sorry, we cannot answer your call right now. Please try again later.')))
response.add(plivoxml.HangupElement(reason='busy'))
print(response.to_string())

Corresponding FlexML PreAnswer Verb Python Syntax

print('''<Response>
             <PreAnswer>
                 <Say>Sorry, we cannot answer your call right now. Please try again later.</Say>
             </PreAnswer>
             <Reject reason="busy"></Reject>
         </Response>''')

Record

The Record verb records the conversation and stores it as an audio file. Refer to the Plivo XML and FlexML documentation sections for more information on Record.

You can use the following Plivo XML Record verb attributes without any changes in FlexML:

There are more attributes in FlexML Record which you can use.

Code Examples

Below is a Python code sample of the Plivo XML Record verb and a corresponding Python syntax of the FlexML Record code:

Plivo XML Record Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.SpeakElement(
        'Please leave a message after the beep. Press the star key when done.'))
response.add(
    plivoxml.RecordElement(
        action='https://example.com/get_recording/',
        max_length=30,
        finish_on_key='*'))
print(response.to_string())

Corresponding FlexML Record Verb Python Syntax

print('''<Response>
             <Say>Please leave a message after the beep. Press the star key when done.</Say>
             <Record containerSid="ea55039a-3ee4-48cd-a1ff-dfb7751f1cec" playBeep="true" action="https://example.com/get_recording/" maxLength="30" finishOnKey="*"></Record>
         </Response>''')

Redirect

The Redirect verb turns over the control of the call flow to another set of instructions located at a different URL. Refer to the Plivo XML and FlexML documentation sections for more information on Redirect.

The only attribute of the Redirect verb in Plivo XML that has the corresponding FlexML field is method. No other attributes are present in either Plivo XML or FlexML.

Code Examples

Below is a Python code sample of the Plivo XML Redirect verb and a corresponding Python syntax of the FlexML Redirect code:

Plivo XML Redirect Verb Python Example

from plivo import plivoxml

response = plivoxml.ResponseElement()
response.add(
    plivoxml.SpeakElement('Please wait while you call is being transferred.'))
response.add(plivoxml.RedirectElement('https://example.com/path/to/handler', method="GET"))
print(response.to_string())

Corresponding FlexML Redirect Verb Python Syntax

print('''<Response>
             <Say>Please wait while you call is being transferred.</Say>
             <Redirect method="GET">https://example.com/path/to/handler</Redirect>
         </Response>''')

Speak

The Speak verb converts text to speech that is read back to the caller. In FlexML, it has a corresponding Say verb. Refer to the Plivo XML and FlexML documentation sections for more information on Say.

You can use the following Plivo XML Speak verb attributes without any changes in FlexML:

One more attribute of the Speak verb in Plivo XML that you can use in FlexML is voice. In FlexML, this attribute accepts the following values: man, woman, and any of the Amazon Polly voices.

Code Examples

Below is a Python code sample of the Plivo XML Say verb and a corresponding Python syntax of the FlexML Say code:

Plivo XML Say Verb Python Example

from plivo import plivoxml

response = (plivoxml.ResponseElement()
            .add(plivoxml.SpeakElement('Thank you for calling customer service.').set_loop(3)))
print(response.to_string())

Corresponding FlexML Say Verb Python Syntax

print('''<Response>
             <Say loop="3">Thank you for calling customer service.</Say>
         </Response>''')

Wait

The Wait verb stops the next verb in the instructions from executing before the specified number of seconds has elapsed. In FlexML, it has a corresponding Pause verb, though Wait is also available. Refer to the Plivo XML and FlexML documentation sections for more information on Pause.

You can use the following Plivo XML Wait verb attributes without any changes in FlexML:

All the other attributes present in Plivo XML Wait are currently unsupported in FlexML. There are also additional attributes in FlexML Pause which you can use.

Code Examples

Below is a Python code sample of the Plivo XML Pause verb and a corresponding Python syntax of the FlexML Pause code:

Plivo XML Wait Verb Python Example

from plivo import plivoxml

response = (plivoxml.ResponseElement().add(
    plivoxml.WaitElement(None).set_length(10).set_min_silence(3000)
    .set_silence(True)).add(plivoxml.SpeakElement('Hello')))
print(response.to_string())

Corresponding FlexML Pause Verb Python Syntax

print('''<Response>
             <Pause length="10" silence="true" minSilence="3000"/>
             <Say>Hello</Say>
         </Response>''')

Further Reading

Now that you know how Plivo XML syntax can be adapted for use with FlexML, you can take a real application and change it so that it worked correctly with CarrierX. Read the following articles with examples of applications migration to CarrierX:

Refer to the following pages to learn more about FlexML verbs and how to use them, and about ways to set up a FlexML endpoint: