telerivet 1.8.5 → 1.9.6

data/lib/telerivet/organization.rb

@@ -40,8 +40,9 @@ class Organization < Entity
     #             is used when computing statistics by date.
     #     
     #     - url_slug
-    #         * Unique string used as a component of the project's URL in the Telerivet web app.
-    #             If not provided, a URL slug will be generated automatically.
+    #         * Unique string used as a component of the project's URL in the Telerivet web app
+    #             (required length: 3-18 characters). If not provided, a URL slug will be generated
+    #             automatically.
     #     
     #     - auto_create_contacts (bool)
     #         * If true, a contact will be automatically created for each unique phone number that
@@ -81,8 +82,34 @@ class Organization < Entity
     end
 
     #
-    # Retrieves information about the organization's service plan and account balance.
+    # Retrieves information about the organization's service plan, including pricing, billing
+    # period, current limits, enabled features, overage rates, and any minimum usage fees, as well
+    # as the current account balance and payment status.
     # 
+    # The `plan_limits` object specifies the maximum allowed usage per
+    # metric (e.g. messages per day, contacts, API requests per day) that is included as part of
+    # the `plan_price`. Unless otherwise specified, each limit is the total across all projects in
+    # the organization (except for `custom_actions`).
+    # 
+    # When usage reaches a limit, what happens depends on the metric
+    # and whether the `soft_limits` feature is enabled in `plan_features`. For some limits,
+    # additional usage is allowed and is billed based on `overage_rates` when the `soft_limits`
+    # feature is enabled. For other limits, additional usage is blocked until the plan is upgraded
+    # to increase the limits.
+    # 
+    # Additional details about how service plan limits are defined,
+    # including what happens when the limits are reached, can be found in the [User
+    # Guide](https://guide.telerivet.com/hc/en-us/articles/360038959631-Service-Plan-Limits).
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #     
+    #     - usage (bool)
+    #         * If true, the response also includes a `usage` object with the current usage count
+    #             for every key in `plan_limits` — equivalent to calling `getUsage` once per key but
+    #             in the same round-trip. Omit (or pass false) to skip the usage counters.
+    #         * Default:
+    #   
     # Returns:
     #     (associative array)
     #       - balance (string)
@@ -119,31 +146,222 @@ class Organization < Entity
     #       
     #       - plan_limits (Hash)
     #           * Object describing the limits associated with the current service plan. The
-    #               object contains the following keys: `phones`, `projects`, `active_services`,
-    #               `users`, `contacts`, `messages_day`, `stored_messages`, `data_rows`,
-    #               `api_requests_day`. The values corresponding to each key are integers, or null.
+    #               values are integers, or null. Either `external_messages_day` or
+    #               `external_messages_period` is included depending on the organization's billing
+    #               mode (per-day vs. per-plan-period messaging quota). Each key:
+    #               
+    #               - `contacts`: Stored contacts — The maximum number of contacts stored in your
+    #               contact database at any time. Each contact can have a name, phone number, and up
+    #               to 100 custom fields, and can be added to groups. By default, a contact is
+    #               automatically created for each phone number you communicate with, as long as there
+    #               is space in your contact database. Automatic contact creation can be disabled in
+    #               the project settings if you don't need to store contacts. You can send messages to
+    #               an unlimited number of different phone numbers if you don't store them in your
+    #               contact database.
+    #               - `phones`: Routes — The maximum number of different routes that your
+    #               organization uses to send or receive messages through Telerivet, including Android
+    #               phones, virtual numbers, alphanumeric sender IDs, SMS shortcodes, and integrations
+    #               with chat apps like WhatsApp. On service plans that support multiple routes, you
+    #               can distribute messages among different routes for higher volume, geographic
+    #               reach, or better rates.
+    #               - `active_services`: Active automated services — The number of automated
+    #               services that run in response to certain events, such as when a new message is
+    #               received, when a message's status changes, or when triggered by a user. Common
+    #               types of automations like polls and auto-replies can be created from built-in
+    #               templates. Custom actions can be created using a drag-and-drop flow builder,
+    #               JavaScript, or a webhook.
+    #               - `users`: User logins — The maximum number of user accounts you can add for
+    #               people in your organization to log in and use Telerivet. Each user account can
+    #               have its own permissions.
+    #               - `stored_messages`: Stored messages — The total number of messages stored in
+    #               your Telerivet account, including scheduled messages. You can delete old or
+    #               unneeded messages to stay under this limit.
+    #               - `service_invocations_day`: Daily service invocations — The maximum number of
+    #               times automated services can run per day, excluding Webhook API services. This
+    #               includes service rules triggered by incoming messages, scheduled triggers, and
+    #               manual invocations. The counter resets at midnight in your organization's
+    #               timezone.
+    #               - `api_requests_day`: Daily API requests — The maximum number of API requests
+    #               your organization can make per day, counting both REST API and Webhook API
+    #               requests. The quota resets daily at midnight in the organization's time zone. If
+    #               you pay Telerivet directly for each message, REST API requests to send messages,
+    #               and Webhook API requests to receive notifications of incoming messages and
+    #               delivery reports, are exempt from this limit.
+    #               - `projects`: Projects — Each project represents an independent mobile messaging
+    #               system. Each project has its own messages, contacts, routes, and services, and its
+    #               own set of user permissions. If necessary, you can add multiple projects under one
+    #               organization and one billing plan.
+    #               - `data_rows`: Rows in custom data tables — Custom data tables are used to store
+    #               responses to polls and other automated services. You can also import your own data
+    #               to build data-driven automations.
+    #               - `script_module_mb`: Cloud Script module storage quota (MB) — Storage quota for
+    #               Cloud Script modules — code modules that you push to Telerivet to run as part of
+    #               automated services. Measured as the total size of all module files across the
+    #               organization.
+    #               - `stored_file_mb`: File storage quota (MB) — Storage quota for files uploaded
+    #               to Telerivet, including media attachments sent or received in messages.
+    #               - `custom_actions`: Custom actions per service — The maximum number of custom
+    #               actions or conditions allowed per automated service. Custom actions extend
+    #               services with logic written in a drag-and-drop flow builder, JavaScript, or
+    #               webhooks. Plans with the Advanced Automation feature have no per-service limit.
+    #               - `groups`: Contact groups — The maximum number of contact groups. Groups are
+    #               used to organize contacts and to send messages to many recipients at once.
+    #               - `custom_contact_fields`: Custom contact fields — The maximum number of custom
+    #               fields that can be defined for contacts. Custom fields store extra information
+    #               about contacts beyond the built-in name and phone number — for example, an
+    #               account ID, language preference, or any project-specific attribute.
+    #               - `external_messages_day`: Included Messages/Day - Bring Your Own Connectivity —
+    #               The maximum number of messages that can be sent or received per day when using
+    #               your own connectivity provider or an Android phone with the Telerivet Gateway app
+    #               (not when paying Telerivet for each message). The counter resets at midnight in
+    #               your organization's timezone. This limit applies when the plan's billing mode has
+    #               a per-day messaging quota.
+    #               - `external_messages_period`: Included Messages/Plan Period - Bring Your Own
+    #               Connectivity — The maximum number of messages that can be sent or received per
+    #               plan period (typically monthly or yearly) when using your own connectivity
+    #               provider or an Android phone with the Telerivet Gateway app (not when paying
+    #               Telerivet for each message). This limit applies when the plan has a
+    #               per-plan-period messaging quota. Each sent or received SMS message part, voice
+    #               call, USSD session, chat app message, or MMS message is counted as one message;
+    #               multi-part SMS messages are counted based on the number of SMS parts in the
+    #               message.
+    #               - `ai_chat_credits_day`: AI chat credits/day
+    #       
+    #       - plan_features (Hash)
+    #           * Object describing which platform features are enabled for this organization. The
+    #               keys are string feature IDs and the values are booleans. Available features:
+    #               
+    #               - `direct_connectivity`: Direct Connectivity — Use Telerivet-managed phone
+    #               routes where Telerivet handles billing with upstream messaging gateways on your
+    #               behalf, instead of requiring you to bring your own gateway credentials.
+    #               - `airtime_transfer`: Airtime Topup & Transfer — Send airtime to prepaid mobile
+    #               phones as a reward or participation incentive, or top-up the airtime on your own
+    #               SIM card directly from Telerivet. (Requires Pro plan or above)
+    #               - `click_tracking`: Click Tracking — Shorten links and track which contacts
+    #               clicked a link in your message.
+    #               - `custom_gateway`: Custom Gateways — Integrate with an SMS shortcode or another
+    #               gateway API. Telerivet can integrate with both HTTP or SMPP messaging APIs, and
+    #               can configure VPN connections directly with mobile networks if necessary.
+    #               (Integration fee varies depending on API - contact us)
+    #               - `custom_logo`: Custom Logo — Replace the Telerivet logo in the web app with
+    #               your own logo. (Requires Pro plan or above)
+    #               - `custom_domain`: Custom Domain Name — Access your Telerivet account from your
+    #               own domain name like sms.example.com, and hide Telerivet branding from users.
+    #               Configure a custom domain for branded short links. (Contact us for pricing)
+    #               - `soft_limits`: Soft Limits — Allow exceeding your plan's daily, monthly, or
+    #               annual limits by paying for extra messages, API requests, or service invocations.
+    #               - `auto_resend`: Automatic Message Resend & Failover — Configure custom rules to
+    #               automatically resend failed messages and failover between routes. (Requires plan
+    #               with Advanced custom automation)
+    #               - `export_storage`: Cloud Data Export — Automatically export and backup
+    #               messages, contacts, and other data to the cloud. Connect your own Amazon Web
+    #               Services S3 account for data storage. (Requires plan with Advanced custom
+    #               automation)
+    #               - `static_ip_address`: Static IP Address — Configure Telerivet to use a static
+    #               IP address for outbound HTTP requests if you need to allow inbound traffic from
+    #               specific IP addresses in your firewall. (Requires plan with Advanced custom
+    #               automation)
+    #               - `script_modules`: Cloud Script Modules — Run Cloud Script API code from an
+    #               external codebase hosted on GitHub, or push code to Telerivet directly from your
+    #               development environment. Use source control to track version history. (Requires
+    #               plan with Advanced custom automation)
+    #               - `service_templates`: Service Templates — Create reusable automated services
+    #               that can be shared with multiple projects and organizations. (Contact us for
+    #               pricing)
+    #               - `single_sign_on`: SAML Single Sign-On — Allow users to log in via your
+    #               organization's single sign-on identity provider (SAML 2.0). (Contact us for
+    #               pricing)
+    #               - `contact_sync`: Contact Data Sync — Synchronize contact information and
+    #               opt-out status across multiple Telerivet projects. (Requires Growth plan or above)
+    #               - `external_airtime_providers`: External Airtime Providers — Configure airtime
+    #               providers in your projects using your own credentials with an external airtime
+    #               provider, in addition to (or instead of) Telerivet-managed airtime.
+    #               - `wire_payments`: Wire Payments — Pay Telerivet invoices via bank wire transfer
+    #               in addition to credit card and other online payment methods.
+    #               - `custom_dashboards`: Custom Dashboards — Create custom dashboards with charts
+    #               and metrics showing Telerivet usage and providing business intelligence about the
+    #               results of your campaigns. (Requires Pro plan or above)
+    #               - `branded_short_links`: Branded Short Links — Configure a custom domain name
+    #               for short links, instead of using the default domain (rvt.me). (Requires Growth
+    #               plan or above)
+    #               - `custom_solutions`: Custom Solution Development — Work with Telerivet's
+    #               professional services team to implement a custom solution for your business needs.
+    #               (Contact us for pricing)
+    #       
+    #       - overage_rates (Hash)
+    #           * Per-unit overage rates billed when usage exceeds the corresponding plan limit.
+    #               Only present when the `soft_limits` feature is enabled in `plan_features` —
+    #               without `soft_limits`, reaching a limit blocks further usage until the counter
+    #               resets rather than accruing per-unit charges, so the rates would not apply and the
+    #               field is omitted entirely. When present, each entry is an object with `amount` and
+    #               `currency` properties, where `amount` is the positive per-unit cost in `currency`,
+    #               or null if no rate is configured. Keys:
+    #               
+    #               - `message`: Cost per external (bring your own connectivity) message sent or
+    #               received beyond the daily limit (`plan_limits.external_messages_day`) or
+    #               per-period limit (`plan_limits.external_messages_period`).
+    #               - `api_request`: Cost per REST API request beyond `plan_limits.api_requests_day`.
+    #               - `service_invocation`: Cost per automated-service invocation beyond
+    #               `plan_limits.service_invocations_day`.
+    #       
+    #       - minimum_usage_fees (array)
+    #           * Array of minimum usage fees configured for this organization. Each fee
+    #               guarantees a minimum amount of usage-based billing per billing cycle (the period
+    #               from `plan_start_time` to `plan_end_time`, recurring per `plan_rrule`) for a
+    #               particular set of usage categories — for example, a monthly minimum on
+    #               per-message fees via a particular provider. If the actual usage-based charges
+    #               across the fee's categories add up to less than the minimum during a billing
+    #               cycle, the shortfall is billed up to the minimum amount, and added to the
+    #               organization's recurring billing alongside the plan price. If actual usage exceeds
+    #               the minimum, no additional minimum-usage charge is applied for that cycle. The
+    #               array is empty when no minimum usage fees are configured.
     #       
     #       - recurring_billing_enabled (boolean)
     #           * True if recurring billing is enabled, false otherwise
     #       
     #       - auto_refill_enabled (boolean)
     #           * True if auto-refill is enabled, false otherwise
+    #       
+    #       - usage (Hash)
+    #           * Object mapping each `plan_limits` key to the current integer usage count for
+    #               that metric — present only when the request was made with `usage=true`. Includes
+    #               either `external_messages_day` or `external_messages_period` (matching whichever
+    #               the organization's billing mode produces in `plan_limits`), not both. Reset
+    #               schedules and the per-service `custom_actions` semantics described on
+    #               [getUsage](#Organization.getUsage) apply here as well.
     #
-    def get_billing_details()
-        data = @api.do_request("GET", get_base_api_path() + "/billing")
+    def get_billing_details(options = nil)
+        data = @api.do_request("GET", get_base_api_path() + "/billing", options)
         return data
     end
 
     #
-    # Retrieves the current usage count associated with a particular service plan limit. Available
-    # usage types are `phones`, `projects`, `users`, `contacts`, `messages_day`,
-    # `stored_messages`, `data_rows`, and `api_requests_day`.
+    # Retrieves the current usage count associated with a particular service plan limit.
+    # 
+    # The available `usage_type` values are the same as the keys returned
+    # in `plan_limits` from the [getBillingDetails](#Organization.getBillingDetails) method, so
+    # each call returns the current value of the corresponding limit's counter.
+    # 
+    # Notes:
+    # 
+    # - `external_messages_day` and `external_messages_period` reset on
+    # different schedules: daily counters reset at midnight in the organization's timezone; period
+    # counters reset at the start of the next plan period (`plan_start_time` to `plan_end_time`
+    # from `getBillingDetails`).
+    # - `custom_actions` is the highest custom-action count across any
+    # single active service in the organization (since the corresponding limit is enforced per
+    # service, not per organization).
+    # - `messages_day` is retained as a deprecated alias for
+    # `external_messages_day`
     # 
     # Arguments:
     #   - usage_type
