Create wip version of call pre-announcement API

[alpaycetin74]

What type of PR is this?

• enhancement/feature

What this PR does / why we need it:

To establish the API Signature for the Verified Caller Call Pre-Announcement API

Which issue(s) this PR fixes:

Fixes #24

Special notes for reviewers:

.

Changelog input

.

Additional documentation

[github-actions]

🦙 MegaLinter status: ✅ SUCCESS

Descriptor	Linter	Files	Fixed	Errors	Elapsed time
✅ ACTION	actionlint	2		0	0.03s
✅ OPENAPI	spectral	2		0	3.33s
✅ REPOSITORY	git_diff	yes		no	0.01s
✅ REPOSITORY	secretlint	yes		no	0.71s
✅ YAML	yamllint	2		0	0.53s

See detailed report in MegaLinter reports

MegaLinter is graciously provided by

[alpaycetin74]

Dear @camaraproject/verified-caller_codeowners , for your review please. Thank you.
CC: @olsi-korkuti

[GillesInnov35]

@alpaycetin74 , sorry I didn't see your PR I left a comment in PR #43
I would prefer to use a operation /pre-announce rather than a resource.
your proposal

paths:
  /pre-announcements:
    post:

mine

paths:
  /pre-announce:
    post:

Thanks Cetin

[alpaycetin74]

@alpaycetin74 , sorry I didn't see your PR I left a comment in PR #43 I would prefer to use a operation /pre-announce rather than a resource. your proposal

paths:
  /pre-announcements:
    post:

mine

paths:
  /pre-announce:
    post:

Thanks Cetin

Thank you, @GillesInnov35 . I renamed as such. I also changed clientId to customerId.

[alpaycetin74]

Could you review this as well, @stroncoso-quobis ? Thank you

[stroncoso-quobis]

Couple of comments after the review of #40 and comparing with this one:

• If we approve this PR we will have two YAML files. The discussion is still ongoing as per last meeting notes... My impression is that a single file will help to identify these two functionalities as a whole: registrar and announce. But is just a comment, not a request.
• No GET Action? a GET action could help to clarify how a validation is done for SIP calling... We can separate it as an enhancement on a different PR.

Also, I included of inlne comments about:

• The usage of customerId that I will suggest to improve using registrationId
• Parameter name announcementId rename to preAnnounceId
• Resourrece name pre-anounce rename to registrations (plural)

Please, @alpaycetin74 , take a look and let me know your impressions. I will review again after your comments.
Best regards,

[stroncoso-quobis]

• Following the same "uniformization" rule: why pre-anounce (singular) but registrations plural?
• Should not this be pre-announces ?

[alpaycetin74]

This is the imperative form of the verb, it was a comment by @GillesInnov35 .
My initial proposal was preannouncements (plural noun). I would agree to either option.

[stroncoso-quobis]

• Not really sure about the usage of customerId on the API POST request. Why not user registrationId, as it is the result of the brand registration API? Also, customerId is an optional parameter in both request and response. This must be an error.
• I get from Start discussion on the Verified Caller API parameters #24 that customerId is an optional parameter for branding, but shouldn't be more secure if we use the response of the registration itself for that purpose?

[alpaycetin74]

I see your point, passing the registration id looks safe and reasonable. And the registration record already points to the clientId if there is one.
@olsi-korkuti any comments here ?
the pre-announcement parameters then would be a number, b number, registration id, ttl

[olsi-korkuti]

Hi @alpaycetin74 @stroncoso-quobis
yes I also like the registrationID. But how would it work on those solutions where a carrier (or integrator) does not use the Registration API but prefer to store the numbers via a GUI? I believe in the proposal from China Telecom the Registration API was left out of scope.

We need to make sure that PreAnnouncement API works for all implementations. But we can still call the parameter registrationID which is defined from the Enterprise either manually or as a result of the Registration API, right?!

[alpaycetin74]

well yes, the registrationIdm may have been assigned to the caller as a part of their brand registration which was handled in another process. In any case the parameter should be mandatory as it establishes the basis for the caller's claim to brand a specific call.
In the description we can explain this registrationId may be a the result of the registration api, if used by the service provider or any other process. In the latter case, the service provider is responsible for delivering it to the caller.

[stroncoso-quobis]

• Not really sure about the response parameter name announcementId. As the API POST action resource is pre-announce, shouldn't be more accurate to use preAnnounceId as the corresponding identifier parameter (as done with registrations <-> regsitrationId)?

[alpaycetin74]

