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 .
In sandbox mode, the "ZZ" country code is included to allow provisioning simulated phone numbers. Refer to the page for details.
try! telephonyClient.getSupportedCountries { result in
switch result {
case .success(let countries):
// countries: list of strings containing the country ISO codes
case .failure(let error):
// error: SudoTelephonyClientError
}
}
telephonyClient.getSupportedCountries { result ->
when (result) {
is Result.Success -> {
// result.value.countries: list of strings containing
// the country ISO codes
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
}
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.
// By country code
try! telephonyClient.searchAvailablePhoneNumbers(countryCode: "US",
limit: 5) { (result) in
switch result {
case .success(let searchResult):
// searchResult: AvailablePhoneNumberResult (see below for details)
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// By country code
// val countryCode = "US"
telephonyClient.searchAvailablePhoneNumbers(countryCode) { result ->
when (result) {
is Result.Success -> {
// result.value.numbers: PhoneNumberSearchResult
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
}
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.
//By area code
try! telephonyClient.searchAvailablePhoneNumbers(countryCode: "US",
prefix: "385",
limit: nil) { (result) in
switch result {
case .success(let searchResult):
// searchResult: AvailablePhoneNumberResult (see below for details)
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// By area code
// val countryCode = "US"
// val areaCode = "385"
telephonyClient.searchAvailablePhoneNumbers(countryCode, areaCode) { result ->
when (result) {
is Result.Success -> {
// result.value.numbers: PhoneNumberSearchResult (see below for details)
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
}
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.
// By lat/lng
// let country: String = "US"
// let lat: Double = 37.234332396
// let lng: Double = -115.80666344
try! client.searchAvailablePhoneNumbers(countryCode: country,
latitude: lat,
longitude: lng,
limit: 5) { result in
switch result {
case .success(let searchResult):
// searchResult: AvailablePhoneNumberResult (see below for details)
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// By lat/lng
// val countryCode = "US"
// val latitude = "37.234332396"
// val longitude = "-115.80666344"
telephony.searchAvailablePhoneNumbers(countryCode,
latitude,
longitude) { result ->
when (result) {
is Result.Success -> {
// result.value.numbers: PhoneNumberSearchResult (see below for details)
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
this.latch.countDown()
}
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.
struct AvailablePhoneNumberResult {
let numbers: [String] // List of numbers available in E.164 format
let countryCode: String // Country code used for search
let prefix: String? // Prefix used for search
}
data class PhoneNumberSearchResult (val id: String,
val numbers: List<String>,
val countryCode: String,
val gps: AvailablePhoneNumberResult.Gps?,
val prefix: String?,
val state: PhoneNumberSearchState)
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.
try! telephonyClient.provisionPhoneNumber(countryCode: "US",
phoneNumber: "+442071838750",
sudoId: "abc123") { result in
switch result {
case .success(let number):
// number: PhoneNumber (see below for details)
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// val countryCode = "US"
// val phoneNumber = "+442071838750"
// val sudoID = "abc123"
telephonyClient.provisionPhoneNumber(countryCode, phoneNumber, sudoID) { result ->
when (result) {
is Result.Success -> {
// result.value: PhoneNumber (see below for details)
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
}
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.
public struct PhoneNumber {
public enum State: Equatable {
case complete
case provisioning
case deprovisioning
case failed
case unknown
}
public let id: String
public let phoneNumber: String
public let state: State
public let version: Int
public let created: Date
public let updated: Date
}
data class PhoneNumber(
val id: String,
val phoneNumber: String,
val state: PhoneNumberState,
val version: Int,
val created: Date,
val updated: Date
)
public enum PhoneNumberState {
PROVISIONING,
FAILED,
COMPLETE,
DEPROVISIONING
}
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
try! telephonyClient.deletePhoneNumber(phoneNumber: "+442071838750") { result in
switch result {
case .success(let phoneNumber):
// phoneNumber: E.164 formatted number
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// val phoneNumber: PhoneNumber
telephonyClient.deletePhoneNumber(phoneNumber.number) { result ->
when (result) {
is Result.Success -> {
// result.value: PhoneNumber
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
}
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.
// let phoneNumber: PhoneNumber
try! telephonyClient.getPhoneNumber(id: phoneNumber.id) { (result) in
switch result {
case .success(let number):
// number: PhoneNumber
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// val phoneNumber: PhoneNumber
telephonyClient.getPhoneNumber(phoneNumber.id) { result ->
when (result) {
is Result.Success -> {
// result.value: PhoneNumber
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
}
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.
let sudoID: String
try! telephonyClient.listPhoneNumbers(sudoId: sudoId, limit: nil, nextToken: nil) { (result) in
switch result {
case .success(let listToken):
// listToken: TelephonyListToken (see below for details)
case .failure(let error):
// error: SudoTelephonyClientError
}
}
// val sudoID = "abc123"
telephonyClient.listPhoneNumbers(sudoId, null, null) { result ->
when(result) {
is Result.Success -> {
// result.value: TelephonyListToken<PhoneNumber>
}
is Result.Error -> {
// result.throwable: telephonysdk.Result.Error
}
}
}
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.
struct TelephonyListToken {
let items: [PhoneNumber] // Phone numbers
let nextToken: String? // Reference for next page
}
data class TelephonyListToken<PhoneNumber>(
val items: List<PhoneNumber>,
val nextToken: String?
)
The Telephony SDK uses the for all string representations of phone numbers.
The Telephony SDK uses the for all string representations of phone numbers and this format is expected when provisioning a number.
A previously provisioned phone number can be de-provisioned by using the deletePhoneNumber() method. This method expects an formatted phone number string. The phone number must have already been provisioned for this to succeed.
