mv.reports

Scheduled reports, previews and runs. These methods are on mv.reports, where mv is your client (see the Node.js SDK). Each one returns the response object and throws when the API answers with an error.

catalog()

List the report widgets. The widgets a report can show, with the filters each honours; the periods and the cadences.

mv.reports.catalog(query?: NonNullable<ReportsCatalogData["query"]>, options?: RequestOptions): Promise<ReportsCatalogResponse>

GET /reports/catalog · API reference

Parameters

Name	Type	Required	Description
query.language	string	no	The language of names and descriptions (default en).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

ReportCatalog:

Field	Type	Description
object	"report_catalog"	Always report_catalog.
widgets	object[]	—
periods	("today" | "yesterday" | "last7" | "last30" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth")[]	—
frequencies	("daily" | "weekly" | "monthly")[]	—

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const reportCatalog = await mv.reports.catalog();
console.log(reportCatalog);

create()

Create a report. Schedules a report: it is computed and emailed to its recipients on its cadence (the first send is next_run_at). Needs a live key.

mv.reports.create(body: ReportsCreateData["body"], options?: RequestOptions): Promise<ReportsCreateResponse>

POST /reports · API reference

Parameters

Name	Type	Required	Description
body.name	string	yes
body.widgets	object[]	yes
body.cadence	object	yes
body.enabled	boolean	no
body.filters	object	no
body.formats	object	no	Default: email and PDF.
body.language	"he" | "en"	no	Default he.
body.period	"today" | "yesterday" | "last7" | "last30" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth"	no	The window each report covers, in its time zone: today, yesterday, last7, last30, thisWeek, lastWeek, thisMonth or lastMonth. Default yesterday.
body.recipients	object[]	no
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options.headers["Idempotency-Key"]	string	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

Report:

Field	Type	Description
object	"report"	Always report.
id	string	A report ID (prefix rpt_).
livemode	boolean	true in live mode, false in test mode.
name	string	—
enabled	boolean	Disabled reports are not sent on their schedule (they can still be sent now).
widgets	object[]	—
period	"today" | "yesterday" | "last7" | "last30" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth"	The window each report covers, in its time zone: today, yesterday, last7, last30, thisWeek, lastWeek, thisMonth or lastMonth.
filters	object	—
cadence	object	—
recipients	object[]	—
formats	object	—
language	"he" | "en"	—
owner_id	string | null	usr_… ID.
next_run_at	string | null	—
last_run_at	string | null	—
last_run	object | null	The latest run (list responses only; null on others).
created	string	An ISO-8601 timestamp in UTC.
updated	string	An ISO-8601 timestamp in UTC.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const report = await mv.reports.create({
  cadence: {
    frequency: "daily",
    time: "08:00",
    timezone: "Asia/Jerusalem",
  },
  formats: {
    email: true,
    pdf: true,
  },
  name: "Daily contact-centre summary",
  period: "yesterday",
  recipients: [
    {
      type: "email",
      value: "ops@example.com",
    },
  ],
  widgets: [
    {
      key: "w1",
      type: "kpis",
    },
    {
      key: "w2",
      params: {
        sla_sec: 20,
      },
      type: "queues",
    },
  ],
});
console.log(report);

delete()

Delete a report. Deletes the report, its runs and their stored files. Needs a live key.

mv.reports.delete(id: ReportsDeleteData["path"]["id"], options?: RequestOptions): Promise<ReportsDeleteResponse>

DELETE /reports/{id} · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A report ID (rpt_…).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options.headers["Idempotency-Key"]	string	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

DeletedReport:

Field	Type	Description
object	"report"	Always report.
id	string	A report ID (prefix rpt_).
deleted	true	—

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const deletedReport = await mv.reports.delete("rpt_7Hk2Lm9Qp");
console.log(deletedReport);

downloadRunCsv()

Download a run’s CSV. The CSV stored for a run (404 when the report has no CSV format, or no storage bucket is configured). Needs a live key.

mv.reports.downloadRunCsv(id: ReportsDownloadRunCsvData["path"]["id"], options?: RequestOptions): Promise<ReportsDownloadRunCsvResponse>

GET /report_runs/{id}/csv · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A report run ID (rptrun_…).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

Nothing, on success.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const data = await mv.reports.downloadRunCsv("rptrun_7Hk2Lm9Qp");
console.log(data);

downloadRunPdf()

Download a run’s PDF. The PDF stored for a run (404 when the report has no PDF format, or no storage bucket is configured). Needs a live key.

mv.reports.downloadRunPdf(id: ReportsDownloadRunPdfData["path"]["id"], options?: RequestOptions): Promise<ReportsDownloadRunPdfResponse>

GET /report_runs/{id}/pdf · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A report run ID (rptrun_…).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

Nothing, on success.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const data = await mv.reports.downloadRunPdf("rptrun_7Hk2Lm9Qp");
console.log(data);

list()

List reports. Returns a page of Report objects, newest first. Pass next_cursor as starting_after for the next page; the SDKs iterate every page for you.

mv.reports.list(query?: NonNullable<ReportsListData["query"]>, options?: RequestOptions): PagedList<ReportsListResponse["data"][number], NonNullable<ReportsListData["query"]>>

GET /reports · API reference

Parameters

Name	Type	Required	Description
query.limit	integer	no	How many objects to return, 1–100 (default 20).
query.starting_after	string	no	A cursor (next_cursor) or object ID: return the objects after it (older).
query.ending_before	string	no	A cursor or object ID: return the objects before it (newer).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

A PagedList: await it for the first page, for await it for every item.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

for await (const report of mv.reports.list()) {
  console.log(report);
}

listRuns()

List a report’s runs. Returns a page of ReportRun objects, newest first. Pass next_cursor as starting_after for the next page; the SDKs iterate every page for you. Answers 404 with the code resource_missing when nothing has this ID in this organisation and mode.

mv.reports.listRuns(id: ReportsListRunsData["path"]["id"], query?: NonNullable<ReportsListRunsData["query"]>, options?: RequestOptions): PagedList<ReportsListRunsResponse["data"][number], NonNullable<ReportsListRunsData["query"]>>

GET /reports/{id}/runs · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A report ID (rpt_…).
query.limit	integer	no	How many objects to return, 1–100 (default 20).
query.starting_after	string	no	A cursor (next_cursor) or object ID: return the objects after it (older).
query.ending_before	string	no	A cursor or object ID: return the objects before it (newer).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

A PagedList: await it for the first page, for await it for every item.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

for await (const report of mv.reports.listRuns("rpt_7Hk2Lm9Qp")) {
  console.log(report);
}

preview()

Preview report data. Computes widgets for a period now and returns the data (nothing is stored or sent). With cadence, also the next three send times. Needs a live key.

mv.reports.preview(body: ReportsPreviewData["body"], options?: RequestOptions): Promise<ReportsPreviewResponse>

POST /reports/preview · API reference

Parameters

Name	Type	Required	Description
body.widgets	object[]	yes
body.cadence	object	no	A cadence to list the next three send times for.
body.filters	object	no
body.language	"he" | "en"	no	The language of labels in the result (default en).
body.period	"today" | "yesterday" | "last7" | "last30" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth"	no	The window each report covers, in its time zone: today, yesterday, last7, last30, thisWeek, lastWeek, thisMonth or lastMonth. Default yesterday.
body.timezone	string	no	Default Asia/Jerusalem.
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options.headers["Idempotency-Key"]	string	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

ReportPreview:

Field	Type	Description
object	"report_preview"	Always report_preview.
livemode	boolean	true in live mode, false in test mode.
period	object	—
generated_at	string	An ISO-8601 timestamp in UTC.
widgets	object[]	—
upcoming_runs	string[]	The next three send times of cadence, when one was sent.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const reportPreview = await mv.reports.preview({
  language: "en",
  period: "last7",
  widgets: [
    {
      key: "w1",
      type: "kpis",
    },
  ],
});
console.log(reportPreview);

retrieve()

Retrieve a report. Returns the Report object. Answers 404 with the code resource_missing when nothing has this ID in this organisation and mode.

mv.reports.retrieve(id: ReportsRetrieveData["path"]["id"], options?: RequestOptions): Promise<ReportsRetrieveResponse>

GET /reports/{id} · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A report ID (rpt_…).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

Report:

Field	Type	Description
object	"report"	Always report.
id	string	A report ID (prefix rpt_).
livemode	boolean	true in live mode, false in test mode.
name	string	—
enabled	boolean	Disabled reports are not sent on their schedule (they can still be sent now).
widgets	object[]	—
period	"today" | "yesterday" | "last7" | "last30" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth"	The window each report covers, in its time zone: today, yesterday, last7, last30, thisWeek, lastWeek, thisMonth or lastMonth.
filters	object	—
cadence	object	—
recipients	object[]	—
formats	object	—
language	"he" | "en"	—
owner_id	string | null	usr_… ID.
next_run_at	string | null	—
last_run_at	string | null	—
last_run	object | null	The latest run (list responses only; null on others).
created	string	An ISO-8601 timestamp in UTC.
updated	string	An ISO-8601 timestamp in UTC.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const report = await mv.reports.retrieve("rpt_7Hk2Lm9Qp");
console.log(report);

send()

Send a report now. Computes the report for its period, stores the files and emails every recipient; returns the run when it finished. Send an Idempotency-Key: a retry with the same key returns the same run instead of emailing again. A second send of the same report while one is in progress is a 409. Needs a live key.

mv.reports.send(id: ReportsSendData["path"]["id"], body?: ReportsSendData["body"], options?: RequestOptions): Promise<ReportsSendResponse>

POST /reports/{id}/send · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A report ID (rpt_…).
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options.headers["Idempotency-Key"]	string	no	A unique key (for example a UUID) that makes this request safe to retry: for 24 hours, a retry with the same key and parameters returns the first response instead of acting twice.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

ReportRun:

Field	Type	Description
object	"report_run"	Always report_run.
id	string	A report run ID (prefix rptrun_).
livemode	boolean	true in live mode, false in test mode.
report_id	string	A report ID (prefix rpt_).
trigger	string	scheduled, manual (sent now) or test.
status	string	running, sent, partial (some recipients or the PDF failed) or failed.
period_from	string | null	—
period_to	string | null	—
recipients	string[]	—
deliveries	object[]	—
artifacts	object	Stored files you can download (GET /v1/report_runs/{id}/pdf|csv).
error	string | null	—
started_at	string	An ISO-8601 timestamp in UTC.
finished_at	string | null	—

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const reportRun = await mv.reports.send("rpt_7Hk2Lm9Qp", {});
console.log(reportRun);

update()

Update a report. Only the fields you send change (filters, recipients, widgets and cadence are replaced as a whole). Needs a live key.

mv.reports.update(id: ReportsUpdateData["path"]["id"], body?: ReportsUpdateData["body"], options?: RequestOptions): Promise<ReportsUpdateResponse>

PATCH /reports/{id} · API reference

Parameters

Name	Type	Required	Description
id	string	yes	A report ID (rpt_…).
body.cadence	object	no
body.enabled	boolean	no
body.filters	object	no
body.formats	object	no	Default: email and PDF.
body.language	"he" | "en"	no	Default he.
body.name	string	no
body.period	"today" | "yesterday" | "last7" | "last30" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth"	no	The window each report covers, in its time zone: today, yesterday, last7, last30, thisWeek, lastWeek, thisMonth or lastMonth. Default yesterday.
body.recipients	object[]	no
body.widgets	object[]	no
options.headers["MoreVoice-Version"]	string	no	The API version to use for this request. Defaults to the version the API key is pinned to.
options	RequestOptions	no	idempotencyKey, extra headers and an abort signal: see retries and idempotency.

Returns

Report:

Field	Type	Description
object	"report"	Always report.
id	string	A report ID (prefix rpt_).
livemode	boolean	true in live mode, false in test mode.
name	string	—
enabled	boolean	Disabled reports are not sent on their schedule (they can still be sent now).
widgets	object[]	—
period	"today" | "yesterday" | "last7" | "last30" | "thisWeek" | "lastWeek" | "thisMonth" | "lastMonth"	The window each report covers, in its time zone: today, yesterday, last7, last30, thisWeek, lastWeek, thisMonth or lastMonth.
filters	object	—
cadence	object	—
recipients	object[]	—
formats	object	—
language	"he" | "en"	—
owner_id	string | null	usr_… ID.
next_run_at	string | null	—
last_run_at	string | null	—
last_run	object | null	The latest run (list responses only; null on others).
created	string	An ISO-8601 timestamp in UTC.
updated	string	An ISO-8601 timestamp in UTC.

Example

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const report = await mv.reports.update("rpt_7Hk2Lm9Qp", {
  enabled: false,
});
console.log(report);