Migrating from Other Services

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 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.

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)

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.

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

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

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

Please 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.

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

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

Migrating from Plivo to CarrierX

Migrating Plivo Account to CarrierX

Setting Applications URLs

Migrating Applications That Use Client Library

Plivo Python Request Example

Corresponding CarrierX Python Syntax

Migrating Plivo XML Applications to FlexML

Dial

Code Examples

Plivo XML Dial Verb Python Example

Corresponding FlexML Dial Verb Python Syntax

DTMF

Code Examples

Plivo XML DTMF Verb Python Example

Corresponding FlexML Dtmf Verb Python Syntax

GetDigits/ GetInput

Code Examples

Plivo XML GetDigits/ GetInput Verb Python Example

Corresponding FlexML Gather Verb Python Syntax

Hangup

Code Examples

Plivo XML Hangup Verb Python Example

Corresponding FlexML Hangup Verb Python Syntax

Plivo XML Hangup Verb Python Example

Corresponding FlexML Reject Verb Python Syntax

Message

Code Examples

Plivo XML Message Verb Python Example

Corresponding FlexML Sms Verb Python Syntax

Number

Code Examples

Plivo XML Number Noun Python Example

Corresponding FlexML Number Noun Python Syntax

Play

Code Examples

Plivo XML Play Verb Python Example

Corresponding FlexML Play Verb Python Syntax

PreAnswer

Code Examples

Plivo XML PreAnswer Verb Python Example

Corresponding FlexML PreAnswer Verb Python Syntax

Record

Code Examples

Plivo XML Record Verb Python Example

Corresponding FlexML Record Verb Python Syntax

Redirect

Code Examples

Plivo XML Redirect Verb Python Example

Corresponding FlexML Redirect Verb Python Syntax

Speak

Code Examples

Plivo XML Speak Verb Python Example

Corresponding FlexML Say Verb Python Syntax

Wait

Code Examples

Plivo XML Wait Verb Python Example

Corresponding FlexML Pause Verb Python Syntax

Further Reading