maybe preAnnouncementId is the best :)

[DENGYONG18]

Hello @alpaycetin74 , announcementId and timeToLive in the Response are not mandatory right?

[olsi-korkuti]

Hi @DENGYONG18 that's correct. The response attributes will be optional and could serve as an opportunity for future implementations where Operator/Network vendors could be inject them as a token to the SIP call.

[eric-murray]

@alpaycetin74
Can you change the file extension to .yaml? Thanks.

[olsi-korkuti]

@alpaycetin74 @GillesInnov35 @stroncoso-quobis @DENGYONG18

Thank you for today's session. I have published the minutes of meetings. https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/156729345/2025-07-03+VerifiedCaller+Minutes

Main topic to be reviewed and agreed and merge this PR. Please lets close the format and options for some agreed fields.

Pre-Announce Request

• callingParticipant - Mandatory field. Is the Caller’s MSISDN. Should match with the phoneNumber registered for Branding.

• RegistrationID - Mandatory. Replaces customerID/clientID previously proposed. Was previously agreed as optional (as clientID) but finally decided to make it mandatory in order to have at least 2 mandatory parameters for a spoof-free solution. This will serve as a pre-shared key associated to the brand during registration. If the Brand registers numbers via Register API, a “RegistrationID“ can be mapped to each individual phoneNumber.

• calledParticipant - Optional field. Was agreed to change from Mandatory to Optional to address privacy issue in some countries where sharing called number might not be allowed. Providing this attribute during pre-Announce would make the verification process more secure as each single call will be verified and not just the caller.

• timeToLive - Optional. Developer can announce how long the pre-announce is valid. Recommended to be in seconds enough to allow the voice call to reach the terminating network.

• strategy - Optional. Developers could announce the preferred branding strategy. Applicable when the operator makes available different implementations to brand the calls. For example verification via CNAM (Display name), SMS/RCS or RCD as drafted at IETF.

• dynamicDisplayName - Optional. This could be a dynamic display name field which gives the opportunity to some operators to use this as primary display name or overwrite the existing one during registration. Could be useful for short campaigns or providing more information in the display like the reason of call. In an RCD implementation the operator could decide to use this field as the subject field in the SIP Call Info header.

Pre-Announce Response

• preAnnouncementID - Optional field. Could serve as a pre-shared token provided by the operator to the Enterprise. when the Enterprises initiates the call the token could be added to the SIP headers. This would require to be adapted by the industry and a possible solution for standardisation (similar to STIR/SHAKEN in US).

• timestamp ?! - Optional. This should be the absolute timestamp (name TBD) in RFC3339 format. Can be returned to the developer to understand the timestamp of the valid time as announced via timeToLive in the request.

[alpaycetin74]

@alpaycetin74 Can you change the file extension to .yaml? Thanks.

sure, I'll do it amongst other changes.

[alpaycetin74]

@alpaycetin74 @GillesInnov35 @stroncoso-quobis @DENGYONG18

Thank you for today's session. I have published the minutes of meetings. https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/156729345/2025-07-03+VerifiedCaller+Minutes

• dynamicDisplayName - Optional. This could be a dynamic display name field which gives the opportunity to some operators to use this as primary display name or overwrite the existing one during registration. Could be useful for short campaigns or providing more information in the display like the reason of call. In an RCD implementation the operator could decide to use this field as the subject field in the SIP Call Info header.

myunderstanding is this field serves as a dynamic caller id, or sms message text depending on the strategy. And there could be other uses in the future. I'd recommend we rename it to something more generic, e.g. "dynamicInformation" ?

Pre-Announce Response

• timestamp ?! - Optional. This should be the absolute timestamp (name TBD) in RFC3339 format. Can be returned to the developer to understand the timestamp of the valid time as announced via timeToLive in the request.

should that be timeToLive (relative value as in the request), or a timestamp (absolute value). Either one is ok for me.

[GillesInnov35]

thanks @olsi-korkuti . I wonder if pre-announceId is a useful information ? From what I read the pre-annouce session is not always saved, and so no id will be generated. Do you know what this identifier could be used ?

[stroncoso-quobis]

Hi @alpaycetin74 ,

my understanding is this field serves as a dynamic caller id, or sms message text depending on the strategy. And there could be other uses in the future. I'd recommend we rename it to something more generic, e.g. "dynamicInformation" ?

🤔 not really sure. I'm in favor to add flexibility, but I would prefer if each field corresponds to a specific purpose. I will keep the easy clear displayName.

