Skip to main content

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.

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​

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:

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

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

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.

note

The main difference in the syntax which TwiML and FlexML use is that TwiML applications normally use the library that Twilio 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 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:

  • action
  • callerId
  • hangupOnStar
  • method
  • recordingStatusCallback
  • recordingStatusCallbackMethod
  • timeLimit
  • timeout
  • trim

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:

  • do-not-record
  • record-from-answer
  • record-from-answer-dual (not supported in FlexML)
  • record-from-ringing
  • record-from-ringing-dual (not supported in FlexML)

The default value is do-not-record.

info

In FlexML the corresponding attribute is also record. Values accepted in this field are:

  • do-not-record
  • record-from-answer
  • record-from-ringing

The default value is do-not-record.

TwiML recordingStatusCallbackEvent​

Values accepted in this field are:

  • absent (not supported in FlexML)
  • completed
  • in-progress (not supported in FlexML)

The default value is completed.

info

In FlexML the corresponding attribute is also recordingStatusCallbackEvent. Values accepted in this field are:

  • completed
  • failed

The default value is completed, failed.

TwiML recordingTrack​

Values accepted in this field are:

  • both
  • inbound
  • outbound

The default value is both.

info

In FlexML the corresponding attribute is recordDirection. Values accepted in this field are:

  • any (use it in place of TwiML both)
  • in (use it in place of TwiML inbound)
  • out (use it in place of TwiML outbound)

The default value is any.

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:

  • action
  • finishOnKey
  • method
  • numDigits
  • timeout

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

Please note that you can only nest Play and Say inside Gather in FlexML.

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.

note

In Twilio, the text message is sent in response to an SMS/MMS that the caller sends to the phone number associated with the TwiML application. In CarrierX, the message is sent to the phone number that the caller uses to place a voice call to the FlexML application.

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

  • action
  • from
  • method
  • to

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

Please note that while you can nest Pause inside Gather in TwiML, in FlexML such nesting is not supported for Pause.

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:

  • digits
  • loop

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:

  • action
  • finishOnKey
  • maxLength
  • method
  • playBeep
  • recordingStatusCallback
  • recordingStatusCallbackMethod
  • timeout
  • transcribe
  • transcribeCallback
  • trim
note

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

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

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

  • language
  • loop

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.

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

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

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: