Add a Call Reason field for /pre-announce endpoint

[mhfoo]

Problem description
Currently, the Brand is shown to the callee.

Possible evolution
In addition to the Brand, include a Call Reason field; to show to the callee, the reason of the call from the Brand.
Example: To indicate the subject of the call.

Alternative solution

Additional context
Call Reason is shown to callee, to increase the confidence level of the callee to pick up the call.

[alpaycetin74]

Hello @mhfoo ,
thank you for your interest.
Generically speaking, it is a single text for the device display.
We think we can handle this in 2 ways:

• Embed call reason in the registered displayName
• For a more dynamic, per-call approach, override the registered displayName with the dynamicDisplayName parameter: in pre-announcement phase:

pre-announcement spec available at: https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/VerifiedCaller/r1.3/code/API_definitions/verified-caller.yaml#/Create%20Pre-announcement/createPreAnnouncement

BR,
Cetin

[mhfoo]

Hi @alpaycetin74:

Generically speaking, it is a single text for the device display.

Is this based on Caller Name Presentation (CNAP) or Caller Name Delivery (CNAM)?

I was referring to the STIR/SHAKEN concept, where there is a placeholder for the Brand name, Brand logo and the call reason.

I would suggest the "call reason" to be a different field (for the purpose of STIR/SHAKEN) and if the MNO supports only Caller Name Presentation (CNAP) or Caller Name Delivery (CNAM), the MNO may concatenate the "call reason" with the Brand name.

[olsi-korkuti]

Hi @alpaycetin74:

Generically speaking, it is a single text for the device display.

Is this based on Caller Name Presentation (CNAP) or Caller Name Delivery (CNAM)?

I was referring to the STIR/SHAKEN concept, where there is a placeholder for the Brand name, Brand logo and the call reason.

I would suggest the "call reason" to be a different field (for the purpose of STIR/SHAKEN) and if the MNO supports only Caller Name Presentation (CNAP) or Caller Name Delivery (CNAM), the MNO may concatenate the "call reason" with the Brand name.

Hi @mhfoo ,
If I can clarify, the call reason field was discussed within this sub-project to be introduced for the purpose of STIR/SHAKEN (together with logo), in CNAM there's not enough characters to add it to the brand name.

Although the attributes in the API would need to be mapped to corresponding fields for Voice protocols such as SIP, so in practice an MNO could also decide to append the call reason content in a non-SIP payload.

As Cetin mentioned in this forum we need to agree weather we introduce this field on Brand Registration, Pre-announce or both

[GillesInnov35]

We see that sometimes the call reason is associated to a campaign. I wonder if it is really useful to introduce this field into the pre-announce flow.

[mhfoo]

@olsi-korkuti
My suggestion is to add the call reason to the pre-announce flow, which is assiocated between the callingParticipant and calledParticipant for that fixed duration. Using a bank as an example, the bank may call customer A regarding a loan application with a call reason text "RE: Loan Application", the bank may call customer B regarding a credit card application with a call reason text "RE: Credit Card Application". The /pre-announce API will be invoked with BRAND_DISPLAY first, then the caller will perform the actual phone call to the callee.

I am not familar with a use case where the call reason is "fixed" for a specific Brand; hence I do not think the call reason is required during the Brand Registration.

@GillesInnov35
The use cases above will set different call reasons, based on the customer follow up engagement by the bank.
If the idea is to set the call reason to be associated for a campaign, the marketing campaign would have a start and end date.

[GillesInnov35]

yes @mhfoo , in that case we should specify a new /campaigns resource to manage this entity with validPeriod and campaignId properties. We could also to be simplier add callReason field into the pre-announce resource. I support the second one.👍

[alpaycetin74]

hello, I'll soon be working on a PR to add call reason parameter to pre-announce resource, fyi. Thank you.

[alpaycetin74]

Hello @mohdfarhanakram , what is your experience for the maximum length of call reason parameter in practice? I did a bit of digging and it seems although there are no strict limits in sip and stir/shaken, there are limitations in devices and operator interconnects.
Anybody, please feel free to provide your experience for finding a safe length limit for the parameter. Thank you.

[mohdfarhanakram]

Hello @mohdfarhanakram , what is your experience for the maximum length of call reason parameter in practice? I did a bit of digging and it seems although there are no strict limits in sip and stir/shaken, there are limitations in devices and operator interconnects. Anybody, please feel free to provide your experience for finding a safe length limit for the parameter. Thank you.

Hi @alpaycetin74 from our branded-calling experience, 32 characters is a safe, reliable limit for the call reason.

As you noted, neither STIR/SHAKEN nor SIP mandates a maximum here - it's effectively a free-text string - so the ceiling is practical: device and operator-interconnect limits, plus what the handset renders before it truncates. 32 sits just above the legacy CNAM 15-char field and keeps the combined name + logo + reason compact, while still fitting useful phrases like "RE: Loan application" or "Suspected fraud alert".

I would suggest enforcing maxLength: 32 in the schema, so an over-long reason is rejected with a clear error rather than getting silently cut off on the device.

BR

[GillesInnov35]

hi @mohdfarhanakram , @alpaycetin74 , I agree with you @mohdfarhanakram, I support no silent truncation because too "dangerous ". Concerning maxLength value, I haven't got any feedback from product team. So maxLength: 32 seems to be good option.

Thanks

[alpaycetin74]

Thank you both, I am off this week but soon I'll raise a PR.