I did not recall the SMS text, we were designing just for the displayName only, as it was the request on this forum. It was my assumption that the SMS body is stored elsewhere or included on a separated SIP MESSAGE request.

Once said this. I fully open to include an optional smsBody field, or, better: leave it for next release, and go big. A wider concept could be to include a generic displayData object, that will depend on the strategy field. A dedicated JSON object that will bring all the flexibility that we want, but in my opinion, we should keep it simple for this first iteration.

--

should that be timeToLive (relative value as in the request), or a timestamp (absolute value). Either one is ok for me.

My vote for an absolute timestamp. Is up to the device to be correctly synchronized with the network time.

--

Regarding @GillesInnov35 question

I wonder if pre-announceId is a useful information ? From what I read the pre-annouce session is not always saved, and so no id will be generated. Do you know what this identifier could be used ?

The pre-announce is not always saved? I did not understand it in that way... But, yes, you are right, you can send an SMS, RCS and simply discard the pre-announce information... In that case, of course, this ID won't bring any useful info.
On the other side, if it is stored (DisplayName update or RCD), the preAnnounceId is just an optional exposure of this storage action to the API consumer, to be used on other future actions (like injection into SIP).

My intention was always to have a unique identifier of the pre-announce, store it and use in other contexts, for instance: accounting and token verification of future SIP calls.

[alpaycetin74]

oh ok @stroncoso-quobis , I understood the purpose wrong. I'll revert to displayName as before.
I agree with the idea about the strategy-based object structure. My understanding was a precursor to it. But we'll do this later.

[stroncoso-quobis]

Thanks @alpaycetin74 , let me known when you are ready to review and approve.
Best regards,

[alpaycetin74]

Ready for review now @olsi-korkuti @stroncoso-quobis @camaraproject/verified-caller_codeowners

[stroncoso-quobis]

LGTM!

POST parameters

201 Created response

IMHO it is a really great first version! 🎉
Thanks all for your contributions!

[olsi-korkuti]

thanks @olsi-korkuti . I wonder if pre-announceId is a useful information ? From what I read the pre-annouce session is not always saved, and so no id will be generated. Do you know what this identifier could be used ?

Hi @GillesInnov35, I assume the pre-announcementID wont be used by most of the Telcos due to difficulty of adoption, so in that case they wont need to store it.
If a Telco decides to use it (therefore provide the ID in the API response) they will ofcourse have to store its value to the DB along with the other parameters, calling and called number etc.

If the pre-announcement is injected to the SIP Invite headers (not sure if new or an existing field can be used in SIP), then it is used as a token together with calling number and reconciliated with the content in the Pre-Announce API DB. I think a good start for Telcos could be to adopt it for calls where A and B party belong both to them.

[olsi-korkuti]

Ready for review now @olsi-korkuti @stroncoso-quobis @camaraproject/verified-caller_codeowners

I believe we agreed to only have callingParticipant and registrationId as mandatory. I would make Strategy field optional, because most of the times the Operator will only have one implementation and will apply the default one.
The rest looks great!

[alpaycetin74]

Ready for review now @olsi-korkuti @stroncoso-quobis @camaraproject/verified-caller_codeowners

I believe we agreed to only have callingParticipant and registrationId as mandatory. I would make Strategy field optional, because most of the times the Operator will only have one implementation and will apply the default one. The rest looks great!

Are you ok with converting strategy to optional, @stroncoso-quobis ?

[olsi-korkuti]

@DENGYONG18 Could you also review this PR and #46 (comment) and let us know if this aligns also with the China Telecom proposal and implementation?

In the previous proposal and the documentation/API_documentation/Verified Caller API Introduction.pptx the below parameters were suggested:

I believe with the parameters we're agreeing today, I understand the implementation to brand via SMS is also supported.

• Strategy defines the implementation
• registrationID (mandatory) could correspond to the templatecode
• dynamicDisplayName could correspond to templateParams as they are both string. Is templateParmas supposed to present the text that will be displayed in the SMS/RCS for branding?

I understand that we are missing the Callbackurl string, but we can all work together on a version 2, to adopt the same.
I dont think there is any other attribute necessary to adopt a unique API, right?

Please review and let us know if we can unify everything under the same path /pre-announce: instead of using proprietary /smssend.

If you disagree then a second path could be added for version 2 of the API. Thank you!

[stroncoso-quobis]

Hi @alpaycetin74

Are you ok with converting strategy to optional, @stroncoso-quobis ?

Yes, I think that this is a first iteration. And the telco will use the default strategy on their backend.

For next releases, we can include a response strategy field where the telco can confirm the strategy used for your request. This will help to keep early adopters, but also to provide space for telcos that want to provide an extra step further.

• You don't specify the strategy: ok, telco will do what he prefers, or what's configured according your registration or contract.
• You specify the strategy: ok, I will check, and reply with NOT_SUPPORTED or just with the capabilities that I have.

Keeping it optional now is a way to speed up things, and in the very end, it does not require being mandatory, as far as the user and the telco are agreed in what is the "default" behavior.

We have time to decide in the future 👍

[alpaycetin74]

Thank you, I'll make it optional in the submission to the release candidate PR.

[GillesInnov35]

hello @ALL , I see that registrationId is mandatory. Perhaps I haven't read all discussions concerning this field, I'm sorry. But in my opinion this parameter should be optional. In some cases an API consumer won't start with a registration creation by the API but by another way. It means that in some cases the id won't be known by the consumer. WDYT ?

[stroncoso-quobis]

Hi @GillesInnov35 ,

We discussed it last meeting, but at the very end, maybe you left already... The main idea is to have a pre-register validation field, at least, one. The main discussion was to use clientId or registrationId...

• If you followed and implement the CAMARA VerifiedCaller Regsitration API, then, you will have a consistent registrationId field. Simply bring your previous returned data into this API.
• But, if you want an independent registration API you can use this field at your convenience, for instance, using a pre-known client or customer ID, or maybe using any other convention. It is up to the vendor. But we thought that a mandatory field that identify a previously registered caller is needed.

If not, how are you going to verify?, you don't have a pre-registration, you neither have a token, neither a limit on the TTL, neither a b-numer. You are simple saying that "a caller is calling", and in that case, why even bother to use this API? Simply use an SMS API, or send RCS APIs or simple call and hope for the best. My thought is that we need to put a limit somewhere, and a mandatory previous registration won't hurt, even if you decide to do your own pre-registration out of the CAMARA APIs.

And remember that this is a first iteration, we can keep discussing this point on a dedicated issue.

Best regards to all.

[GillesInnov35]

hi @stroncoso-quobis , thanks for your comment. I'm sorry I had to leave the last meeting before the end. I understand your answer.
I just pointed that mandatory couldn't change to optional after the first version (for backward compatibility). I thought that caller phone number could be also a key value when registration has been done out of CAMARA API.
BR
Gilles

[olsi-korkuti]

hello @ALL , I see that registrationId is mandatory. Perhaps I haven't read all discussions concerning this field, I'm sorry. But in my opinion this parameter should be optional. In some cases an API consumer won't start with a registration creation by the API but by another way. It means that in some cases the id won't be known by the consumer. WDYT ?

Hi @GillesInnov35,
exactly as Santiago explained. The registrationID can be used also from brands that dont use the Register API. It could be a pre-agreed identifier for each brand. Of course the solution is more secure if the Register API is used and a registrationID is assigned to each PhoneNumber.
The decision to make it mandatory came after the B-number was agreed to become optional (to consider per country privacy concerns). During implementation a Telco can probably choose to adjust the B-number as mandatory and registrationID optional.

[olsi-korkuti]

I have published the minutes of meetings. https://lf-camaraproject.atlassian.net/wiki/spaces/CAM/pages/156729345/2025-07-03+VerifiedCaller+Minutes

@GillesInnov35 as one of the actions of last Meeting was to propose you to become a codeowner can you please follow the same steps as we did with Cetin, by creating an issue then a PR for it like below?
Issue #17
PR #18

[GillesInnov35]

yes sure, thanks @olsi-korkuti

[GillesInnov35]

@olsi-korkuti , thanks a lot for your answer. I understand your meaning.

The decision to make it mandatory came after the B-number was agreed to become optional (to consider per country privacy concerns). During implementation a Telco can probably choose to adjust the B-number as mandatory and registrationID optional.

In my opinion mandatory is an impactful decision for the backend service because it couldn't be managed as an optional field if it has been declared as mandatory in the swagger file. It will also impact for example GSMA certification tests which are developped and based on CAMARA specifications.
As I said to @stroncoso-quobis I thought that the a-number (caller phone number) might be a unique key to find concerned Registration information if no registrationId is known.
But I'm not an expect of existing Branded Calling solution and implementation, and so I'll support the collegial decision.
BR
Gilles

[GillesInnov35]

