Start discussion on the Verified Caller API parameters

[olsi-korkuti]

Problem description
Unclear which API parameters will be used.

Expected action
Discussion needed to review the documentation provided on PR #9 #20 and agree on the parameters

[GillesInnov35]

hi @olsi-korkuti , considering the 2 steps (operations) we might propose those first request body parameters

• registration
  - caller phone number
  - display branded name
  - action type
  - valid period
• pre-authorization (pre-anouncement)
  - caller phone number
  - called phone number

BR
Gilles

[olsi-korkuti]

Hi @GillesInnov35, thank you for you proposals!

As discussed in today's meeting below the proposals and comments (yet to agree on the naming of each parameter):

• Registration
  • caller phone number (agreed. Mandatory. Can have an additional optional alternate phonenumber, for cases when a small company is identified with PBX and extension number)
  • display branded name (agreed. Mandatory. )
  • action type (agreed. Mandatory. Can have 3 actions, for the company to declare Blocking or Not_branding when verification fails but also a No_Verify when a small company needs only call branding and no verification-call announcement)
  • valid period (to discuss next session as is unclear if this marks the time to live for the pre-announcement or the validity of registration)
  • ClientID (New proposal. Optional? To uniquely identify the company. Useful for reporting of branded calls for a certain company. Can be used at pre-announcement as well so no company impersonates another one by declaring their phone number)
  • Terminating Country (New proposal. For Company to specify for which markets they want branded calling for. Relevant for operators that have presence in many countries. Can be an array of countries. Optional. If not declared it can apply globally for all available markets)
  • Campaign (New proposal. Optional. Can be relevant for reporting purposes, stats like pickup rates per campaign etc. Companies often register many phone numbers and pool them to a campaign)

Note: A PartnerID parameter could be created and added to the Header from authentication of the API consumer (often an aggregator)

• Pre-authorization (Pre-anouncement)
  • caller phone number (agreed. Mandatory)
  • called phone number (agreed. Mandatory)
  • ClientID (New proposal. Optional? Parameter assigned/announced at registration. To be declared so no company impersonates another one by declaring their phone number. If that happens we can return an error)

[GillesInnov35]

Thanks alot @olsi-korkuti, I guess those parameters should cover most of needs. The valid period I mentionned in my proposal concerns the validity of the registration as it is a and not the TTL (which is a mandatory parameter to be stored ans perhaps also updated via the API). I was thinking that as it is a pay for use service, a validity period might be recorded.
I don't have detailed specifications of the Branded Calling solution so perhaps it's not required.
BR
Gilles

[alpaycetin74]

Hello, I would recommend using an absolute time stamp value to indicate the "expiry" of the registration. I personally prefer absolute timestamps over relative TTL values.

[GillesInnov35]

thanks @alpaycetin74 , in my mind validPeriod was something different from TTL (Time To Live). But it may not be useful to manage also such a valid period.

I would propose that TTL could be configure at the registration step but also updated at pre-authorization step .

• Pre-authorization (Pre-anouncement)
  • caller phone number (agreed. Mandatory)
  • called phone number (agreed. Mandatory)
  • ClientID (New proposal. Optional? Parameter assigned/announced at registration. To be declared so no company impersonates another one by declaring their phone number. If that happens we can return an error)
  • timeToLive

As you say, TTL should be a integer (time stamp in seconds for example).

WDYT ?

[stroncoso-quobis]

Hi team,

Sorry that I was OOO these weeks, but I found all basic mandatory parameters really accurate: aNumber, bNumber, action_type and the valid time for branded sessions: TTL. So, these are great.

I will add some extra comments

Regarding to registration params

Agree with all of them (even the optional newer ones), but...

I really didn't get the no_verify action type. We shouldn't allow no-verified calls that impersonate a company, If a small company needs to create a campaign for a bigger, already registered customer, then, they should use their authentication and their already onboard data.

Maybe I'm missing something here, but I really think that this could be a problem. What's the use case? A 3-party contact center? Why they don't use the authorized information of the main customer? 🤔 Why they won't be verified? Wouldn't this open up a possibility of phishing or spamming under the cover of not verifying the call?

