Product analytics

Generated from DialerDigital/core commit 0fc18008b3c8 — spec openapi/dialer-v1.yaml v0.134.0. Do not edit by hand; see How this reference is built. Download the OpenAPI spec.

Español

Product analytics and NPS inside the console, our own and with no third party (macro-tasks#876): usage events as keys of a closed catalog, and the NPS question for account administrators. Always on; it never carries a consumer's data.

Endpoints

Method	Path	Summary
POST	/v1/product-analytics/events	Record the calling user's console usage events
GET	/v1/product-analytics/nps	Is the NPS question due for the calling user?
POST	/v1/product-analytics/nps	Answer the NPS question, or dismiss it

Record the calling user's console usage events

POST /v1/product-analytics/events

The console reports which screen a user opened and which function they used. Each event is a KEY of a closed catalog (screen.<route> or feature.<function>): there is no free-text field, so no data of a consumer can travel in one. The server stamps the time and the tenant (the login's, never body input). Keys outside the catalog are dropped and counted in rejected, so a console newer than the server breaks nothing. At most 50 keys per request. Events are kept 180 days.

Needs a dashboard login: a dd_ key has no person behind it and is 403.

Request body (JSON, required)

Field	Type	Required	Description
events	array of string	yes

Responses

202

Accepted; how many keys were stored and how many were dropped.

Field	Type	Required	Description
accepted	integer	yes
rejected	integer	yes

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

403 — Forbidden

The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

Is the NPS question due for the calling user?

GET /v1/product-analytics/nps

due is true only for an account_admin whose last NPS record (an answer or a dismissal) is at least interval_days old, or who has none. Any other user gets due: false. Needs a dashboard login.

Responses

200

Whether to ask now.

Field	Type	Required	Description
due	boolean	yes
interval_days	integer	yes

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

403 — Forbidden

The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

Answer the NPS question, or dismiss it

POST /v1/product-analytics/nps

Send { "score": 0..10, "comment": "..." } (the comment is optional, at most 500 characters) or { "dismissed": true }. Both postpone the next question by interval_days. Only an account_admin answers (403 otherwise); asking again before the interval is 409. The comment is free text a person types: the console asks them not to put customer data in it.

Request body (JSON, required)

Field	Type	Required	Description
score	integer	no
comment	string	no
dismissed	boolean	no

Responses

201

The stored record.

Field	Type	Required	Description
response	object	yes
response.outcome	answered · dismissed	yes
response.score	integer,null	yes
response.comment	string,null	yes

400 — BadRequest

Malformed request (shape/type errors, invalid filters, bad timestamps).

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

401 — Unauthorized

Missing, unknown or revoked API key (or, on /v1/admin/*, a bad/unset admin token; on webhooks, a bad/missing signature). A dashboard session (ddu_) that a newer login of the same person ended answers the code session_superseded instead (tenant flag single_session_enforced), so the screen can say why it was signed out; a logout, an expired or an unknown token stay unauthorized.

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

403 — Forbidden

The tenant is suspended. A dashboard session (ddu_) of a tenant whose login policy (ADR 227) is in mode enforce answers 403 with the code login_policy_denied on a request from an address or at an hour the policy does not allow — the same body for both; the session is not revoked and a later request inside the policy goes through. A widget token (ddw_) of a seat is held to the same policy on every request (core#2406, flag widget_login_honors_policy). A synthetic (demo) tenant answers 403 with the code synthetic_tenant on every route that would reach a third party — manual dial, external transfer or conference leg, SMS send (core#2251, ADR #280 addendum). No payment changes it.

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

409 — Conflict

Invalid state transition, uniqueness conflict, or a seat that is busy/reserved.

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}