Verified Caller API- Pre-Authorization Proposal

[DENGYONG18]

What type of PR is this?

Add one of the following kinds:

• enhancement/feature

What this PR does / why we need it:

Proposal of a draft Verified Caller API yaml file, which could be discussed in the next discussion.

Which issue(s) this PR fixes:

Fixes #

Special notes for reviewers:

Changelog input

 release-note

Additional documentation

This section can be blank.

docs

[GillesInnov35]

Hello @DENGYONG18 , I see that there's already a yaml proposal from @alpaycetin74 which includes all parameters yet discussed.
BR
Gilles

[DENGYONG18]

Hello @GillesInnov35 , @alpaycetin74 proposed the yaml is about registration, my proposal is more similar to the "pre-announce" flow of your Branded Calling proposal. We want to discuss some details and make some expressions more standardized. :)

Actually, we think that the registration process is just a pre-production of the API functionality process and should not be part of it. But if you all agree that registration should be part of the API functionality process, that's OK.

[DENGYONG18]

We proposed a flow diagram on #33, which is more clearly.

If you guys are interested you can check it out. :)

[GillesInnov35]

@DENGYONG18, in my opinion registration should be also proposed in the API design even if it can be processes by another way.
In your pre-announced proposal I don't see any called phone number (what we named B-number). Could you detail where and how this information may be provided.
Thanks

[DENGYONG18]

Sorry, we initially defaulted to a generic strategy that only required an A-number. If we use a customized strategy for A-number and B-number, we do need to bind the A-number and B-number. We have updated the proposal.

[alpaycetin74]

Hello @DENGYONG18 , we are happy to discuss.
I see there are 3 different spec files under this PR, which is a bit confusing:

Could we have one spec file under this PR ? You can add commits to the PR, if you need to edit the file.
We have the biweekly meeting on Thursday 11:00 CET, if you could join. Thank you.
CC: @olsi-korkuti

[DENGYONG18]

Hello @alpaycetin74 , I've modified it to keep only the updated file. I'll join the meeting on Thursday ：）.

[GillesInnov35]

hi all, I see that verified-caller design is not aligned with what we've decided

• name of the verb/operation what POST /pre-announce
• parameters in the pre-announce request body were bellow

{
  "a-number": "+123456789",
  "b-number: "+123456789",
  "clientId": "string",
  "timeToLive": 30
}

am I wrong ?
we may update swagger design.

Thanks a lot Gilles

[DENGYONG18]

Hello all, I have updated the pre-authorization YAML, only retain the following four mandatory parameters：

caller phone number (Mandatory)
called phone number (Mandatory)
ClientID (Mandatory)
timeToLive (Mandatory)

[olsi-korkuti]

Hello all, I have updated the pre-authorization YAML, only retain the following four mandatory parameters：

caller phone number (Mandatory) called phone number (Mandatory) ClientID (Mandatory) timeToLive (Mandatory)

Hi @DENGYONG18 ,

I agree with Caller and Called Phone Numbers to be mandatory, but the ClientID and timeToLive I think we never agreed to have them mandatory but keep them optional. Here's why according to my opinion:

• ClientID is an important parameter that will increase security in usecase where two or more companies are onboarded and use the Pre-Announce API. They could not impersonate each other as they don't have the other's Client ID (even if they spoof the A-number). But to share the ClientID the companies will not always send it to the service provider (Telco) via Registration API. Maybe some companies dont want to use the Registration API at all and do it manually via a Front end portal. For that reason I think we should keep ClientID optional.

• Same goes for timeToLive. It should be optional because some Telcos might prefer to hardcode it or configure in the backend. Usually the timeToLive is a default value of around 30 seconds (which is enough time to wait for the call setup time and for network can verify).

• As per my comment in PR Verified Caller Flow #33 based on your proposal in the call flows, I have suggested to have a 5th optional parameter to support those implementations where the display name or additional text like "Call reason" to be announced dynamically via Pre-Announce API.

• In the 200 OK Response I also like optional preAnnounceId + TTL at Call Flow diagram #15 that would serve as tokens and provide the option for Telcos enhance their SIP protocols.

All please, let me know your thoughts, if you agree.

cc: @GillesInnov35 @alpaycetin74 @stroncoso-quobis

[eric-murray]

ClientID is an important parameter that will increase security in usecase where two or more companies are onboarded and use the Pre-Announce API.

Calling a parameter ClientID will just cause confusion with the client_id parameter used for client authentication / authorisation.

If it is something else, call it something else, and document it properly.

And if it actually is equivalent to the client_id used during client authentication, well you will already know it from the access token, so don't need to pass it again.

[GillesInnov35]

@eric-murray , no ClientID proposed by Vodafone is different from the ClientId generally given by the exposition gateway and included in the access token for authorization journey. You're right we should named differently the identifier which is the customer identifier in the partner system.

[alpaycetin74]

Should we just rename it to something else to avoid confusion, like customerId or brandId ? We hope we can raise a PR this week for the next public release.

[GillesInnov35]

@alpaycetin74 , customerId may be a good proposal. I see that the name of operation is smssend and not pre-announce as we agreed. We've also to align the specifications with Commonalities Fall25 I think.

[ECORMAC]

Hi,
Apologies for the late comment but was wondering about the "Called Phone Number" (B-number) being mandatory. What are the legal / Consentual consequences of this?
Branding is a calling party (A-number) service (from a core / 3GPP pespective), why is the B-number being distributed (and why is it mandatory-conditional perhaps if consent from B has been received)?

[GillesInnov35]

hello @ECORMAC , I've posted bellow comment in PR #40 which concerned /pre-announce step. It means that in our case the aggregator/reseller should never know b-number and in consequence pre-announce flow should involve only the consumer (call center for example) and operators.

hello, we have a request from our legal entity recommending that reseller/aggregator should never know b-number regarding GDPR. As the caller doesn't know which is the operator for b-number to directly call it, it would mean b-number should be hashed.
It seems to be much complex. Do you have such a recommendation ?

BR
Gilles

[olsi-korkuti]

why is the B-number being distributed (and why is it mandatory-conditional perhaps if consent from B has been received)?

Hi @ECORMAC , we're checking this with product and privacy if there are any concerns. If the consumption of the API to the carrier platform is directly from the Enterprise that places the calls, the propagation of the B-number should have no privacy concerns as the same is propagated via the voice call. It is needed to reconciliate the A-number, B-number of the API with the Calling number and Called number of the SIP Invite, like a 2-factor authentication.

But if a 3rd party manages the API and the Branding platform, one option is applying pseudonymization of the B-number if no lawful basis is valid.

[DENGYONG18]

Hello @olsi-korkuti, I'm sorry, I think I misunderstand your comments. I accept that ClientID(customerid) and timeToLive are not mandatory parameters.

I think the file of PR#46 is ok.