Add a callback flow to notify the enterprises when their verified calls are branded successfully

[GillesInnov35]

Problem description
Add a callback flow to notify enterprises when their verified calls have been branded successfully.

Possible evolution
add a new resource /subscription to the verifed Caller API based on Notification Subscription Template
https://github.com/camaraproject/Commonalities/blob/main/artifacts/camara-cloudevents/event-subscription-template.yaml

SubscriptionEventType proposal: org.camaraproject.verifiedcaller.v1.call-branded

Alternative solution

[rartych]

The whole guide is here: https://github.com/camaraproject/Commonalities/blob/main/documentation/CAMARA-API-Event-Subscription-and-Notification-Guide.md

[GillesInnov35]

@rartych , I've a question on subscription/config content.
What should be placed in CreateSubscriptionDetail block according to Commonalities ?
Is it what should be provided when a POST /cloud-event is done, for example information of concerned mobile phone number ?
see example bellow

[mohdfarhanakram]

Hi @GillesInnov35, jumping in with a consumer-side perspective - my background is in branded calling (FirstOrion), so this issue caught my eye.

On your direct question: CreateSubscriptionDetail is intentionally left as an empty stub in CAMARA_event_common.yaml#L142 - each API overrides it with its own event-specific fields. The Notification Guide confirms (config table) that subscriptionDetail is exactly where the resource identifier of the subscribed entity goes - device.phoneNumber in device-roaming-subscriptions, for example. So your screenshot is on the right track.

For org.camaraproject.verifiedcaller.v1.call-branded the open question is which identifier. From an integrator's point of view, registrationId` is already the natural handle - consumers receive it from POST /registrations and use it for every subsequent GET, PUT, and DELETE on /registrations/{registrationId}. Reusing it as the subscription scope means no new identifier for the consumer to track, and the subscription's lifecycle aligns 1:1 with the brand it's about:

CreateSubscriptionDetail:
  type: object
  required: [registrationId]
  properties:
    registrationId:
      type: string
      format: uuid
      description: Identifier of the Brand Registration whose call-branded events should be notified.
      example: "ea77c42f-fa5e-4612-cb43-d502ae794832"

This also fits the resource-based (explicit) subscription pattern in the guide, and per that section it would land in a separate file - verified-caller-subscriptions.yaml - alongside the existing brand-registration API.

A per-phoneNumber variant (mirroring device-roaming-subscriptions) is the alternative, but enterprises typically own many numbers under one brand, so it would force N subscriptions where one would do.

Curious what you and @rartych think. Happy to draft the YAML once there's agreement on direction.

[rartych]

There is a new PR camaraproject/Commonalities#612 that adds sample-implicit-events.yaml as the canonical template for the implicit-subscription pattern.

In implicit subscription you don't need to have CreateSubscription, but extend CreatePreAnnouncementRequest with sink attribute and add callbacks to POST /pre-announce.
This would create notfications for given request.
We can think also about creating notifications feature for brand registration, then all events related to given registrationId can be notified (including pre-anouncement requests).

BTW, the templates introduce using $ref for common schemas for CAMARA APIs - when Commonalites publish its release, then it should be easy to follow this pattern.

Event type is defined as follows: org.camaraproject.<api-name>.<event-version>.<event-name>, kebab-case is used, and event version usually started from 0 so the type should be like:

org.camaraproject.verified-caller.v0.call-branded

[GillesInnov35]

hi @mohdfarhanakram , @rartych , interesting the 2 options ...

@rartych , does it mean there are an explicit subscription definition (with a ne wresource /subscription to be detailes) ansd an implicit subscription defiinition in a POST /resource (for example pre-announce) by adding sink and sinkcredentials ?
I don't see where the cloud-event has been defined by the /pre-announce API consumer .

[alpaycetin74]

There is a new PR camaraproject/Commonalities#612 that adds sample-implicit-events.yaml as the canonical template for the implicit-subscription pattern.

In implicit subscription you don't need to have CreateSubscription, but extend CreatePreAnnouncementRequest with sink attribute and add callbacks to POST /pre-announce. This would create notfications for given request. We can think also about creating notifications feature for brand registration, then all events related to given registrationId can be notified (including pre-anouncement requests).

BTW, the templates introduce using $ref for common schemas for CAMARA APIs - when Commonalites publish its release, then it should be easy to follow this pattern.

Event type is defined as follows: org.camaraproject.<api-name>.<event-version>.<event-name>, kebab-case is used, and event version usually started from 0 so the type should be like:

org.camaraproject.verified-caller.v0.call-branded

Hello,
calls can also be branded without the need for pre-announcement. Pre-anouncement is only necessary when verifyCallerAction is defined in brand registration phase.
For that reason, I would prefer to link notification event to brand registration spec.

[alpaycetin74]

Hello again,

There is also an implicit subscription example in Quality on Demand API:

https://camaraproject.github.io/swagger-ui/?url=https://raw.githubusercontent.com/camaraproject/QualityOnDemand/r3.2/code/API_definitions/quality-on-demand.yaml

The client requests the creation of a data session with specific QoS parameters, and later receives notifications about the lifecycle of the session.

I think it is a better fit and also more lightweight to follow an implicit subscription approach, instead of creating an explicit subscription resource.

[GillesInnov35]

@alpaycetin74 , I see that when a event notifcation has been pushed
The notification will be sent as a CloudEvent compliant message

Do you know where the cloud event content should be described, for example data block.

[alpaycetin74]

Hello @GillesInnov35 , the spec is here:
https://github.com/camaraproject/Commonalities/blob/44e3f6d37462e8ca996b9050596623240f0e391d/artifacts/common/CAMARA_event_common.yaml

The description says "data" spec is left up to the specific API. In QoD case, the "data" content is fully QoD specific.
Thank you.

[rartych]

Hello, calls can also be branded without the need for pre-announcement. Pre-anouncement is only necessary when verifyCallerAction is defined in brand registration phase. For that reason, I would prefer to link notification event to brand registration spec.

Makes sense, then we can think of events like:

org.camaraproject.brand-registration.v0.registration - with events related to registration life-cycle management (it duplicates responses from Brand Registration API - do we need it?)
org.camaraproject.brand-registration.v0.call-branded - with events related to calls

Quality on Demand API is good example, but camaraproject/Commonalities#612 brings example of refactored API definition using CAMARA_event_common.yaml for common schemas.

In POST /registrations for brand-registration the following snippet from sample-implicit-events.yaml needs to be added :

 callbacks:
        notifications:
          "{$request.body#/sink}":
            post:
              summary: "notifications callback"
              description: |
                Important: this endpoint is to be implemented by the API consumer.
                The sample service server will call this endpoint whenever a
                sample service event occurs for a resource whose creation request registered a `sink`.
                `operationId` value will have to be replaced accordingly with WG API specific semantic.
              operationId: postNotification
              parameters:
                - $ref: "../common/CAMARA_common.yaml#/components/parameters/x-correlator"
              requestBody:
                required: true
                content:
                  application/cloudevents+json:
                    schema:
                      $ref: "#/components/schemas/ApiNotificationEvent"

And modiefied according to the needs - event details are defined similarly to ApiNotificationEvent and subsequent schemas.

[GillesInnov35]

@alpaycetin74 , @rartych , thanks that's clear.
Even if in my understanding the notification event type should be related to the concerned entity and so event type org.camaraproject.brand-registration.v0 should be related to Registration lifecycle, I support the idea to design branded-call event type in Registration API because in many cases pre-announce API may not to be implemented.