-    #       * Usage type.
-    #       * Allowed values: phones, projects, users, contacts, messages_day, stored_messages,
-    #           data_rows, api_requests_day
+    #       * Usage type. Same as the keys returned in `plan_limits` from
+    #           `Organization.getBillingDetails`.
+    #       * Allowed values: contacts, phones, active_services, users, stored_messages,
+    #           service_invocations_day, api_requests_day, projects, data_rows, script_module_mb,
+    #           stored_file_mb, custom_actions, groups, custom_contact_fields, external_messages_day,
+    #           external_messages_period, ai_chat_credits_day
     #       * Required
     #   
     # Returns:
@@ -153,6 +371,67 @@ class Organization < Entity
         return @api.do_request("GET", get_base_api_path() + "/usage/#{usage_type}")
     end
 
+    #
+    # Retrieves the daily history of the usage count associated with a particular service plan
+    # limit.
+    # 
+    # Telerivet stores a snapshot of each organization's usage once per
+    # day, shortly after midnight in the organization's time zone. For usage types that are
+    # counted per day (`external_messages_day`, `api_requests_day`, `service_invocations_day`, and
+    # `ai_chat_credits_day`), each entry contains the usage counted during that entire day. For
+    # all other usage types, each entry contains the usage count at the time the snapshot was
+    # recorded.
+    # 
+    # The maximum supported date range is 500 days between start_date and
+    # end_date. If the requested date range includes the current time, the response will also
+    # include a final entry with `current: true` containing the live usage count computed at the
+    # time of the API request.
+    # 
+    # Usage snapshots are only recorded while an organization is active,
+    # so an entry may not be available for every date in the requested range.
+    # 
+    # Arguments:
+    #   - options (Hash)
+    #       * Required
+    #     
+    #     - usage_type (string)
+    #         * Usage type, corresponding to the keys in the `plan_limits` property returned by
+    #             [getBillingDetails](#Organization.getBillingDetails).
+    #         * Allowed values: contacts, phones, active_services, users, stored_messages,
+    #             service_invocations_day, api_requests_day, projects, data_rows, script_module_mb,
+    #             stored_file_mb, custom_actions, groups, custom_contact_fields,
+    #             external_messages_day, external_messages_period, ai_chat_credits_day
+    #         * Required
+    #     
+    #     - start_date (string)
+    #         * Start date of usage history, in YYYY-MM-DD format (in the organization's time
+    #             zone)
+    #         * Required
+    #     
+    #     - end_date (string)
+    #         * End date of usage history (inclusive), in YYYY-MM-DD format (in the organization's
+    #             time zone)
+    #         * Required
+    #   
+    # Returns:
+    #     (associative array)
+    #       - timezone_id (string)
+    #           * The organization's time zone ID, used to determine the date associated with each
+    #               entry
+    #       
+    #       - usage_type (string)
+    #           * The usage type from the request
+    #       
+    #       - history (array)
+    #           * List of usage entries in chronological order, one for each daily usage snapshot
+    #               recorded within the requested date range (plus the live usage entry if the range
+    #               includes the current time).
+    #
+    def get_usage_history(options)
+        data = @api.do_request("GET", get_base_api_path() + "/usage_history", options)
+        return data
+    end
+
     #
     # Retrieves statistics about messages sent or received via Telerivet. This endpoint returns
     # historical data that is computed shortly after midnight each day in the project's time zone,
