Manage Phone Numbers

Phone numbers are a central part of the Telephony SDK. Phone numbers from different countries around the world can be provisioned and used to to communicate with other phone numbers.
Provisioning a phone number is a two-step process. First, a search must be performed for an available phone number using a specific country code. After the desired phone number is selected, the phone number can be provisioned to a Sudo.
Get Supported Countries
To get the list of supported countries, use the getSupportedCountries() method. The country code format currently supported is the two-letter format described in ISO 3166-1 alpha-2.
In sandbox mode, the "ZZ" country code is included to allow provisioning simulated phone numbers. Refer to the Telephony Simulator page for details.
Swift
Kotlin
1
try! telephonyClient.getSupportedCountries { result in
2
    switch result {
3
    case .success(let countries):
4
        // countries: list of strings containing the country ISO codes
5
    case .failure(let error):
6
        // error: SudoTelephonyClientError
7
    }
8
}
Copied!
1
telephonyClient.getSupportedCountries { result ->
2
    when (result) {
3
        is Result.Success -> {
4
            // result.value.countries: list of strings containing 
5
            // the country ISO codes
6
        }
7
        is Result.Error -> {
8
            // result.throwable: telephonysdk.Result.Error
9
        }
10
    }
11
}
Copied!
Each project in your Sudo Platform account can be configured to support a specific set of country codes. Your solutions engineer can assist you in selecting the desired country codes.
Search Available Phone Numbers
A search for a phone number can be performed using either a country code, a country code plus phone number prefix (e.g., in the United States the prefix is called an "area code") or a latitude and longitude. A limit can be provided to ensure a maximum number of results are returned.
By Country Only
To search for a phone number by country code, use the searchAvailablePhoneNumbers() method and provide the two-character ISO country code.
Swift
Kotlin
1
// By country code
2
try! telephonyClient.searchAvailablePhoneNumbers(countryCode: "US", 
3
                                                 limit: 5) { (result) in
4
    switch result {
5
    case .success(let searchResult):
6
        // searchResult: AvailablePhoneNumberResult (see below for details) 
7
    case .failure(let error):
8
        // error: SudoTelephonyClientError
9
    }
10
}
Copied!
1
// By country code 
2
​
3
// val countryCode = "US"
4
telephonyClient.searchAvailablePhoneNumbers(countryCode) { result ->
5
    when (result) {
6
        is Result.Success -> {
7
            // result.value.numbers: PhoneNumberSearchResult
8
        }
9
        is Result.Error -> {
10
            // result.throwable: telephonysdk.Result.Error
11
        }
12
    }
13
}
Copied!
By Country and Prefix
To search for a phone number by country code and prefix, use the searchAvailablePhoneNumbers() method and provide the two-character country code and prefix digits.
Swift
Kotlin
1
//By area code
2
try! telephonyClient.searchAvailablePhoneNumbers(countryCode: "US", 
3
                                                 prefix: "385",
4
                                                 limit: nil) { (result) in
5
    switch result {
6
    case .success(let searchResult):
7
        // searchResult: AvailablePhoneNumberResult (see below for details) 
8
    case .failure(let error):
9
        // error: SudoTelephonyClientError
10
    }
11
}
Copied!
1
// By area code 
2
​
3
// val countryCode = "US"
4
// val areaCode = "385"
5
telephonyClient.searchAvailablePhoneNumbers(countryCode, areaCode) { result ->
6
    when (result) {
7
        is Result.Success -> {
8
            // result.value.numbers: PhoneNumberSearchResult (see below for details) 
9
        }
10
        is Result.Error -> {
11
            // result.throwable: telephonysdk.Result.Error
12
        }
13
    }
14
}
Copied!
By Latitude and Longitude
To search for a phone number by country code and latitude/longitude, use the searchAvailablePhoneNumbers() method and provide the two-character country code and latitude/longitude. This function finds geographically close numbers within miles. Applies to only phone numbers in the US and Canada.
Swift
Kotlin
1
// By lat/lng
2
​
3
// let country: String = "US"
4
// let lat: Double = 37.234332396
5
// let lng: Double = -115.80666344
6
try! client.searchAvailablePhoneNumbers(countryCode: country,
7
                                        latitude: lat,
8
                                        longitude: lng,
9
                                        limit: 5) { result in
10
    switch result {
11
    case .success(let searchResult):
12
        // searchResult: AvailablePhoneNumberResult (see below for details) 
13
    case .failure(let error):
14
        // error: SudoTelephonyClientError
15
    }
16
}
Copied!
1
// By lat/lng
2
​
3
// val countryCode = "US"
4
// val latitude = "37.234332396"
5
// val longitude = "-115.80666344"
6
telephony.searchAvailablePhoneNumbers(countryCode, 
7
                                      latitude, 
8
                                      longitude) { result ->
9
    when (result) {
10
        is Result.Success -> {
11
            // result.value.numbers: PhoneNumberSearchResult (see below for details) 
12
        }
13
        is Result.Error -> {
14
            // result.throwable: telephonysdk.Result.Error
15
        }
16
    }
17
​
18
    this.latch.countDown()
19
}
Copied!
Search Result
Both calls to searchAvailablePhoneNumbers() return a AvailablePhoneNumberResult (iOS) / PhoneNumberSearchResult (Android) on success. The result contains a list of available numbers and the country code / prefix used in the search.
The Telephony SDK uses the E.164 phone number format for all string representations of phone numbers.
Swift
Kotlin
1
struct AvailablePhoneNumberResult {
2
    let numbers: [String] // List of numbers available in E.164 format
3
    let countryCode: String // Country code used for search
4
    let prefix: String? // Prefix used for search
5
}
Copied!
1
data class PhoneNumberSearchResult (val id: String,
2
                                    val numbers: List<String>,
3
                                    val countryCode: String,
4
                                    val gps: AvailablePhoneNumberResult.Gps?,
5
                                    val prefix: String?,
6
                                    val state: PhoneNumberSearchState)
Copied!
Provision Phone Number
After an available phone number is found, it can be provisioned to a Sudo using the provisionPhoneNumber() method. Provisioning a phone number to a Sudo makes it available to communicate with other phone numbers, such as sending and receiving SMS and MMS messages.
The Telephony SDK uses the E.164 phone number format for all string representations of phone numbers and this format is expected when provisioning a number.
Swift
Kotlin
1
try! telephonyClient.provisionPhoneNumber(countryCode: "US", 
2
                                          phoneNumber: "+442071838750", 
3
                                          sudoId: "abc123") { result in
4
    switch result {
5
    case .success(let number):
6
        // number: PhoneNumber (see below for details)
7
    case .failure(let error):
8
        // error: SudoTelephonyClientError
9
    }
10
}
Copied!
1
// val countryCode = "US"
2
// val phoneNumber = "+442071838750"
3
// val sudoID = "abc123"
4
telephonyClient.provisionPhoneNumber(countryCode, phoneNumber, sudoID) { result ->
5
    when (result) {
6
        is Result.Success -> {
7
            // result.value: PhoneNumber (see below for details)
8
        }
9
        is Result.Error -> {
10
            // result.throwable: telephonysdk.Result.Error
11
        }
12
    }
13
}
Copied!
Phone Number
The PhoneNumber type is returned when a phone number is provisioned. This type is expected in other places where a phone number is used, such as sending an SMS/MMS message.
Swift
Kotlin
1
public struct PhoneNumber {
2
    public enum State: Equatable {
3
        case complete
4
        case provisioning
5
        case deprovisioning
6
        case failed
7
        case unknown
8
    }
9
​
10
    public let id: String
11
    public let phoneNumber: String
12
    public let state: State
13
    public let version: Int
14
    public let created: Date
15
    public let updated: Date
16
}
Copied!
1
data class PhoneNumber(
2
    val id: String,
3
    val phoneNumber: String,
4
    val state: PhoneNumberState,
5
    val version: Int,
6
    val created: Date,
7
    val updated: Date
8
)
9
​
10
public enum PhoneNumberState {
11
  PROVISIONING,
12
  FAILED,
13
  COMPLETE,
14
  DEPROVISIONING
15
}
Copied!
Entitlements
Each user is allocated a limited number of phone numbers per Sudo. The current limit is 1 number per Sudo. In the future this value will be configurable from the Admin Console. If an attempt is made to provision a number in excess of the entitlements, and error will be returned from the SDK.
De-Provision Phone Number
A previously provisioned phone number can be de-provisioned by using the deletePhoneNumber() method. This method expects an E.164 phone number format formatted phone number string. The phone number must have already been provisioned for this to succeed.
Swift
Kotlin
1
try! telephonyClient.deletePhoneNumber(phoneNumber: "+442071838750") { result in
2
    switch result {
3
    case .success(let phoneNumber):
4
        // phoneNumber: E.164 formatted number
5
    case .failure(let error):
6
        // error: SudoTelephonyClientError
7
    }
8
}
Copied!
1
// val phoneNumber: PhoneNumber
2
telephonyClient.deletePhoneNumber(phoneNumber.number) { result ->
3
    when (result) {
4
        is Result.Success -> {
5
            // result.value: PhoneNumber
6
        }
7
        is Result.Error -> {
8
            // result.throwable: telephonysdk.Result.Error
9
        }
10
    }
11
}
Copied!
Retrieving Existing Phone Numbers
Previously provisioned numbers can be retrieved using a phone number identifier or by retrieving all provisioned numbers.
Using Phone Number ID
You can retrieve a previously provisioned phone numbers by using the getPhoneNumber() method.
Swift
Kotlin
1
// let phoneNumber: PhoneNumber
2
try! telephonyClient.getPhoneNumber(id: phoneNumber.id) { (result) in
3
    switch result {
4
    case .success(let number):
5
        // number: PhoneNumber
6
    case .failure(let error):
7
        // error: SudoTelephonyClientError
8
    }
9
}
Copied!
1
// val phoneNumber: PhoneNumber
2
telephonyClient.getPhoneNumber(phoneNumber.id) { result ->
3
    when (result) {
4
        is Result.Success -> {
5
            // result.value: PhoneNumber
6
        }
7
        is Result.Error -> {
8
            // result.throwable: telephonysdk.Result.Error
9
        }
10
    }
11
}
Copied!
All Provisioned Phone Numbers
To retrieve all provisioned phone numbers, use the listPhoneNumbers() method. This method supports paging using the limit and nextToken parameters, and optionally filters by sudo id.
Swift
Kotlin
1
let sudoID: String
2
try! telephonyClient.listPhoneNumbers(sudoId: sudoId, limit: nil, nextToken: nil) { (result) in
3
    switch result {
4
    case .success(let listToken):
5
        // listToken: TelephonyListToken (see below for details)
6
    case .failure(let error):
7
        // error: SudoTelephonyClientError
8
    }
9
}
Copied!
1
// val sudoID = "abc123"
2
telephonyClient.listPhoneNumbers(sudoId, null, null) { result ->
3
    when(result) {
4
        is Result.Success -> {
5
            // result.value: TelephonyListToken<PhoneNumber>
6
        }
7
        is Result.Error -> {
8
            // result.throwable: telephonysdk.Result.Error
9
        }
10
    }
11
}
Copied!
The result of the listPhoneNumbers() call is a TelephonyListToken as described below.
Retrieve Multiple Phone Numbers Result
When multiple phone numbers are retrieved, for example through the getPhoneNumbers() method, a list token object is returned which includes a list of phone numbers and a paging token used to retrieve the next set of results.
Swift
Kotlin
1
struct TelephonyListToken {
2
    let items: [PhoneNumber] // Phone numbers
3
    let nextToken: String? // Reference for next page
4
​
5
}
Copied!
1
data class TelephonyListToken<PhoneNumber>(
2
    val items: List<PhoneNumber>,
3
    val nextToken: String?
4
)
Copied!
Integrate the Telephony SDK
Text Messaging
Last modified 1yr ago
Copy link
Contents
Get Supported Countries
Search Available Phone Numbers
By Country Only
By Country and Prefix
By Latitude and Longitude
Search Result
Provision Phone Number
Phone Number
Entitlements
De-Provision Phone Number
Retrieving Existing Phone Numbers
Using Phone Number ID
All Provisioned Phone Numbers
Retrieve Multiple Phone Numbers Result