Migrating from Twilio to CarrierX

This article will describe how to migrate from Twilio 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 TwiML applications so that they worked with CarrierX.

Migrating Twilio 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

Twilio 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 Twilio, users can use the client library provided by Twilio 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):

Twilio Python Request Example

from twilio.rest import Client

client = Client('TWILIO_ACCOUNT_SID', 'TWILIO_AUTH_TOKEN')

call = client.calls.create(
                        url='https://example.com/path/to/handler',
                        to='+15558675310',
                        from_='+15017122661'
                    )

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 TwiML Applications to FlexML

Twilio uses TwiML, 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 TwiML 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 Twilio TwiML, 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 TwiML verbs and nouns that are supported in FlexML and provide the FlexML syntax that corresponds to the TwiML code which uses the Twilio libraries.

Dial

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

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

Some of the attributes (record and recordingStatusCallbackEvent) also exist both in TwiML and FlexML Dial, but have some differences. Other attributes (recordingTrack) have different names and values in FlexML, but can be converted to the new corresponding format. Refer to the sections below to find out how these attributes differ.

TwiML record

Values accepted in this field are:

The default value is do-not-record.

TwiML recordingStatusCallbackEvent

Values accepted in this field are:

The default value is completed.

TwiML recordingTrack

Values accepted in this field are:

The default value is both.

Code Examples

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

TwiML Dial Verb Python Example

from twilio.twiml.voice_response import Dial, VoiceResponse

response = VoiceResponse()
response.dial('415-123-4567')

print(response)

Corresponding FlexML Dial Verb Python Syntax

print('''<Response>
             <Dial>4151234567</Dial>
         </Response>''')

Gather

The Gather verb collects the digits that a caller enters into the phone keypad. Refer to the TwiML and FlexML documentation sections for more information on Gather.

You can use the following TwiML Gather verb attributes without any changes in FlexML:

All the other attributes present in TwiML Gather are currently unsupported in FlexML.

Code Examples

Below is a Python code sample of the TwiML Gather verb and a corresponding Python syntax of the FlexML Gather code:

TwiML Gather Verb Python Example

from twilio.twiml.voice_response import Gather, VoiceResponse, Say

response = VoiceResponse()
gather = Gather(action='/process_gather.php', method='GET')
gather.say('Please enter your account number, followed by the pound sign')
response.append(gather)

print(response)

Corresponding FlexML Gather Verb Python Syntax

print('''<Response>
             <Gather action="/process_gather.php" method="GET">
                 <Say>
                     Please enter your account number, followed by the pound sign
                 </Say>
             </Gather>
         </Response>''')

Hangup

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

The Hangup verb has no attributes either in TwiML or in FlexML.

Code Examples

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

TwiML Hangup Verb Python Example

from twilio.twiml.voice_response import Hangup, VoiceResponse

response = VoiceResponse()
response.hangup()

print(response)

Corresponding FlexML Hangup Verb Python Syntax

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

Message

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

You can use all TwiML Message verb attributes without any changes in FlexML Sms:

Code Examples

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

TwiML Message Verb Python Example

from twilio.twiml.messaging_response import Message, MessagingResponse

response = MessagingResponse()
response.message(
    'Store Location: 123 Easy St.', to='+14151234567'
)

print(response)

Corresponding FlexML Sms Verb Python Syntax

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

Number

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

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

Code Examples

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

TwiML Number Noun Python Example

from twilio.twiml.voice_response import Dial, Number, VoiceResponse

response = VoiceResponse()
dial = Dial()
dial.number('415-123-4567', send_digits='wwww1928')
response.append(dial)

print(response)

Corresponding FlexML Number Noun Python Syntax

print('''<Response>
             <Dial>
                 <Number sendDigits=",,,,1928">
                     4151234567
                 </Number>
             </Dial>
         </Response>''')

Pause

The Pause verb stops the next verb in the instructions from executing before the specified number of seconds has elapsed. Refer to the TwiML and FlexML documentation sections for more information on Pause.

The only attribute of the Pause verb in TwiML that has the corresponding FlexML field is length. No other attributes are present in TwiML Pause, although there are more attributes in FlexML Pause which you can use.

Code Examples

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

TwiML Pause Verb Python Example

from twilio.twiml.voice_response import Pause, VoiceResponse, Say

response = VoiceResponse()
response.say('I will pause 10 seconds starting now!')
response.pause(length=10)
response.say('I just paused 10 seconds')

print(response)

Corresponding FlexML Pause Verb Python Syntax

print('''<Response>
             <Say>I will pause 10 seconds starting now!</Say>
             <Pause length="10"/>
             <Say>I just paused 10 seconds</Say>
         </Response>''')

Play

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

You can use the following TwiML Play verb attributes without any changes in FlexML:

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

Code Examples

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

TwiML Play Verb Python Example

from twilio.twiml.voice_response import Play, VoiceResponse

response = VoiceResponse()
response.play('https://example.com/path/to/media.mp3', loop=10)

print(response)

Corresponding FlexML Play Verb Python Syntax

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

Record

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

You can use the following TwiML 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 TwiML Record verb and a corresponding Python syntax of the FlexML Record code:

TwiML Record Verb Python Example

from twilio.twiml.voice_response import Record, VoiceResponse

response = VoiceResponse()
response.record(timeout=10, transcribe=True)

print(response)

Corresponding FlexML Record Verb Python Syntax

print('''<Response>
             <Record containerSid="ea55039a-3ee4-48cd-a1ff-dfb7751f1cec" timeout="10" transcribe="true"></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 TwiML and FlexML documentation sections for more information on Redirect.

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

Code Examples

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

TwiML Redirect Verb Python Example

from twilio.twiml.voice_response import Redirect, VoiceResponse

response = VoiceResponse()
response.redirect('https://example.com/path/to/handler', method='GET')

print(response)

Corresponding FlexML Redirect Verb Python Syntax

print('''<Response>
             <Redirect method="GET">https://example.com/path/to/handler</Redirect>
         </Response>''')

Reject

The Reject verb does not answer a call, but instead rejects it. Refer to the TwiML and FlexML documentation sections for more information on Reject.

The only attribute of the Reject verb in TwiML that has the corresponding FlexML field is reason. No other attributes are present in TwiML Pause, although there are more reject reasons in FlexML Reject which you can use.

Code Examples

Below is a Python code sample of the TwiML Reject verb and a corresponding Python syntax of the FlexML Reject code:

TwiML Reject Verb Python Example

from twilio.twiml.voice_response import Reject, VoiceResponse

response = VoiceResponse()
response.reject(reason='busy')

print(response)

Corresponding FlexML Reject Verb Python Syntax

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

Say

The Say verb converts text to speech that is read back to the caller. Refer to the TwiML and FlexML documentation sections for more information on Say.

You can use the following TwiML Say verb attributes without any changes in FlexML:

One more attribute of the Say verb in TwiML 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 TwiML Say verb and a corresponding Python syntax of the FlexML Say code:

TwiML Say Verb Python Example

from twilio.twiml.voice_response import VoiceResponse, Say

response = VoiceResponse()
response.say('Thank you for calling customer service', voice='woman', loop=2)

print(response)

Corresponding FlexML Say Verb Python Syntax

print('''<Response>
             <Say voice="woman" loop="2">Thank you for calling customer service</Say>
         </Response>''')

Further Reading

Now that you know how TwiML 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: