Dashboard

Update dashboard card

Updates writable fields on the given dashboard card.

Automatically generated cards on a dashboard that has not been customized do not have IDs and cannot be updated via this endpoint. To update such a card, first update the dashboard (POST /projects/<project_id>/dashboards/<dashboard_id>, even with no fields) to convert it to a custom dashboard, then update the card using the ID from the cards property of the response.

post/v1/projects/{project_id}/dashboards/{dashboard_id}/cards/{id}

Request

  • Base URL: https://api.telerivet.com
  • URL: https://api.telerivet.com/v1/projects/{project_id}/dashboards/{dashboard_id}/cards/{id}
  • Auth: one of:
    • HTTP basic
    • OAuth 2 (authorization code, authorization URL https://telerivet.com/oauth/authorize, token URL https://api.telerivet.com/oauth/token)

Path parameters

project_idstring required

ID of the Project

dashboard_idstring required

ID of the Dashboard

idstring required

ID of the DashboardCard

Request body

titlestring

Title of the card. If no title has been set, a default title is displayed based on the card type.

orderinteger

Sort order of the card on the dashboard (cards are displayed in ascending order)

widthinteger

Width of the card in pixels, or null if the card has not been resized

heightinteger

Height of the card in pixels, or null if the card has not been resized

configobject

Type-specific configuration parameters for the card. Only returned when retrieving a single card by ID or querying the cards on a dashboard. When updating a card, parameters omitted from config keep their current values.

messages card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>messages.new</code>, <code>messages.export</code>, <code>messages.stats</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the messages card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>messages.todaycounts</code> - Messages sent and received today by type (expands to multiple statistics, one for each direction/type combination) -

  • <code>messages.scheduled</code> - Scheduled messages -

  • <code>messages.scheduledtoday</code> - Messages scheduled for today -

  • <code>messages.convtoday</code> - Conversations today -

  • <code>messages.activeconv</code> - Active conversations -

  • <code>messages.starred</code> - Starred messages -

  • <code>messages.broadcaststoday</code> - Broadcasts sent today -

  • <code>messages.status</code> - All messages with a particular status - <code>status</code>: <code>queued</code>, <code>failed</code>, <code>not_delivered</code>, etc.

  • <code>messages.statustoday</code> - Messages today with a particular status - <code>status</code>: <code>failed</code>, <code>not_delivered</code>, <code>service_error</code>, etc.

  • <code>messages.labelcount</code> - Messages with a particular label - <code>label_id</code>: ID of the label

contacts card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>contacts.add</code>, <code>contacts.import</code>, <code>contacts.export</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the contacts card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>contacts.total</code> - Total number of contacts -

  • <code>contacts.incomingtoday</code> - Contacts heard from today -

  • <code>contacts.outgoingtoday</code> - Contacts contacted today -

  • <code>contacts.createdtoday</code> - Contacts created today -

  • <code>contacts.groupmembers</code> - Contacts in a particular group - <code>group_id</code>: ID of the group

  • <code>contacts.viewcount</code> - Contacts matching custom filters - <code>title</code>: displayed title; <code>filters</code>: object of conditions that contacts must match, in the same format as the <code>filters</code> of a dynamic group (see project.createGroup)

data_tables card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>datatables.add</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the data_tables card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>tables.recentlyupdated</code> - Rows in recently updated data tables (expands to multiple statistics, one for each of the 5 most recently-updated data tables) -

  • <code>tables.rows</code> - Rows in a particular data table - <code>table_id</code>: ID of the data table

  • <code>tables.viewrows</code> - Rows in a particular data table view - <code>view_id</code>: ID of the data table view; <code>title</code>: displayed title

airtime card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>airtime.send</code>, <code>airtime.stats</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the airtime card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>airtime.txtoday</code> - Airtime transactions today -

  • <code>airtime.spenttoday</code> - Airtime spent today -

  • <code>airtime.balance</code> - Current balance with airtime providers -

messages_chart card

<th> Parameter </th><th> Description </th>

  • <code>statistic</code> - Value to chart: <code>count</code> (number of messages), <code>num_parts</code> (number of SMS parts), <code>duration</code> (call duration), or <code>price.<currency></code> (total price of messages in a particular currency, e.g. <code>price.USD</code>, where <code><currency></code> is a 3-letter ISO currency code in which messages in the project have been priced)

  • <code>group_ids</code> - Array of series group IDs determining how messages are grouped into chart series: <code>type</code>, <code>direction</code>, <code>status</code>, <code>source</code>, <code>simulated</code>, <code>gateway</code>, <code>network</code>, <code>currency</code>, <code>link</code>, <code>user</code>, <code>phone</code>, <code>service</code>

  • <code>filters</code> - Object of filter conditions on the messages included in the chart, e.g. <code>{"dir": "incoming", "type": "sms"}</code>. Each key is the filter parameter for a group that must be included in <code>group_ids</code>: <code>type</code> (message type, e.g. <code>sms</code>, <code>call</code>), <code>dir</code> (<code>incoming</code> or <code>outgoing</code>), <code>status</code> (message status, e.g. <code>sent</code>, <code>delivered</code>, <code>failed</code>), <code>source</code> (e.g. <code>phone</code>, <code>web</code>, <code>api</code>, <code>service</code>), <code>simulated</code> (bool), <code>gateway</code> (gateway ID), <code>mccmnc</code> (mobile network code), <code>currency</code>, <code>link</code> (<code>clicked</code>, <code>not_clicked</code>, or <code>no_link</code>), <code>user</code>, <code>phone</code>, <code>service</code> (IDs). Each value is a single value or an array of values to match.

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

airtime_chart card

<th> Parameter </th><th> Description </th>

  • <code>statistic</code> - Value to chart: <code>count</code> (number of successful transactions), <code>topup_value.<currency></code> (total value transferred, e.g. <code>topup_value.KES</code>), or <code>price.<currency></code> (total price of transactions, e.g. <code>price.USD</code>), where <code><currency></code> is a 3-letter ISO currency code in which transactions in the project have been valued or priced

  • <code>group_ids</code> - Array of series group IDs: <code>airtime.billing</code>, <code>airtime.status</code>, <code>airtime.country</code>, <code>airtime.productid</code>, <code>airtime.category</code>

  • <code>filters</code> - Object of filter conditions on the transactions included in the chart. Each key is the filter parameter for a group that must be included in <code>group_ids</code>: <code>internal_billing</code> (bool), <code>status</code> (e.g. <code>successful</code>, <code>failed</code>, <code>cancelled</code>), <code>country</code> (country code), <code>product_id</code>, <code>provider_category</code>. Each value is a single value or an array of values to match.

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

contacts_chart card

<th> Parameter </th><th> Description </th>

  • <code>series</code> - Array of up to 10 data series to chart (the same keys as the <code>series</code> parameter of project.getContactStats): each item is either <code>total</code> (the total number of contacts in the project) or the ID of a contact group (the number of contacts in that group)

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

data_table_chart card

<th> Parameter </th><th> Description </th>

  • <code>series</code> - Array of up to 10 data series to chart (the same keys as the <code>series</code> parameter of project.getDataTableStats): each item is the ID of a data table or data table view (the number of rows in that table or view)

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

data_table_summary card

<th> Parameter </th><th> Description </th>

  • <code>table_id</code> - ID of the data table

  • <code>stats_variable</code> - The custom variable (field) of the data table to count rows by, e.g. <code>region</code> (without the <code>vars.</code> prefix used in <code>filters</code>)

  • <code>chart_type</code> - <code>pie</code> or <code>bar</code>

  • <code>sort</code> - Sort order of the values: <code>count</code> (by number of rows) or <code>value</code>

  • <code>num_values</code> - Maximum number of values to display (int)

  • <code>filters</code> - Object of conditions that rows must match to be counted. To filter by a custom variable (field) of the table, precede the field name with <code>vars.</code> (e.g. <code>{"vars.region": "North"}</code>); other supported keys are <code>view</code> (ID of a data table view whose rows should be counted), <code>id</code>, <code>contact_id</code>, <code>contact_name</code>, <code>from_number</code>, <code>time_created</code>, and <code>time_updated</code>. Each value is either a value to match exactly, or an object with an operator such as <code>ne</code>, <code>prefix</code>, <code>gte</code>, <code>lt</code>, <code>exists</code>, or <code>not_exists</code> as the key (e.g. <code>{"vars.age": {"gte": 18}}</code>).

poll card

<th> Parameter </th><th> Description </th>

  • <code>service_id</code> - ID of the poll service

  • <code>chart_type</code> - <code>pie</code>, <code>bar</code>, or <code>none</code>

campaign_calendar card

<th> Parameter </th><th> Description </th>

  • <code>period</code> - <code>month</code>, <code>week</code>, or <code>day</code>

  • <code>status</code> - Only display campaigns with this status: <code>draft</code>, <code>scheduled</code>, <code>sent</code>, or <code>pending_review</code> (null to display all campaigns)

campaigns card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>campaigns.new</code>, <code>custom</code> (see <strong>Links</strong> below).

services card

<th> Parameter </th><th> Description </th>

  • <code>filters</code> - Object of filter conditions for the services displayed on the card: <code>trigger</code> (<code>incoming_message</code>, <code>manual</code>, <code>recurring</code>, <code>message_action</code>, <code>contact_action</code>, <code>outgoing_call</code>, <code>message_status</code>, <code>link</code>, <code>data_row_action</code>, <code>project_action</code>, or <code>webhook</code>), <code>template</code> (bool; if true, only display custom templates), <code>tag</code> (only display services with this tag)

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>services.add</code>, <code>custom</code> (see <strong>Links</strong> below).

phones card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>phones.add</code>, <code>phones.routes</code>, <code>custom</code> (see <strong>Links</strong> below).

account card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>account.billing</code>, <code>account.users</code>, <code>account.api</code>, <code>custom</code> (see <strong>Links</strong> below).

custom card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>custom</code> (see <strong>Links</strong> below).

Links

Link types other than custom take no parameters. A custom link has the following params:

<th> Param </th><th> Description </th>

  • <code>title</code> - Displayed link text

  • <code>link_type</code> - Determines how <code>url_suffix</code> is interpreted: <code>project_relative</code> (default), <code>account_relative</code>, <code>user_relative</code>, or <code>external</code> (see below)

  • <code>url_suffix</code> - The link destination, whose format depends on <code>link_type</code>:<br />

  • <code>project_relative</code>: a path relative to the project's URL in the Telerivet web app (e.g. <code>messages</code> or <code>contacts?f[group]=CG2ad0100821a98bea</code> links to <code>https://telerivet.com/p/&lt;project url_slug>/messages</code> or <code>.../contacts?...</code>)<br />

  • <code>account_relative</code>: a path relative to the organization's URL in the web app (<code>https://telerivet.com/a/&lt;organization id>/</code>), e.g. <code>billing</code><br />

  • <code>user_relative</code>: a path relative to the URL of the user viewing the dashboard (<code>https://telerivet.com/u/&lt;username&gt;/</code>), e.g. <code>settings</code><br />

  • <code>external</code>: an absolute URL, e.g. <code>https://example.com/report</code>

  • <code>open_in_new_tab</code> - If true, the link opens in a new browser tab (bool)

Example request

{
  "title": "Registrations by Region",
  "order": 1,
  "width": 400,
  "height": 300
}

Response

Successful response

idstring nullable

ID of the card (null for an automatically generated card on a dashboard that has not been customized yet; cards receive IDs the first time the dashboard is updated via the API or web app)

typestring

Type of the card:

  • messages_chart: time series chart of messages sent and received
  • contacts_chart: time series chart of the number of contacts
  • airtime_chart: time series chart of airtime transactions
  • data_table_chart: time series chart of the number of rows in data tables
  • data_table_summary: pie or bar chart of the number of rows in a data table by the value of a particular field
  • messages: statistics about messages (e.g. number of messages sent and received today)
  • contacts: statistics about contacts (e.g. number of contacts in particular groups)
  • data_tables: statistics about data tables (e.g. number of rows in particular tables)
  • airtime: statistics about airtime/value transfers
  • campaigns: summary of recent, upcoming, and ongoing campaigns
  • campaign_calendar: calendar of sent and scheduled campaigns
  • phones: list of routes and their current status
  • services: list of active services
  • poll: charts of responses for each question in a poll
  • account: basic account information for the organization
  • custom: custom card with links
  • setup: project setup progress (automatically generated; cannot be added)
titlestring

Title of the card. If no title has been set, a default title is displayed based on the card type.

orderinteger

Sort order of the card on the dashboard (cards are displayed in ascending order)

widthinteger nullable

Width of the card in pixels, or null if the card has not been resized

heightinteger nullable

Height of the card in pixels, or null if the card has not been resized

configobject

Type-specific configuration parameters for the card. Only returned when retrieving a single card by ID or querying the cards on a dashboard. When updating a card, parameters omitted from config keep their current values.

messages card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>messages.new</code>, <code>messages.export</code>, <code>messages.stats</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the messages card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>messages.todaycounts</code> - Messages sent and received today by type (expands to multiple statistics, one for each direction/type combination) -

  • <code>messages.scheduled</code> - Scheduled messages -

  • <code>messages.scheduledtoday</code> - Messages scheduled for today -

  • <code>messages.convtoday</code> - Conversations today -

  • <code>messages.activeconv</code> - Active conversations -

  • <code>messages.starred</code> - Starred messages -

  • <code>messages.broadcaststoday</code> - Broadcasts sent today -

  • <code>messages.status</code> - All messages with a particular status - <code>status</code>: <code>queued</code>, <code>failed</code>, <code>not_delivered</code>, etc.

  • <code>messages.statustoday</code> - Messages today with a particular status - <code>status</code>: <code>failed</code>, <code>not_delivered</code>, <code>service_error</code>, etc.

  • <code>messages.labelcount</code> - Messages with a particular label - <code>label_id</code>: ID of the label

contacts card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>contacts.add</code>, <code>contacts.import</code>, <code>contacts.export</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the contacts card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>contacts.total</code> - Total number of contacts -

  • <code>contacts.incomingtoday</code> - Contacts heard from today -

  • <code>contacts.outgoingtoday</code> - Contacts contacted today -

  • <code>contacts.createdtoday</code> - Contacts created today -

  • <code>contacts.groupmembers</code> - Contacts in a particular group - <code>group_id</code>: ID of the group

  • <code>contacts.viewcount</code> - Contacts matching custom filters - <code>title</code>: displayed title; <code>filters</code>: object of conditions that contacts must match, in the same format as the <code>filters</code> of a dynamic group (see project.createGroup)

data_tables card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>datatables.add</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the data_tables card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>tables.recentlyupdated</code> - Rows in recently updated data tables (expands to multiple statistics, one for each of the 5 most recently-updated data tables) -

  • <code>tables.rows</code> - Rows in a particular data table - <code>table_id</code>: ID of the data table

  • <code>tables.viewrows</code> - Rows in a particular data table view - <code>view_id</code>: ID of the data table view; <code>title</code>: displayed title

airtime card

<th> Parameter </th><th> Description </th>

  • <code>value_stats</code> - Array of the statistics displayed on the card, in display order. Each item is an object with a <code>type</code> (see below) and, for statistic types that take parameters, a <code>params</code> object.

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>airtime.send</code>, <code>airtime.stats</code>, <code>custom</code> (see <strong>Links</strong> below).

Available value_stats types for the airtime card:

<th> Type </th><th> Statistic </th><th> Params </th>

  • <code>airtime.txtoday</code> - Airtime transactions today -

  • <code>airtime.spenttoday</code> - Airtime spent today -

  • <code>airtime.balance</code> - Current balance with airtime providers -

messages_chart card

<th> Parameter </th><th> Description </th>

  • <code>statistic</code> - Value to chart: <code>count</code> (number of messages), <code>num_parts</code> (number of SMS parts), <code>duration</code> (call duration), or <code>price.<currency></code> (total price of messages in a particular currency, e.g. <code>price.USD</code>, where <code><currency></code> is a 3-letter ISO currency code in which messages in the project have been priced)

  • <code>group_ids</code> - Array of series group IDs determining how messages are grouped into chart series: <code>type</code>, <code>direction</code>, <code>status</code>, <code>source</code>, <code>simulated</code>, <code>gateway</code>, <code>network</code>, <code>currency</code>, <code>link</code>, <code>user</code>, <code>phone</code>, <code>service</code>

  • <code>filters</code> - Object of filter conditions on the messages included in the chart, e.g. <code>{"dir": "incoming", "type": "sms"}</code>. Each key is the filter parameter for a group that must be included in <code>group_ids</code>: <code>type</code> (message type, e.g. <code>sms</code>, <code>call</code>), <code>dir</code> (<code>incoming</code> or <code>outgoing</code>), <code>status</code> (message status, e.g. <code>sent</code>, <code>delivered</code>, <code>failed</code>), <code>source</code> (e.g. <code>phone</code>, <code>web</code>, <code>api</code>, <code>service</code>), <code>simulated</code> (bool), <code>gateway</code> (gateway ID), <code>mccmnc</code> (mobile network code), <code>currency</code>, <code>link</code> (<code>clicked</code>, <code>not_clicked</code>, or <code>no_link</code>), <code>user</code>, <code>phone</code>, <code>service</code> (IDs). Each value is a single value or an array of values to match.

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

airtime_chart card

<th> Parameter </th><th> Description </th>

  • <code>statistic</code> - Value to chart: <code>count</code> (number of successful transactions), <code>topup_value.<currency></code> (total value transferred, e.g. <code>topup_value.KES</code>), or <code>price.<currency></code> (total price of transactions, e.g. <code>price.USD</code>), where <code><currency></code> is a 3-letter ISO currency code in which transactions in the project have been valued or priced

  • <code>group_ids</code> - Array of series group IDs: <code>airtime.billing</code>, <code>airtime.status</code>, <code>airtime.country</code>, <code>airtime.productid</code>, <code>airtime.category</code>

  • <code>filters</code> - Object of filter conditions on the transactions included in the chart. Each key is the filter parameter for a group that must be included in <code>group_ids</code>: <code>internal_billing</code> (bool), <code>status</code> (e.g. <code>successful</code>, <code>failed</code>, <code>cancelled</code>), <code>country</code> (country code), <code>product_id</code>, <code>provider_category</code>. Each value is a single value or an array of values to match.

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

contacts_chart card

<th> Parameter </th><th> Description </th>

  • <code>series</code> - Array of up to 10 data series to chart (the same keys as the <code>series</code> parameter of project.getContactStats): each item is either <code>total</code> (the total number of contacts in the project) or the ID of a contact group (the number of contacts in that group)

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

data_table_chart card

<th> Parameter </th><th> Description </th>

  • <code>series</code> - Array of up to 10 data series to chart (the same keys as the <code>series</code> parameter of project.getDataTableStats): each item is the ID of a data table or data table view (the number of rows in that table or view)

  • <code>rollup</code> - Time period per data point: <code>day</code>, <code>week</code>, <code>month</code>, or <code>year</code>

  • <code>date_range_mode</code> - <code>recent</code> (the most recent <code>prev_days</code> days) or <code>fixed</code> (from <code>start_date</code> to <code>end_date</code>)

  • <code>prev_days</code> - Number of days to display when <code>date_range_mode</code> is <code>recent</code> (int)

  • <code>start_date</code> - First date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>end_date</code> - Last date to display (<code>YYYY-MM-DD</code>) when <code>date_range_mode</code> is <code>fixed</code>

  • <code>cumulative</code> - If true, each data point shows the cumulative total up to that date (bool)

data_table_summary card

<th> Parameter </th><th> Description </th>

  • <code>table_id</code> - ID of the data table

  • <code>stats_variable</code> - The custom variable (field) of the data table to count rows by, e.g. <code>region</code> (without the <code>vars.</code> prefix used in <code>filters</code>)

  • <code>chart_type</code> - <code>pie</code> or <code>bar</code>

  • <code>sort</code> - Sort order of the values: <code>count</code> (by number of rows) or <code>value</code>

  • <code>num_values</code> - Maximum number of values to display (int)

  • <code>filters</code> - Object of conditions that rows must match to be counted. To filter by a custom variable (field) of the table, precede the field name with <code>vars.</code> (e.g. <code>{"vars.region": "North"}</code>); other supported keys are <code>view</code> (ID of a data table view whose rows should be counted), <code>id</code>, <code>contact_id</code>, <code>contact_name</code>, <code>from_number</code>, <code>time_created</code>, and <code>time_updated</code>. Each value is either a value to match exactly, or an object with an operator such as <code>ne</code>, <code>prefix</code>, <code>gte</code>, <code>lt</code>, <code>exists</code>, or <code>not_exists</code> as the key (e.g. <code>{"vars.age": {"gte": 18}}</code>).

poll card

<th> Parameter </th><th> Description </th>

  • <code>service_id</code> - ID of the poll service

  • <code>chart_type</code> - <code>pie</code>, <code>bar</code>, or <code>none</code>

campaign_calendar card

<th> Parameter </th><th> Description </th>

  • <code>period</code> - <code>month</code>, <code>week</code>, or <code>day</code>

  • <code>status</code> - Only display campaigns with this status: <code>draft</code>, <code>scheduled</code>, <code>sent</code>, or <code>pending_review</code> (null to display all campaigns)

campaigns card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>campaigns.new</code>, <code>custom</code> (see <strong>Links</strong> below).

services card

<th> Parameter </th><th> Description </th>

  • <code>filters</code> - Object of filter conditions for the services displayed on the card: <code>trigger</code> (<code>incoming_message</code>, <code>manual</code>, <code>recurring</code>, <code>message_action</code>, <code>contact_action</code>, <code>outgoing_call</code>, <code>message_status</code>, <code>link</code>, <code>data_row_action</code>, <code>project_action</code>, or <code>webhook</code>), <code>template</code> (bool; if true, only display custom templates), <code>tag</code> (only display services with this tag)

  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>services.add</code>, <code>custom</code> (see <strong>Links</strong> below).

phones card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>phones.add</code>, <code>phones.routes</code>, <code>custom</code> (see <strong>Links</strong> below).

account card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>account.billing</code>, <code>account.users</code>, <code>account.api</code>, <code>custom</code> (see <strong>Links</strong> below).

custom card

<th> Parameter </th><th> Description </th>
  • <code>links</code> - Array of shortcut links displayed on the card. Each item is an object with a <code>type</code> and, for link types that take parameters, a <code>params</code> object. Available link types: <code>custom</code> (see <strong>Links</strong> below).

Links

Link types other than custom take no parameters. A custom link has the following params:

<th> Param </th><th> Description </th>

  • <code>title</code> - Displayed link text

  • <code>link_type</code> - Determines how <code>url_suffix</code> is interpreted: <code>project_relative</code> (default), <code>account_relative</code>, <code>user_relative</code>, or <code>external</code> (see below)

  • <code>url_suffix</code> - The link destination, whose format depends on <code>link_type</code>:<br />

  • <code>project_relative</code>: a path relative to the project's URL in the Telerivet web app (e.g. <code>messages</code> or <code>contacts?f[group]=CG2ad0100821a98bea</code> links to <code>https://telerivet.com/p/&lt;project url_slug>/messages</code> or <code>.../contacts?...</code>)<br />

  • <code>account_relative</code>: a path relative to the organization's URL in the web app (<code>https://telerivet.com/a/&lt;organization id>/</code>), e.g. <code>billing</code><br />

  • <code>user_relative</code>: a path relative to the URL of the user viewing the dashboard (<code>https://telerivet.com/u/&lt;username&gt;/</code>), e.g. <code>settings</code><br />

  • <code>external</code>: an absolute URL, e.g. <code>https://example.com/report</code>

  • <code>open_in_new_tab</code> - If true, the link opens in a new browser tab (bool)

dashboard_idstring

ID of the dashboard this card belongs to

project_idstring

ID of the project this card belongs to

time_createdinteger nullable

Time the card was created in Telerivet (null for an automatically generated card on a dashboard that has not been customized)

time_updatedinteger nullable

Time the card was last updated in Telerivet

Example response

{
  "id": "DC5c9155e33a1d0c1a",
  "type": "messages_chart",
  "title": "Registrations by Region",
  "order": 1,
  "width": 400,
  "height": 300,
  "dashboard_id": "DB2ad0100821a98bea",
  "project_id": "PJ2ad0100821a98bea",
  "time_created": 1392254503,
  "time_updated": 1392254503
}

Changes

No recorded changes to this operation across all 1 revision of this API.