SudoTelephonyClient

public protocol SudoTelephonyClient

Protocol encapsulating a library of functions for managing phone numbers and messages in the Sudo Platform Telephony service.

  • Removes all keys associated with this client, resets any cached data, cleans up subscriptions, and purges any pending operations.

    It is important to note that this will clear ALL cached data related to all telephony services.

    Declaration

    Swift

    func reset() throws

  • Get supported countries for searching available phone numbers. The supported countries are returned in ISO 3166-1 alpha-2 format. For example: US, ND, etc.

    Declaration

    Swift

    func getSupportedCountries(completion: @escaping TelephonyClientCompletion<[String]>)

    Parameters

    completion

    Completion callback that returns supported countries.

  • Get available phone numbers for the specified country code.

    Declaration

    Swift

    func searchAvailablePhoneNumbers(countryCode: String, limit: UInt?, completion: @escaping SudoTelephonySearchResult)

    Parameters

    countryCode

    Supported country code to search on. Code must be formatted in ISO 3166-1 alpha-2 format. For example: US, BR, ND, etc.
    limit

    Optional limit on the number of available phone numbers returned in the search result. If the limit is not specified, the default value is 10 and the search result will provide no more than 10 phone numbers.
    completion

    Completion callback providing a search result containing available phone numbers with the given country code.

  • Get available phone numbers for the specified country code and prefix.

    Declaration

    Swift

    func searchAvailablePhoneNumbers(countryCode: String, prefix: String, limit: UInt?, completion: @escaping SudoTelephonySearchResult)

    Parameters

    countryCode

    Supported country code to search on. Code must be formatted on the ISO 3166-1 alpha-2 format. For example: US, BR, ND, etc.
    prefix

    Parameter prefix: Optional prefix (area code) used to limit the search results. If nil, only the country code will used for the search. If the country code and area code do not match, the resulting list of available phone numbers might be empty.
    limit

    Optional limit on the number of available phone numbers returned in the search result. If the limit is not specified, the default value is 10 and the search result will provide no more than 10 phone numbers.
    completion

    Completion callback providing a search result containing available phone numbers with the given country code and prefix.

  • Get available phone numbers for the specified coordinates.

    Declaration

    Swift

    func searchAvailablePhoneNumbers(countryCode: String, latitude: Double, longitude: Double, limit: UInt?, completion: @escaping SudoTelephonySearchResult)

    Parameters

    countryCode

    Supported country code to search on. Code must be formatted on the ISO 3166-1 alpha-2 format. For example: US, BR, ND, etc.
    longitude

    Double value of the longitude of the coordinate to search on.
    latitude

    Double value of the latitude of the coordinate to search on.
    limit

    Optional limit on the number of available phone numbers returned in the search result. If the limit is not specified, the default value is 10 and the search result will provide no more than 10 phone numbers.
    completion

    Completion callback providing a search result containing available phone numbers with the given country code and coordinates.

  • Provision a phone number to the signed in account. Searching for available phone numbers should be done before this call, ensuring that the passed in phone number is available.

    Declaration

    Swift

    func provisionPhoneNumber(countryCode: String, phoneNumber: String, sudoId: String, completion: @escaping TelephonyClientCompletion<PhoneNumber>)

    Parameters

    countryCode

    Supported country of the number to provision. Code must be formatted on the ISO 3166-1 alpha-2 format. For example: US, BR, ND, etc.
    phoneNumber

    The E164 formatted phone number to provision.. For example: “+14155552671”.
    sudoId

    The ID of the Sudo to provision the phone number for.
    completion

    Completion callback that provides the provisioned phone number.

  • Delete an already provisioned from number from the signed in account.

    Declaration

    Swift

    func deletePhoneNumber(phoneNumber: String, completion: @escaping TelephonyClientCompletion<String>)

    Parameters

    phoneNumber

    The E164 formatted phone number to delete. For example: “+14155552671”.
    completion

    Completion callback that provides the phone number string on success.

  • List all the phone numbers provisioned by the user account. If the user does not have phone numbers associated with the account, an empty list will be returned. The list can be queried in batches, where the limit and the next batch token can be specified.

    Declaration

    Swift

    func listPhoneNumbers(sudoId: String?, limit: Int?, nextToken: String?, completion: @escaping TelephonyClientCompletion<TelephonyListToken<PhoneNumber>>)

    Parameters

    sudoId

    The sudo id to fetch for.
    limit

    The limit of the batch to fetch. If none specified, all of them will be returned.
    nextToken

    The token to use for pagination. Must pass same parameters as the previous call or unexpected results may be returned.
    completion

    Completion callback that provides a list of phone numbers or an error if there was a failure.

  • Retrieves the phone number for the provided ID. If the number is not associated/provisioned by the account, nil will be returned.

    Declaration

    Swift

    func getPhoneNumber(id: String, completion: @escaping TelephonyClientCompletion<PhoneNumber?>)

    Parameters

    id

    The id of the phone number to retrieve.
    completion

    Completion callback that provides the phone number or an error if it could not be retrieved.

  • Sends an MMS message from a provisioned phone number to another number.

    Declaration

    Swift

    func sendSMSMessage(localNumber: PhoneNumber, remoteNumber: String, body: String, completion: @escaping TelephonyClientCompletion<PhoneMessage>)

    Parameters

    localNumber

    The E164 formatted phone number to send the message from. For example: “+14155552671”.
    remoteNumber

    The E164 formatted phone number of the recipient. For example: “+14155552671”.
    body

    The body of the SMS message.
    completion

    Completion callback providing the sent message or an error if there was a failure.

  • Sends an MMS message from a provisioned phone number to another number.

    Declaration

    Swift

    func sendMMSMessage(localNumber: PhoneNumber, remoteNumber: String, body: String?, localUrl: URL, completion: @escaping TelephonyClientCompletion<PhoneMessage>)

    Parameters

    localNumber

    The E164 formatted phone number to send the message from. For example: “+14155552671”.
    remoteNumber

    The E164 formatted phone number of the recipient. For example: “+14155552671”.
    body

    The text body of the MMS message.
    localUrl

    The local path of the media to be uploaded.
    completion

    Completion callback providing the sent message or an error if there was a failure.

  • Subscribe to new messages and message status updates.

    Declaration

    Swift

    func subscribeToMessages(statusObserver: SubscriptionHandler<SubscriptionStatus>?,
                                resultHandler: @escaping SubscriptionHandler<PhoneMessage>) throws -> SubscriptionToken?

    Parameters

    statusObserver

    A callback that provides subscription status events.
    resultHandler

    A callback that provides new/updated messages when message events occur.

    Return Value

    SubscriptionToken The object used to cancel the subscription. When this object is released, the subscription is canceled.

  • Retrieves a message matching the associated id.

    Declaration

    Swift

    func getMessage(id: String, completion: @escaping TelephonyClientCompletion<PhoneMessage>)

    Parameters

    id

    The id of the message to retrieve.
    completion

    Completion callback providing the message or an error if it could not be retrieved.

  • Retrieves a list of messages matching the specified criteria.

    Declaration

    Swift

    func getMessages(localNumber: PhoneNumber, remoteNumber: String, limit: Int?, nextToken: String?, completion: @escaping TelephonyClientCompletion<TelephonyListToken<PhoneMessage>>)

    Parameters

    localNumber

    The E164 formatted phone number of the participating sudo. For example: “+14155552671”.
    remoteNumber

    The E164 formatted phone number of the other participant in the phone conversation. For example: “+14155552671”.
    limit

    The maximum number of messages to retrieve.
    nextToken

    The token to use for pagination.
    completion

    Completion callback providing a list of messages or an error if there was a failure.

  • Retrieves a list of messages matching the specified criteria.

    Declaration

    Swift

    func getMessages(conversationId: String, limit: Int?, nextToken: String?, completion: @escaping TelephonyClientCompletion<TelephonyListToken<PhoneMessage>>)

    Parameters

    conversationId

    The id of the conversation associated with the messages to be retrieved.
    limit

    The maximum number of messages to retrieve.
    nextToken

    The token to use for pagination.
    completion

    Completion callback providing a list of messages or an error if there was a failure.

  • Downloads MMS attachments.

    Declaration

    Swift

    func downloadData(for media: MediaObject, completion: @escaping TelephonyClientCompletion<Data>)

    Parameters

    media

    The MediaObject that provides the necessary info for retrieving the media data.
    completion

    Completion callback providing the raw data of the retrieved media object or an error if it could not be retrieved.

  • Deletes a message matching the associated id.

    Declaration

    Swift

    func deleteMessage(id: String, completion: @escaping TelephonyClientCompletion<String>)

    Parameters

    id

    The id of the message to delete.
    completion

    Completion callback providing the id of the deleted message or an error if the message could not be deleted.

  • Retrieves the conversation matching the specified criteria.

    Declaration

    Swift

    func getConversation(conversationId: String, completion: @escaping TelephonyClientCompletion<PhoneMessageConversation>)

    Parameters

    conversationId

    The id of the conversation to be retrieved.
    completion

    Completion callback providing the conversation or an error if could not be retrieved.

  • Retrieves the conversation matching the specified criteria.

    Declaration

    Swift

    func getConversation(localNumber: PhoneNumber, remoteNumber: String, completion: @escaping TelephonyClientCompletion<PhoneMessageConversation>)

    Parameters

    localNumber

    The E164 formatted phone number of the participating sudo. For example: “+14155552671”.
    remoteNumber

    The E164 formatted phone number of the other participant in the phone conversation. For example: “+14155552671”.
    completion

    Completion callback providing the conversation or an error if could not be retrieved.

  • Retrieves a list of conversations for provisioned numbers.

    Declaration

    Swift

    func getConversations(localNumber: PhoneNumber, limit: Int?, nextToken: String?, completion: @escaping TelephonyClientCompletion<TelephonyListToken<PhoneMessageConversation>>)

    Parameters

    localNumber

    The E164 formatted phone number of the participating sudo. For example: “+14155552671”.
    limit

    The maximum number of conversations to retrieve.
    nextToken

    The token to use for pagination.
    completion

    Completion callback providing a list of conversations or an error if there was a failure.

  • Creates a call from a provisioned phone number to another number.

    Throws

    A CallConfigurationError if a CallProviderConfiguration object is not provided in the initializer.

    Declaration

    Swift

    func createVoiceCall(localNumber: PhoneNumber, remoteNumber: String, delegate: ActiveCallDelegate) throws

  • Register for incoming calls.

    Throws

    A CallConfigurationError if a CallProviderConfiguration object is not provided in the initializer.

    Declaration

    Swift

    func registerForIncomingCalls(with token: Data, useSandbox: Bool, completion: ((SudoTelephonyClientError?) -> Void)?) throws

    Parameters

    data

    The push token data from PushKit
    useSandbox

    Use the sandbox or production APNS. Developer builds typically use the sandbox.
    completion

    Called when the push token has been sucessfully provided to the service. Returns an error on failure.

  • Deregisters for calls using the last recieved voip push token data. The method should be called when Pushkit notifies your app the credentials have been invalidaded, or any other time you want to stop recieving voip pushes for incoming calls.

    Throws

    A CallConfigurationError if a CallProviderConfiguration object is not provided in the initializer.

    Declaration

    Swift

    func deregisterForIncomingCalls(completion: ((SudoTelephonyClientError?) -> Void)?) throws

    Parameters

    completion

    Called when deregistration is complete.

  • Notifies the SDK a new push was recieved.

    Throws

    A CallConfigurationError if a CallProviderConfiguration object is not provided in the initializer.

    Declaration

    Swift

    func handleIncomingPushNotificationPayload(_ payload: [AnyHashable : Any], notificationDelegate: IncomingCallNotificationDelegate) throws -> Bool

    Parameters

    payload

    The payload from the voip push

    Return Value

    A Bool indicating if the SDK was able to handle the payload or not.

  • Retrieves the call record with specified id.

    Declaration

    Swift

    func getCallRecord(callRecordId: String, completion: @escaping (Swift.Result<CallRecord, SudoTelephonyClientError>) -> Void) throws

    Parameters

    callRecordId

    The id of the CallRecord to be retrieved.
    completion

    Completion callback providing the CallRecord or an error if it could not be retrieved.

  • Retrieves a list of call records.

    Declaration

    Swift

    func getCallRecords(localNumber: PhoneNumber, limit: Int?, nextToken: String?, completion: @escaping (Swift.Result<TelephonyListToken<CallRecord>, SudoTelephonyClientError>) -> Void) throws

    Parameters

    localNumber

    The PhoneNumber of the participating sudo.
    limit

    The maximum number of call records to retrieve.
    nextToken

    The token to use for pagination.
    completion

    Completion callback providing a list of CallRecords or an error if it could not be retrieved.

  • Subscribe to new call record updates.

    Declaration

    Swift

    func subscribeToCallRecords(resultHandler: @escaping (Swift.Result<CallRecord, SudoTelephonyClientError>) -> Void) throws -> SubscriptionToken

    Parameters

    resultHandler

    A callback that provides new/updated call record when a call is completed.

    Return Value

    SubscriptionToken The object used to cancel the subscription. When this object is released, the subscription is canceled.

  • Deletes a call record matching the associated id.

    Declaration

    Swift

    func deleteCallRecord(id: String, completion: @escaping (Swift.Result<String, SudoTelephonyClientError>) -> Void) throws

    Parameters

    id

    The id of the CallRecord to delete.
    completion

    Completion callback providing the id of the deleted CallRecord or an error if the CallRecord could not be deleted.

  • Retrieves a list of Voicemails for the given PhoneNumber.

    Declaration

    Swift

    func getVoicemails(localNumber: PhoneNumber, limit: Int?, nextToken: String?, completion: @escaping (Swift.Result<TelephonyListToken<Voicemail>, SudoTelephonyClientError>) -> Void)

    Parameters

    localNumber

    The PhoneNumber to fetch Voicemails for.
    limit

    The maximum number of Voicemails to retrieve per page.
    nextToken

    The token to use for pagination.
    completion

    Completion callback providing a list of Voicemails or an error if it could not be retrieved.

  • Retrieves the voicemail with the specified id.

    Declaration

    Swift

    func getVoicemail(id: String, completion: @escaping (Swift.Result<Voicemail, SudoTelephonyClientError>) -> Void)

    Parameters

    id

    The id of the Voicemail to retrieve.
    completion

    Completion callback providing the Voicemail or an error if it could not be retrieved.

  • Deletes a voicemail matching the given id.

    Declaration

    Swift

    func deleteVoicemail(id: String, completion: @escaping (Swift.Result<Void, SudoTelephonyClientError>) -> Void)

    Parameters

    id

    The id of the Voicemail to delete.
    completion

    Completion callback providing success or an error if the Voicemail could not be deleted.

  • Subscribe to new, updated, and deleted Voicemail records.

    Declaration

    Swift

    func subscribeToVoicemails(resultHandler: @escaping (Swift.Result<Voicemail, SudoTelephonyClientError>) -> Void) throws -> SubscriptionToken

    Parameters

    resultHandler

    A callback that provides new/updated/deleted Voicemail records when changes occur.

    Return Value

    SubscriptionToken An object used to cancel the subscription. When this object is released, the subscription is canceled.