@@ -183,16 +462,14 @@ class Organization < Entity
     #     
     #     - metrics (string)
     #         * Comma separated list of metrics to return (summed for each distinct value of the
-    #             requested properties)
-    #         * Allowed values: count, num_parts, duration, price
+    #             requested properties). Supported metrics are `count` (the number of messages),
+    #             `num_parts` (the number of SMS parts), `duration` (the total duration of calls, in
+    #             seconds), and `price.<currency>` (the total price of messages priced in the
+    #             specified ISO 4217 currency, e.g. `price.USD`). Amounts are not converted between
+    #             currencies: each `price.<currency>` metric only includes messages priced in the
+    #             specified currency.
     #         * Required
     #     
-    #     - currency (string)
-    #         * Three-letter ISO 4217 currency code used when returning the 'price' field. If the
-    #             original price was in a different currency, it will be converted to the requested
-    #             currency using the approximate current exchange rate.
-    #         * Default: USD
-    #     
     #     - filters (Hash)
     #         * Key-value pairs of properties and corresponding values; the returned statistics
     #             will only include messages where the property matches the provided value. Only the

data/lib/telerivet/phone.rb

@@ -68,6 +68,21 @@ module Telerivet
 #           to send messages. When null, there is no restriction on recipient countries.
 #       * Updatable via API
 #   
+#   - sent_message_limit (int)
+#       * Maximum number of messages that can be sent from this phone in a given period. When
+#           the sent_message_count reaches this limit, sending is automatically paused. Set to
+#           null to disable the limit.
+#       * Updatable via API
+#   
+#   - sent_message_count (int)
+#       * Number of messages sent from this phone since the counter was last reset (see
+#           sent_message_epoch). This property is not updated if sent_message_limit is null.
+#       * Read-only
+#   
+#   - sent_message_epoch (UNIX timestamp)
+#       * The UNIX timestamp when the sent_message_count was last reset to 0.
+#       * Read-only
+#   
 #   - send_delay (number)
 #       * Number of seconds to wait after sending each message from this phone, to avoid
 #           exceeding carrier rate limits.
@@ -176,6 +191,10 @@ module Telerivet
 #           Only applicable for routes that support external API configuration. Write-only; not
 #           returned by the API when retrieving a phone.
 #       * Updatable via API
+#   
+#   - url
+#       * URL to this phone in the Telerivet web app
+#       * Read-only
 #
 class Phone < Entity
     #
@@ -195,7 +214,7 @@ class Phone < Entity
     #     - source
     #         * Filter messages by source
     #         * Allowed values: phone, provider, web, api, service, webhook, scheduled,
-    #             integration
+    #             integration, mcp
     #     
     #     - starred (bool)
     #         * Filter messages by starred/unstarred
@@ -267,6 +286,15 @@ class Phone < Entity
         super
     end
 
+    #
+    # Resets this route's sent_message_count to 0 and updates sent_message_epoch to the current
+    # time. If sending was automatically paused because the previous count reached the limit,
+    # sending will be resumed.
+    #
+    def reset_sent_message_count()
+        @api.do_request("POST", get_base_api_path() + "/reset_sent_message_count")
+    end
+
     def id
         get('id')
     end
@@ -331,6 +359,22 @@ class Phone < Entity
         set('allowed_recipient_countries', value)
     end
 
+    def sent_message_limit
+        get('sent_message_limit')
+    end
+
+    def sent_message_limit=(value)
+        set('sent_message_limit', value)
+    end
+
+    def sent_message_count
+        get('sent_message_count')
+    end
+
+    def sent_message_epoch
+        get('sent_message_epoch')
+    end
+
     def send_delay
         get('send_delay')
     end
@@ -443,6 +487,10 @@ class Phone < Entity
         set('external_secret', value)
     end
 
+    def url
+        get('url')
+    end
+
     def get_base_api_path()
         "/projects/#{get('project_id')}/phones/#{get('id')}"
     end