As said, maybe, I'm missing something here

Regarding the pre-authorization params

I really like the clientId param that provide a cross-realtionship with the registration. I that line, I miss a "preAuthorizationId" parameter in the response. It won't harm, and it will allow, in the future, to validate SIP sessions based on a pre-shared token. This could be embedded into the SIP signaling (not required to define it right now).

So my purpose is to add a preAuthorizationId in the POST pre-announce response that identifies the pre-authorization command done previously.

Additional question: Don't we need also to include a text string for the call intention as part of the RCD to be displayed?

About time-to-live

UTC absolute timestamps will help to avoid confusions, I vote for that. Also, time references are inlcuded on commonalities, making reference to RFC3339 (example: 2018-04-05T17:31:00Z).

Also, IMHO I'm convinced that there is a valid time-to-live for the registration, when customer is able to pre-announce (eg.: 2-3 weeks), that the time-to-live of the pre-announce itself, that should be shorter.

--

Hope this helps, willing to join next conversations to try to clarify.
Also, to help us all, I already included all parameters discussed at #34

Best regards

[alpaycetin74]

Hello @stroncoso-quobis ,
to my knowledge do_not_verify is considered for smaller businesses, who do not have a call center or a sophisticated system to generate calls, like a local flower shop. The shop registers itself with the name "X Flower Shop" to improve business. But they don't have any people to organize the timing of their calls.

[DENGYONG18]

Hello @alpaycetin74. Originally, we did not consider flower shops or bakeries as target service recipients for our API, as our primary focus has been on large enterprises such as financial institutions, healthcare organizations, and commercial platforms. However, these small businesses use cases do exist. I recommend setting the no_verify parameter to optional for small businesses like flower shops and bakeries. For the alpha-release, I think it would be important to finalize the mandatory parameters first.

@stroncoso-quobis @GillesInnov35 @olsi-korkuti
I my opinion, at the pre-authorization step, I fully agree the four mandatory parameters as follows:

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

And at the registration step, I suggest that no_verify of active_type could be an optional parameters. I agree the following parameters:

• phoneNumber (Mandatory) & phoneNumberAlternate(Optional) pair
• display name (Mandatory)
• action type (Optional)
• ClientID (Mandatory)
• Terminating Country (Mandatory)
• CampaignName(Optional. I think it may be feasible to have one registration associated with multiple campaigns at the same time.）

ps：If we want to meet the Fall25 meta-release, we'd better to finalized the necessary parameters of Registration and Pre-authorization as soon as possible. Alpha-release M3 phase(June 21th) is a Key Node. :)

[DENGYONG18]

Hello @olsi-korkuti , in response to your antispoofing question in last meeting:

Actually, there is a call authentication process when a large enterprise's Call Center makes calls. During this process, the caller number (A-number) is strictly bound to parameters such as its associated IP address. If the TAS determines that the caller number does not match its pre-registered IP address, the call will be blocked. Only after the call process is successfully authenticated will the caller’s registered branded calling service be used. This ensures effective prevention of fraudulent activities during the use of the branded calling service.

Hope helpful for you. :)

[alpaycetin74]

yes, since verify_action parameter is optional, value DO_NOT_VERIFY could be removed from the range.
Absence of the verify_action parameter is already interpreted as DO_NOT_VERIFY

[DENGYONG18]

As far as I know, for the meta-realease, we need to make a tracker firstly.

I have received the notification:
"To be part of the Fall25 meta-release, for each API, the API yaml file need to be provided in line with the latest Commonalities and ICM (see Alpha releases on the Fall25 page for the reference) – I had a quick look, and the yaml files in the PRs need some alignment work. I recommend to look at the QualityOnDemand repository for examples.

For each API, also all the release assets need to be prepared and the first API release-candidate versions are due for the M3 date (June 21). A specific “release PR” (see documentation below) needs to be created that will be reviewed by release management team.
The API release process is described here: ReleaseManagement/documentation/API_Release_Guidelines.md – see section releasing an API step by step.

With additional information on the Wiki here: API Release Process (CAMARA Wiki)"

But I'm sorry, I'm not clear the process.