The notifications settings endpoints provide the ability to configure specific notifications settings for each environment. They implement operations to read, update and reset the settings for the environment.

Configure an SMS/Voice provider fallback chain

The sequence of SMS/Voice providers in smsProvidersFallbackChain comprises the notification fallback sequence, in the event of a primary or subsequent provider failing to send the notification.

  1. The providers must be configured in the Phone Delivery Settings resource.
  2. Update the notifications setting resource by using the PUT /environments/{envId}/notificationsSettings/ operation. For example, to define your own provider (represented here as TwilioPhoneDeliverySettingsId) as the primary provider, and Ping’s Twilio account as the fallback:
{
    "restrictions": {
        "smsVoiceQuota": {
            "daily": 1
        }
    },
    "whitelist": [
        {
            "user": {
                "id": {id}
            }
        }
    ],
    "smsProvidersFallbackChain": [ {TwilioPhoneDeliverySettingsId}, "PINGONE_TWILIO" ],
    "deliveryMode": "WHITELIST"
}

Notifications settings properties

Property Description
updatedAt The time the resource was last updated.
restrictions.smsVoiceQuota.daily The maximum number of SMS and voice notifications that can be sent per user per day.
  • restrictions.smsVoiceQuota.daily can be set to any value between 0 and 50.
  • Trial accounts have a default value of 30.
  • The daily counters are reset every night at midnight UTC.
defaultLanguage Defaults to “en”. A string that specifies the a written or spoken language, which is optional. This may be explicitly set to null when updating to unset it. If provided, the format of the value must be a valid language range and the same as the HTTP Accept-Language header field (not including Accept-Language:) and is specified in Section 5.3.5 of RFC 7231. For example: en-US, en-gb;q=0.8, en;q=0.7. The setting here will be used as the language for any notifications if both the Notifications Templates locale property and the Users preferredLanguage property are not set.
deliveryMode A string that indicates the environment’s delivery mode.
Possible values:
  • ALL: Enable notifications to all users.
    • This option is supported in the production environment only.
    • The default deliveryMode for the production environment is ALL.
  • WHITELIST: Enable notifications to whitelisted users only.
    • This option is supported for both production and sandbox environments.
    • The default deliveryMode for sandbox environments is WHITELIST.
whitelist.user.id Declaration of the whitelist array comprising users and their IDs.
  • These users will receive notifications when deliveryMode is set to WHITELIST.
  • Sandbox environments have a maximum limit of 50 users in the whitelist array.
environment.id A string that specifies the environment resource’s unique identifier.
smsProvidersFallbackChain A string that specifies a comma-separated list which represents the execution order of different SMS/Voice providers configured for the environment. The providers and their accounts’ configurations are represented in the list by the ID of the corresponding PhoneDeliverySettings resource. The only provider which is not represented by a PhoneDeliverySettingsId is the PingOne Twilio provider. The PingOne Twilio provider is represented by the “PINGONE_TWILIO” string. If the smsProvidersFallbackChain list is empty, an SMS or voice message will be sent using the default Ping Twilio account. Otherwise, an SMS or voice message will be sent using the first provider in the list. If the server fails to queue the message using that provider, it will use the next provider in the list to try to send the message. This process will go on until there are no more providers in the list. If the server failed to send the message using all providers, the notification status is set to FAILED.
from.name A string that specifies the email’s “from” name (relevant when the deliveryMethod is Email).
from.address A string that specifies the email’s “from” address (relevant when the deliveryMethod is Email). This value must be a trusted email address.
replyTo.name A string that specifies the email’s “reply to” name (relevant when deliveryMethod is Email).
replyTo.address A string that specifies the email’s “reply to” address (relevant when deliveryMethod is Email). This value must be a trusted email address.

Notifications settings response codes

Code Message
200 Successful operation.
201 Successfully created.
400 The request could not be completed.
401 You do not have access to this resource.
403 You do not have permissions or are not licensed to make this request.
404 The requested resource was not found.