client.reports

Scheduled reports, previews and runs. These methods are on client.reports, where client is a MoreVoice client (see the Python SDK). On AsyncMoreVoice the same methods are awaited. Each one returns the response object and raises an exception 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.

client.reports

def catalog(self, *, language: _m.ReportsCatalogLanguage | Unset = "en", more_voice_version: str | Unset = UNSET) -> _m.ReportCatalog

client.reports.catalog() · await async_client.reports.catalog() · GET /reports/catalog · API reference

Parameters

Name	Type	Required	Description
language	"he" | "en"	no	The language of names and descriptions (default en).

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

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report_catalog = client.reports.catalog()
print(report_catalog)

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.

client.reports

def create(self, body: _m.ReportsCreateBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.Report

client.reports.create() · await async_client.reports.create() · POST /reports · API reference

Request body

Field	Type	Required	Description
name	string	yes	—
widgets	object[]	yes	—
cadence	object	yes	—
enabled	boolean	no	—
filters	object	no	—
formats	object	no	Default: email and PDF.
language	"he" | "en"	no	Default he.
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.
recipients	object[]	no	—

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

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report = client.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",
        },
    ],
})
print(report)

delete()

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

client.reports

def delete(self, id: str, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.DeletedReport

client.reports.delete() · await async_client.reports.delete() · DELETE /reports/{id} · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A report ID (rpt_…).

Returns

DeletedReport:

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

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

deleted_report = client.reports.delete("rpt_7Hk2Lm9Qp")
print(deleted_report)

download_run_csv()

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.

client.reports

def download_run_csv(self, id: str, *, more_voice_version: str | Unset = UNSET) -> str

client.reports.download_run_csv() · await async_client.reports.download_run_csv() · GET /report_runs/{id}/csv · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A report run ID (rptrun_…).

Returns

Nothing, on success.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

data = client.reports.download_run_csv("rptrun_7Hk2Lm9Qp")
print(data)

download_run_pdf()

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.

client.reports

def download_run_pdf(self, id: str, *, more_voice_version: str | Unset = UNSET) -> bytes

client.reports.download_run_pdf() · await async_client.reports.download_run_pdf() · GET /report_runs/{id}/pdf · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A report run ID (rptrun_…).

Returns

Nothing, on success.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

data = client.reports.download_run_pdf("rptrun_7Hk2Lm9Qp")
print(len(data), "bytes")

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.

client.reports

def list(self, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.Report]

client.reports.list() · await async_client.reports.list() · GET /reports · API reference

Parameters

Name	Type	Required	Description
limit	integer	no	How many objects to return, 1–100 (default 20).
starting_after	string	no	A cursor (next_cursor) or object ID: return the objects after it (older).
ending_before	string	no	A cursor or object ID: return the objects before it (newer).

Returns

A page of results (ReportList): data, has_more and next_cursor.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for report in client.reports.list():
    print(report)

list_runs()

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.

client.reports

def list_runs(self, id: str, *, limit: int | Unset = 20, starting_after: str | Unset = UNSET, ending_before: str | Unset = UNSET, more_voice_version: str | Unset = UNSET) -> AsyncPage[_m.ReportRun]

client.reports.list_runs() · await async_client.reports.list_runs() · GET /reports/{id}/runs · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A report ID (rpt_…).
limit	integer	no	How many objects to return, 1–100 (default 20).
starting_after	string	no	A cursor (next_cursor) or object ID: return the objects after it (older).
ending_before	string	no	A cursor or object ID: return the objects before it (newer).

Returns

A page of results (ReportRunList): data, has_more and next_cursor.

Example

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

for report in client.reports.list_runs("rpt_7Hk2Lm9Qp"):
    print(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.

client.reports

def preview(self, body: _m.ReportsPreviewBody | Mapping[str, Any], *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.ReportPreview

client.reports.preview() · await async_client.reports.preview() · POST /reports/preview · API reference

Request body

Field	Type	Required	Description
widgets	object[]	yes	—
cadence	object	no	A cadence to list the next three send times for.
filters	object	no	—
language	"he" | "en"	no	The language of labels in the result (default en).
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.
timezone	string	no	Default Asia/Jerusalem.

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

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report_preview = client.reports.preview({
    "language": "en",
    "period": "last7",
    "widgets": [
        {
            "key": "w1",
            "type": "kpis",
        },
    ],
})
print(report_preview)

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.

client.reports

def retrieve(self, id: str, *, more_voice_version: str | Unset = UNSET) -> _m.Report

client.reports.retrieve() · await async_client.reports.retrieve() · GET /reports/{id} · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A report ID (rpt_…).

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

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report = client.reports.retrieve("rpt_7Hk2Lm9Qp")
print(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.

client.reports

def send(self, id: str, body: _m.ReportSendParamsInput | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET, idempotency_key: str | Unset = UNSET) -> _m.ReportRun

client.reports.send() · await async_client.reports.send() · POST /reports/{id}/send · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A report ID (rpt_…).

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

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report_run = client.reports.send("rpt_7Hk2Lm9Qp", {})
print(report_run)

update()

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

client.reports

def update(self, id: str, body: _m.ReportsUpdateBody | Mapping[str, Any] | Unset = UNSET, *, more_voice_version: str | Unset = UNSET) -> _m.Report

client.reports.update() · await async_client.reports.update() · PATCH /reports/{id} · API reference

Parameters

Name	Type	Required	Description
id	str	yes	A report ID (rpt_…).

Request body

Field	Type	Required	Description
cadence	object	no	—
enabled	boolean	no	—
filters	object	no	—
formats	object	no	Default: email and PDF.
language	"he" | "en"	no	Default he.
name	string	no	—
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.
recipients	object[]	no	—
widgets	object[]	no	—

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

from morevoice import MoreVoice

client = MoreVoice()  # MOREVOICE_API_KEY from the environment

report = client.reports.update("rpt_7Hk2Lm9Qp", {
    "enabled": False,
})
print(report)