Skip to main content

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.

tip

Refer to our Getting Started article for more information on how to start work with CarrierX. There you can learn how to obtain an authentication token, which you will use for API requests, and learn how to send a first request.

You can also read the following quick start guides 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:

  • In the phone number settings

    If you have a phone number associated with several endpoints and want to execute the instructions every time the phone number receives a call on all endpoints, you can set the application URL to the phone number. To do this, go to the portal Configure left-side menu, click Phone Numbers, select the phone number you want to edit with the mouse, and switch to the Application: FlexML tab. Here, enter the application URL and Method. You can also set up the Status Callback URL and the Status Callback Method in the same form.

  • In the endpoint settings

    If you prefer to set the applications on the per-endpoint basis, go to the portal Configure left-side menu, click Endpoints, select the endpoint you want to edit with the mouse, and switch to the Application: FlexML tab. Here, enter the application Default URL and Default Method.

note

You need to set the Default Container in the endpoint settings if you want to use the Record verb and store the recordings in CarrierX storage. In the case you do not set it, you will either need to specify this storage container each time when you use the Record verb or use the external storage for the recordings, also specifying that storage with the Record verb arguments.

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)
note

You are free to store the credentials data as environment variables and not to mention them explicitly in your code.

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.

note

The main difference in the syntax which Plivo XML and FlexML use is that Plivo XML applications normally use the library that Plivo provides for most programming languages. In its turn, FlexML does not use any additional libraries, and you can simply return plain FlexML to the call.

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.

note

In Plivo XML, the Dial verb requires to nest either the Number or User nouns inside it. In CarrierX FlexML, you can use the Dial verb by itself or nest the Number noun.

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

  • callerId
  • callerName
  • confirmKey
  • hangupOnStar
  • method

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:

  • In Plivo XML, the timeLimit attribute defaults to 14400 seconds (4 hours). In CarrierX FlexML, the default value is 0, meaning that the call time is not limited.
  • In Plivo XML, the default value for timeout is not set. In CarrierX FlexML, the default value is 30.

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:

  • In Plivo XML, you can set the dialMusic attribute to either real (to play the real ringtone of the called party) or to the fully qualified URL of the music that will be played.
  • In CarrierX FlexML, you can set the ringing attribute to true to play the ringing sound, or to music to playback the default music. It is also possible to disable any sound with setting this attribute to false.

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:

  • action
  • finishOnKey
  • method
  • numDigits
  • timeout
  • validDigits
note

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.

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:

  • callbackMethod in Plivo XML is replaced with the FlexML method attribute.
  • callbackUrl in Plivo XML is replaced with the FlexML action attribute.
  • dst in Plivo XML is replaced with the FlexML to attribute.
  • src in Plivo XML is replaced with the FlexML from attribute.

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:

  • action
  • callbackUrl
  • fileFormat
  • finishOnKey
  • maxLength
  • method
  • playBeep
  • recordSession
  • timeout
note

By default, the playBeep attribute value is set to true in Plivo XML but equals to false in FlexML. Please set it explicitly in the case you omit it in Plivo XML code.

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>''')
note

note that you need to additionally specify the secure ID (containerSid) of the container where the recording will be stored either here or in the FlexML endpoint portal settings (or use one of the supported external storage services), and explicitly set the FlexML recordSession attribute to true if you want to record the whole session in the background. Refer to the FlexML Record verb documentation for more information on this.

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:

  • language
  • loop

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.

note

CarrierX FlexML currently does not use Speech Synthesis Markup Language (SSML) for TTS generated voice messages.

Code Examples​

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

Plivo XML Speak 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>''')
note

In FlexML the length of Say is limited to 1,024 characters. Please split your phrases so that they are not longer than 1,024 characters if needed.

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:

  • length
  • minSilence
  • silence

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: