Table of Contents

API Changes for Voice Billing

Read Time: 12 mins

Intro

With our voice billing update deployment (October 6th, 2022) brings significant improvements to voice billing in Sonar, and includes several changes to our GraphQL API. Please see review the "Reference" section below for a full list of changes.

What’s New?

We have introduced three new entities in this update:

  1. Rate Centers
  2. Scheduled Event Account Voice Service Details
  3. Voice Service Generic Parameter Taxes

We also now support one-time transactions on accounts for Voice Services and have added the option to include Call Detail Records (CDRs) on invoices.

Rate Centers

A Rate Center is grouping of telephone numbers; a regulatory construct in the North American Numbering Plan (NANP). Rate centers are primarily used to determine usage-based call rates and number portability in the Public Switched Telephone Network (PSTN). A number may be ported between service providers but not between rate centers.

In Sonar, a rate center is an organizational grouping of direct inward dial (DID) numbers. It has a name and a related group of DIDs. Each DID added to Sonar must be associated with a rate center. A rate center does not describe the rates that apply to CDRs in Sonar. Other mechanisms e.g. Voice Service Details (VSDs), Voice Provider Rates, etc. are used to determine the applicable usage-based call rates.

Rate centers may be queried with the new rate_centers query and managed with the new createRateCenter, updateRateCenter, and deleteRateCenter mutations.

At the time of our update, we create the “Default” rate center and associate all of the existing DIDs with this default.

Please note: the default rate center may not be deleted but may be renamed.

When creating a DID with the available mutations, either of createDid or importDids, the rate_center_id is now a required field in the input.

When updating a DID with the available mutation, updateDid, the rate_center_id may be provided to re-assign the DID to the specified rate center.

Scheduled Event Account Voice Service Details

The Scheduled Event Account Voice Service Details are the Account Voice Service Details (AVSDs) included when creating or updating a Scheduled Event that will add one or more Voice Services to an Account. An AVSD configures, for each of the available Voice Service Generic Parameters (VSGPs) defined on the Voice Service, the quantity of the VSGP included with the account’s service and optionally a price override with price override reason.

The Scheduled Event AVSDs may be queried with the new scheduled_event_account_voice_service_details query.

When a scheduled event is used to add voice services, the required Scheduled Event AVSDs are provided in the new account_voice_service_details field of the createScheduledEvent mutation.

When an update to Scheduled Event AVSDs is necessary, the updateScheduledEvent mutation may now be provided with the account_voice_service_details field to specify the new values.

Voice Service Generic Parameter Taxes

A Voice Service Generic Parameter Tax is an entity which relates a Tax and an optional tax exemption amount, to a VSGP defined on a Voice Service. A Voice Service may have many VSGPs and a VSGP may have zero or more VSGP Taxes.

Prior to the update, VSGPs were taxed according to the Service Taxes configured on the Voice Service where the VSGPs were defined. We introduced the VSGP Tax to provide much more fine-grained control over tax application and exemption, on a per-VSGP basis. A VSGP Tax is to a VSGP as a Service Tax is to a Service.

VSGP Taxes may be queried with the new voice_service_generic_parameter_taxes query.

When creating a new VSGP, the applicable VSGP Taxes may be provided in the new taxes field of the createVoiceServiceGenericParameter mutation.

When an update to existing VSGP Taxes is necessary, the updateVoiceServiceGenericParameter mutation may now be provided with the taxes field to specify the new values.

Voice Services In One Time Transactions on Accounts

When creating a one time transaction for a Voice Service on an account, the createAccountOneTimeTransaction mutation now accepts the required AVSDs for a Voice Service in the new account_voice_service_details field. Previously, it was not possible to include a Voice Service in a one time transaction.

Call Detail Records on Invoices

CDRs which contribute to transactions included on an invoice may now be displayed in a detailed listing on the invoice. This setting is configured on the Voice Service to provide additional flexibility on which CDRs are included and defaults to false when not specified.

When creating a Voice Service, the display of CDRs on invoices can be enabled with the new show_call_detail_records_on_invoices field of the createVoiceService mutation.

For existing Voice Services, the setting may be updated with the new show_call_detail_records_on_invoices field of the updateVoiceService mutation.

Only those CDRs which are rated for a non-zero charge amount are displayed. For example, free local calls are not included.

What’s Changed?

We have simplified day-to-day operations with DIDs, Voice Provider Rates, and CDRs, and made improvements to better the overall, end-to-end consistency of voice billing in Sonar.

Direct Inward Dial Numbers

DIDs no longer include the country and subdivision fields, we determine this information from the number itself. These fields have been removed from the DID entity and are no longer present in the input to the createDid and importDids mutations.

DIDs are now grouped by Rate Center, and the rate_center_id input field is required in the createDid mutation.

When creating or updating a DID, the provided number must be unique across all Voice Providers. Previously it only needed to be unique within its Voice Provider.

Call Detail Records

CDRs have several changes with the new update that apply both before rating -when creating the CDR in Sonar- and after rating -where the type of call and applicable charges are determined.

CDRs may now be managed individually with the new createCallDetailRecord, updateCallDetailRecord, and deleteCallDetailRecord mutations.

Before Rating

CDRs no longer include the originating_country, and receiving_country fields, we determine this information from the numbers in originating_number and receiving_number.

The originating_number and receiving_number input fields are now required in each of the items in the call_detail_records input field of the createCallDetailRecordImport mutation.

Each of the two numbers originating_number and receiving_number should be provided in E-164 format with the short-form international exit code prefix, ‘+’, to ensure accurate rating. Numbers which do not include the ‘+’ prefix are accepted only where they pass a validation check as a valid number when the country code for the country configured in the Sonar System Settings is appended to the number. For example, where a CDR includes the London, UK telephone number 44 (0)33 3320 6000 -note the missing ‘+’ prefix- and the Sonar System Settings indicate the country is the U.S.A., the number will be validated as +14403333206000, and fail validation because this is not a valid telephone number for the U.S.A. To correctly include the the UK telephone number in the CDR, it must begin with a leading ‘+’ e.g. +44 (0)33 3320 6000.

The answered_at field is removed. We consider the started_at field to determine which customer account placed or received the call based on DID assignments applicable at that time, and the length_in_seconds field to calculate the applicable charges for the call. An unanswered call must have a length_in_seconds field value of zero (0).

The createCallDetailRecordImport mutation gains the required voice_provider_id input field. Each of the CDRs provided in the call_detail_records input field is associated with the provided Voice Provider. When rating these CDRs, only those customer accounts having an assigned DID related to the same Voice Provider are candidates to be charged for the call. For example, consider the call placed from Customer A using a DID associated with Voice Provider A, to Customer B using a DID associated with Voice Provider B. If the CDR is associated with Voice Provider A, the call is determined to be an OUTBOUND call with any applicable charges owned by Customer A. If the CDR is associated with Voice Provider B, the call is INBOUND and any charges apply to Customer B.

After Rating

The local and long_distance fields are removed, the call type is now provided in the prefix_type field. Where before the prefix_type could be any string value, it now has the CallDetailRecordPrefixType. The complete list of values for prefix_type is:

  • TOLL_FREE - for calls placed to a toll-free number. Any number beginning with one of the following prefixes is considered a toll-free number:
    • 1-800
    • 1-833
    • 1-844
    • 1-855
    • 1-866
    • 1-877
    • 1-888
  • LOCAL - for calls matching a local prefix defined on the Voice Service.
  • PROVIDER_RATED - for calls matching a prefix given in a Voice Provider Rate.
  • LONG_DISTANCE - the default prefix type; for calls which are neither toll-free, local, nor provider rated.

Where a CDR is the PROVIDER_RATED prefix type, the CDR description field is set to the description of the matched Voice Provider Rate. For all other CDRs the description field is empty.

The newly added direction field with type CallDetailRecordDirection is used to indicate which party on the call owns the applicable charges and is given by the account relation in the API response when querying the CDR. The complete list of values for direction is:

  • INBOUND - the charges apply to the account which is assigned the DID in the receiving_number field.
  • OUTBOUND - the charges apply to the account which is assigned the DID in the originating_number field.

The newly added charge_rate field provides the per-minute rate used in calculating the amount to bill for the call.

Voice Providers

The name field of a Voice Provider must be unique across all Voice Providers.

Voice Provider Rates

Voice Provider Rates no longer include the country field. This has been removed from the Voice Provider Rate entity and is no longer present in the items provided in the rates input field of the createVoiceProviderRateImport mutation. We determine the country from the prefix itself.

The createVoiceProviderRateImport also gains the two new required input fields voice_provider_id to associate a rate with a specific voice provider, and charge_percent to specify a percentage over the base_rate to charge the end-user. For example, providing a charge_percent of “10” will apply a 10% markup to each of the provided rates, such that a voice provider rate with a base_rate of $0.10 per minute is billed to end-users at the rate of $0.11 per minute ($0.10 + 10%). The charge_percent input field accepts any value between 0 and 999.999 with up to three-digits of precision after the decimal point.

Voice Provider Rates may now be managed individually with the new createVoiceProviderRate, updateVoiceProviderRate, and deleteVoiceProviderRate mutations.

Voice Service Generic Parameters

The default_quantity input field of the createVoiceServiceGenericParamter mutation is deprecated, in favor of the new backfill_quantity input field which serves the same purpose. That is, when creating a new VSGP for a Voice Service which is already in service with customers, the new VSGP is added to the existing services in the quantity specified in backfill_quantity.

Putting It All Together

We’ve now covered all of the changes to the Sonar GraphQL API in our 2022 voice billing update. For complete information on getting started and working with voice billing as a Sonar Partner using our Sonar web application directly, check out our deployment and billing documentation.

We have plenty more in store for voice billing in Sonar with more great features and conveniences coming your way soon. Stay tuned!

Reference

This reference section covers the API changes introduced at the time of our October 6th, 2022 voice billing update. Refer to the Sonar GraphQL Documentation for the most up-to-date reference.

New Types

  1. CallDetailRecordDirection
  2. RateCenter
  3. ScheduledEventAccountVoiceServiceDetail
  4. VoiceServiceGenericParamterTax

Changes to Existing Types

  1. CallDetailRecord
    1. The originating_country, receiving_country, answered_at, local, and long_distance fields are removed.
    2. The prefix_type field type has changed from string to CallDetailRecordPrefixType.
    3. The direction field with type CallDetailRecordDirection is newly added.
    4. The charge_rate field with type float is newly added.
    5. The description field with type string is newly added.
  2. CallDetailRecordPrefixType
    1. The INBOUND_TOLL_FREE case is removed.
    2. The INTERNATIONAL case is renamed to PROVIDER_RATED.
  3. Did
    1. The country and subdivision fields are removed.
    2. The rate_center_id field with type int64 is newly added.
    3. The rate_center connection to one related RateCenter is newly added.
  4. ScheduledEvent
    1. The scheduled_event_account_voice_service_details connection to many related ScheduledEventAccountVoiceServiceDetail is newly added.
  5. VoiceProviderRate
    1. The country field is removed.
  6. VoiceServiceDetail
    1. The show_call_detail_records_on_invoice field with type boolean is newly added.
  7. VoiceServiceGenericParameter
    1. The scheduled_event_account_voice_service_details connection to many related ScheduledEventAccountVoiceServiceDetail is newly added.
    2. The taxes connection to many related VoiceServiceGenericParameterTax is newly added.

New Queries

  1. rate_centers
  2. scheduled_event_account_voice_service_details
  3. voice_service_generic_parameter_taxes

New Mutations

  1. createCallDetailRecord
  2. createRateCenter
  3. createVoiceProviderRate
  4. deleteCallDetailRecord
  5. deleteRateCenter
  6. deleteVoiceProviderRate
  7. updateCallDetailRecord
  8. updateRateCenter
  9. updateVoiceProviderRate

Changes to Existing Mutations

  1. createAccountOneTimeTransaction
    1. The account_voice_service_details optional input field is newly added.
  2. createCallDetailRecordImport
    1. The voice_provider_id input field is newly added and is required.
    2. For each list item provided in the call_detail_records input field:
      1. The originating_number and receiving_number input fields are now required.
      2. The originating_country and receiving_country input fields are removed.
      3. The answered_at input field is removed.
  3. createDid
    1. The country and subdivision input fields are removed.
    2. The rate_center_id input field is newly added and is required.
    3. The number input value must be unique across all DIDs for all voice providers.
  4. createScheduledEvent
    1. The account_voice_service_details optional input field is newly added.
  5. createVoiceProviderRateImport
    1. The voice_provider_id field is newly added and is required.
    2. The charge_percent input field is newly added and is required.
    3. For each list item provided in the rates input field:
      1. The country input field is removed.
  6. createVoiceServiceGenericParameter
    1. The default_quantity input field has been deprecated. Use backfill_quantity instead.
    2. The backfill_quantity optional input field is newly added. One of backfill_quantity or default_quantity is required. New implementations should use backfill_quantity.
    3. The taxes optional input field is newly added.
  7. createVoiceProvider
    1. The name input value must be unique across all voice providers.
  8. createVoiceService
    1. The show_call_detail_records_on_invoice optional input field is newly added.
  9. deleteAccountService
    1. The account service must not have any active DID assignments.
  10. deleteVoiceProvider
    1. The voice provider must not have any DIDs.
  11. importDids
    1. The rate_center_id input field is newly added and is required.
    2. For each list item provided in the did input field:
      1. The country and subdivision input fields are removed.
      2. The number input value must be unique across all DIDs for all voice providers.
  12. updateDid
    1. The number, country, and subdivision input fields are removed.
    2. The rate_center_id input field is newly added.
  13. updateScheduledEvent
    1. The account_voice_service_details optional input field is newly added.
  14. updateVoiceService
    1. The show_call_detail_records_on_invoice optional input field is newly added.
  15. updateVoiceServiceGenericParameter
    1. The taxes optional input field is newly added.

How did we do?

Best Practices to Remain CPNI Compliant

Contact