@hdamker, may I ask you to create a PR link to issue #50 as it has been done for @alpaycetin74 #50. It has been approved during last meeting .
cc @olsi-korkuti , @alpaycetin74 , @DENGYONG18
Great thanks
Gilles

[hdamker]

@hdamker, may I ask you to create a PR link to issue #50 as it has been done for @alpaycetin74 #50. It has been approved during last meeting . cc @olsi-korkuti , @alpaycetin74 , @DENGYONG18 Great thanks Gilles

See #50 (comment) ... I won't do the PR (as I then won't be able to approve it anymore).

[olsi-korkuti]

In my opinion mandatory is an impactful decision for the backend service because it couldn't be managed as an optional field if it has been declared as mandatory in the swagger file. It will also impact for example GSMA certification tests which are developped and based on CAMARA specifications.

Hi @GillesInnov35 @stroncoso-quobis @DENGYONG18 @alpaycetin74 @camaraproject/verified-caller_codeowners

I have discussed thoroughly with the VF Product team (who are in liaison with VF Privacy, Regulation and other MNOs Product teams).
They strongly suggest to make the B-number Mandatory for the Pre-Announce API, and if we agree that we can put "registrationID" back to Optional.

After careful consideration and keeping in mind the adoption of this API I agree with this change.

If through this API we somehow "enable" the fraudsters to brand spoofed calls that has consequences for the MNOs.
If an operator only accepts the A-number that will not protect at all and as a result won't have adoption, below some usecases:

1- Banks can place thousands of calls a day from the same A-number, so they are practically at all times on call and the announcements are always active.
All a Fraudster need to do is, call by spoofing the A-number to the one of the bank, in a call within an interval of time to leave. The Branding Platform will check that A-number from SIP INVITE will match with the A-number pre-announced and due to successful match with provide the Bank Name in the presentation.

2- The same is valid for the usage of the Registration ID. As long as it is not sent via SIP INVITE header it is useless. The same Fraudster in usecase above all they have to do is try calling within that TTL interval.
The value of registration ID is to stop another API consumer to announce an A-number they don't own.

Regarding Privacy concern in each country, I think that is sensitive to only when 3rd parties are in the Pre-announce call flow who are not intended to "see" the B-number. That solution should stay out of scope of this Fall release. Afterall the Bank can decide to consume the API without a 3rd party. We can think of improving that later with some pseudonymization.
In worst case scenario, a country does not allow the API adoption due to B-number mandatory, but an A-number only solution is a worse trade-off, as might not even find adoption at all, or even worse is used and is exploited by Fraud.

Apologies for the forth and back on this topic. Please respond if you agree to make B-number mandatory and for convenience as per Gilles' proposal we can make registrationID optional, because with A-number, B-number and TTL the solution would be rock solid.

.

[GillesInnov35]

hi @olsi-korkuti , that is the first proposal I supported.
As you say, if a third party has been involved in call flow, Privacy rules aligment (legal team) will force the consumer to call each operator involved in the contract with the third party, won't it ?
In this call flow, problem is that 3rd party won't see any call, how will be managed usage/payment ? solution to be found.

Many Thanks
Gilles

[olsi-korkuti]

consumer to call each operator involved in the contract with the third party, won't it ?
In this call flow, problem is that 3rd party won't see any call, how will be managed usage/payment ? solution to be found.

Those are good questions. I think the simplest way, this will be solved contractually via legal teams where the 3rd parties should not persist the B numbers or use for any other purpose.

The other option, the Enterprise/Brand (API consumer) could call a Phone Lookup API to discover the owner of B-number and pre-announce the call directly to the Branding platform owned by the MNO. This could be to circumvent the 3rd party in those countries where privacy rules are strict.

Regarding monetisation, generally the service is charged per branded call and not per number of pre-announcements. Pre-announcements are only enablers to secure the call before branding it. If the calls fail to be branded they should not be charged. The Branding Platform (MNO) would charge the party they have a contract with (the brand or the reseller/aggregator).
In a future version for this API, we could work on a callback flow (similar to the one suggested by China Telecom), where the Network would notify if the call is branded and that can be used as a charging feed as well.

[stroncoso-quobis]

Hi team,

I don't agree, but I understand the situation, and if we have a majority that supports this change, I will abide by it without problems, the idea is to move in the right direction.

But the more we argue, the more sense it makes me a service discriminator, to be clear what you are getting in return for your pre-announce submit.

The strategy field that we started to discuss some time ago, I'm going to open a dedicated issue for that, hope it will be better.

Best regards,