API for Notifications

Users receive email notifications to inform them when they receive a voicemail message. Multiple users can be notified by email about a voicemail, for example if the main reception phone gets a voicemail.

Use the Notifications API to manage templates for notification emails by configuring the JSON data and uploading the notification templates. Plaintext and HTML documents are currently supported.

API calls

Click on each call to view the endpoint, method, and request example.

• Get available notification templates from the system
• Get notifications overridden in the account
• Get notification configuration
• Create a notification template
• Get a specific notification
• Update a notification configuration
• Remove a notification template
• Get notification template
• Update notification template
• Preview a new template
• Get the SMTP log for notifications
• Customer update

Sample notifications API template

NOTE: The macros object is a per-template, system-defined set of macros you can use in your templates. You cannot configure this through the API.

{
    "enabled": true,
    "from": "peter@email.com",
    "macros": {
        "user.first_name": {
            "description": "If the voicemail box has an owner id, this is the first name of that user.  Not always present",
            "friendly_name": "First Name",
            "i18n_label": "first_name"
        },
        "user.last_name": {
            "description": "If the voicemail box has an owner id, this is the first name of that user.  Not always present",
            "friendly_name": "Last Name",
            "i18n_label": "last_name"
        }
    },
    "subject": "Hello {{user.first_name}}, you received a new voicemail!",
    "template_charset": "utf-8",
    "to": {
        "email_addresses": [
            "peter@email.com"
        ],
        "type": "admins"
    }
}

Parameters

The table shows the possible parameters available for notification requests.

Key	Description	Type	Options/Min/Max/Default
from	Required. The "from" email address.	string
subject	Required. The email subject.	string	(1..200)
to	Required. The "to" email field.	object
bcc	The bcc email field.	object
bcc.email_addresses	List of bcc email addresses.	array(string)
bcc.email_addresses.[]	Specific bcc email addresses.	string
bcc.type	Type of bcc email.	string	original, specified, admins
category	Category of the template, for grouping purposes.	string	(1..)
cc	The cc email field.	object
cc.email_addresses	List of cc email addresses.	array(string)
cc.email_addresses.[]	Specific cc email addresses.	string
cc.type	Type of cc email.	string	original, specified, admins
enabled	Indicates if notifications should be enabled.	boolean	The default is true.
friendly_name	Friendly name of the template.	string	(1..)
macros	Email macros.	object
reply_to	The "reply-to" email address.	string
template_charset	The possible character sets.	string	(1..). The default is utf-8.
to.email_addresses.[]	Specific "to" email addresses.	string
to.type	The type of "to" email.	string	original, specified, admins

NOTE: Only a reseller or master account owner can modify an account notification.

IMPORTANT: - To modify an account's template(s), use /v2/accounts/{ACCOUNT_ID}/notifications. - To modify the system default template, use /v2/notifications.

Get available notification templates from the system

Returns a list of notification templates. This is the first request you should make to see what templates exist on the system to override.

Method and endpoint

GET /v2/notifications

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications

Response

{
        "auth_token": "{AUTH_TOKEN},
        "data": [
            {"id": "voicemail_to_email"
             ,"macros": {
                 "call_id": {
                     "description": "Call ID of the caller"
                     ,"friendly_name": "Call ID"
                     ,"i18n_label": "call_id"
                     }
                 ,"caller_id.name": {
                     "description": "Caller ID Name"
                     ,"friendly_name": "Caller ID Name"
                     ,"i18n_label": "caller_id_name"
                 }
                 ,...
             }
            }
            ,{...}
        ]
        "request_id": "{REQUEST_ID}",
        "revision": "{REVISION}",
        "status": "success"
}

Get notifications overridden in the account

Returns the templates that the account overrides when you specify the account ID in the URI.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/notifications

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications

Response

  {
      "auth_token": "{AUTH_TOKEN}",
      "data": [
          {
              "id": "voicemail_to_email",
              "macros": {
                  "call_id": {
                      "description": "Call ID of the caller",
                      "friendly_name": "Call ID",
                      "i18n_label": "call_id"
                  },
                  "caller_id.name": {
                      "description": "Caller ID Name",
                      "friendly_name": "Caller ID Name",
                      "i18n_label": "caller_id_name"
                  },
                  ...
              },
              "account_overridden": true
          }
      ],
      "request_id": "{REQUEST_ID}",
      "revision": "{REVISION}",
      "status": "success"
  }

NOTE: The key account_overridden exists on any templates that are account-specific.

Get notification configuration

Returns details of the notification settings.

Method and endpoint

GET /v2/notifications/{NOTIFICATION_ID}

Using the ID from the system listing above, get the template JSON. This document allows you to set "static" properties, for example, call data or system alert. Static properties are any settings that are not derived from the event causing the notification.

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/notifications/{NOTIFICATION_ID}

Response

    {
        "auth_token": "{AUTH_TOKEN}",
        "data": {
            "id": "{NOTIFICATION_ID}"
            ,"macros":{...}
            ,"templates": {
                "text/html": {
                    "length": 600
                }
                ,"text/plain": {
                    "length": 408
                }
            }
        },
        "request_id": "{REQUEST_ID}",
        "revision": "{REVISION}",
        "status": "success"
    }

Performing a GET with an account ID returns the notification object. The account_overridden flag is added if it is account-specific. The absence of the key indicates that it is the system default notification.

Create a notification template

Modifies the system default template and puts it back to the account.

Method and endpoint

PUT /v2/accounts/{ACCOUNT_ID}/notifications

Request

curl -v -X PUT \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{
    "data": {
        "id":"{NOTIFICATION_ID}",
        "to": {
            "type": "users",
            "email_addresses": ["user@account.com"]
        },
        "from": "reseller@resellerdomain.com",
        "subject": "Hello {{user.first_name}}, you recieved a new voicemail!",
        "enabled": true,
        "template_charset": "utf-8"
    }}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "enabled": true,
        "from": "reseller@resellerdomain.com",
        "id": "{NOTIFICATION_ID}",
        "macros": {
            "user.first_name": {
                "description": "If the voicemail box has an owner id, this is the first name of that user. Not always present",
                "friendly_name": "First Name",
                "i18n_label": "first_name"
            },
            "user.last_name": {
                "description": "If the voicemail box has an owner id, this is the last name of that user. Not always present",
                "friendly_name": "Last Name",
                "i18n_label": "last_name"
            }
        },
        "subject": "Hello {{user.first_name}}, you recieved a new voicemail!",
        "template_charset": "utf-8",
        "to": {
            "email_addresses": [
                "user@account.com"
            ],
            "type": "users"
        }
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

NOTE: This request fails if "id" does not already exist in the system defaults. To create a new system notification template, a super admin can use the PUT request to /v2/notifications instead of a specific account.

Get a specific notification

Returns the account specific notification. You can then use it in a WYSIWYG editor or for other purposes.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Response

{
    "auth_token": "{AUTH_TOKEN}",
    "data": {
        "id": "{NOTIFICATION_ID}",
        ...
    },
    "request_id": "{REQUEST_ID}",
    "revision": "{REVISION}",
    "status": "success"
}

Update a notification configuration

Updates an existing notification configuration.

Method and endpoint

POST /v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

NOTE: You can omit /accounts/{ACCOUNT_ID} to update the system's version.

Request

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -d '{
    "data": {
        "id":"{NOTIFICATION_ID}",
        "to": {
            "type": "users",
            "email_addresses": ["user@account.com"]
        },
        "from": "reseller@resellerdomain.com",
        "subject": "Hello {{user.first_name}}, you recieved a new voicemail!",
        "enabled": true,
        "template_charset": "utf-8",
        "macros": {
            "user.first_name": {
                "i18n_label": "first_name",
                "friendly_name": "First Name",
                "description": "If the voicemail box has an owner id, this is the first name of that user.  Not always present"
            },
            "user.last_name": {
                "i18n_label": "last_name",
                "friendly_name": "Last Name",
                "description": "If the voicemail box has an owner id, this is the last name of that user.  Not always present"
            }
        }
    }}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Remove a notification template

Deletes a notification template from the system.

Method and endpoint

  DELETE /v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

NOTE: You can omit the /accounts/{ACCOUNT_ID} to remove the system default. For example DELETE /v2/notifications/{NOTIFICATION_ID}.`

Request

curl -v -X DELETE \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Template Formats

In addition to creating the configuration documents, you must also be able to attach the notification templates in their various forms. Currently supported formats are plaintext and HTML.

Get a notification template

Returns a specific notification template, using the notification ID.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

When you GET a notification config (accept of application/json), you get a templates list of Content-Type attributes. You can use those to fetch a specific template by setting the Accept header:

Request (HTML)

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Accept: text/html' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Request (plain)

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Accept: text/plain' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

The only difference between the HTML and plain request is the Accept attribute. This parameter determines which attachment is returned in the payload. If you specify a non-existent Accept MIME type, then a "406 Not Acceptable" error is returned.

To get the HTML template for clients that do not support setting the Accept header, you can include a querystring parameter, http://server:8000/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}?accept=text/html.

Update a notification template

Updates the notification template.

Method and endpoint

POST /v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Request (plaintext)

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Content-Type: text/plain' \
    -d 'some plain text template code' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Request (HTML)

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Content-Type: text/html' \
    -d '<div>
            <p>Some Html and {{macro.key}} replaced on render</p>
       </div>' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}

Preview a new template

Returns a preview of the resulting email. It is useful to preview your updates before saving the modified template.

Method and endpoint

POST /v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}/preview

Request

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Content-Type: application/json' \
    -d '{"data": {
        "to": {"email_addresses": ["me@iptelecom.com"]},
        "from": "hostedbpx@iptelecom.ie",
        "subject": "Testing NOTIFICATION",
        "html": "SSUyNTIwJTI1dTI2NjElMjUyMFVuaWNvZGUlMjUyMQ==",
        "plain": "You just recieved an email! It was sent to {{user.email}}",
        "enabled": true
        }}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/{NOTIFICATION_ID}/preview

• HTML is the base64 encoded HTML template
• Plain is the plain-text template

IMPORTANT: In HostedPBX versions prior to 3.9, notification templates were managed and processed by the "notify" app. All accounts will continue to be processed by the notify app until the Crossbar notification APIs are accessed for the first time (for instance, when using the Branding App in the Hosted PBX UI). After a client uses the APIs, a flag is set on the account telling the notify app to ignore processing and instructs the teletype app to process it instead. This enables admins to run both notify and teletype concurrently without sending multiple copies of each notification.

Get the SMTP log for notifications

Returns the SMTP log for a notification or multiple notifications.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/notifications/smtplog

Request

  curl -v -X GET \
      -H "X-Auth-Token: {AUTH_TOKEN}" \
      -H 'Content-Type: text/plain' \
      https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/smtplog

Get a notification's SMTP log

Returns a specific SMTP log for a notification.

Method and endpoint

  GET /v2/accounts/{ACCOUNT_ID}/notifications/smtplog/{SMTP_LOG_ID}

Request

curl -v -X GET \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/smtplog/{SMTP_LOG_ID}

Response

{
  "data": {
    "rendered_templates": {
      "text/plain": "Expired registration in account \"teste\".\nNotifications are enabled for loss of registration on the device 995582142@teste.sip.90e9.com\n\nLast Registration:\nDevice ID: 4e411cf70ad352a222e24fbacf467c18\nAccount ID: 85ea6075c6c1e266f8512e2233541bdb\nUser Agent: Grandstream GXP2130 1.0.7.25\nContact: sip:995582142@192.168.26.13:5060;reg-id=1;+sip.instance="urn:uuid:00000000-0000-1000-8000-000B826C4283"\n\nThis may be due to a network connectivity issue, power outage, or misconfiguration. Please check the device.",
      "text/html": "<h2>Expired registration in account \"teste\"</h2><p>Notifications are enabled for loss of registration on the device 995582142@teste.sip.90e9.com</p><h3>Last Registration</h3><table><tbody><tr><td>Device ID</td><td>4e411cf70ad352a222e24fbacf467c18</td></tr><tr><td>Account ID</td><td>85ea6075c6c1e266f8512e2233541bdb</td></tr><tr><td>User Agent</td><td>Grandstream GXP2130 1.0.7.25</td></tr><tr><td>Contact</td><td>sip:995582142@192.168.26.13:5060;reg-id=1;+sip.instance=&quot;urn:uuid:00000000-0000-1000-8000-000B826C4283&quot;</td></tr></tbody></table><p>This may be due to a network connectivity issue, power outage, or misconfiguration. Please check the device.</p>"
    },
    "subject": "Loss of Registration for 995582142@teste.sip.90e9.com",
    "emails": {
      "from": "no_reply@dev-01.90e9.com",
      "to": [
        "teste@factorlusitano.com"
      ]
    },
    "receipt": "2.0.0 Ok: queued as B60E22044B",
    "account_id": "{ACCOUNT_ID}",
    "account_db": "{ACCOUNT_DB}",
    "template_id": "deregister",
    "template_account_id": "5ba01ad7ad1611d436b1860d8c552897",
    "id": "{SMTP_LOG_ID}"
  },
  "revision": "{REVISION}",
  "request_id": "{REQUEST_ID}",
  "status": "success",
  "auth_token": "{AUTH_TOKEN}"
}

Customer update

Sends a notification message of an update to all reseller's children or to a particular account.

Method and endpoint

  POST /v2/accounts/{ACCOUNT_ID}/notifications/customer_update/message

Request (sends message to all resellers accounts)

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Content-Type: text/plain' \
    -d '{} \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/customer_update/message

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Content-Type: text/plain' \
    -d '{} \
    https://apps.hostedpbx.ie:8443/v2/accounts/{SENDER(RESELLER)_ACCOUNT_ID}/notifications/customer_update/message

Request (sends message to a particular account)

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Content-Type: text/plain' \
    -d '{"data": {"recipient_id": "33ca3929ed585e0e423eb39e4ffe1452"}}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{ACCOUNT_ID}/notifications/customer_update/message

curl -v -X POST \
    -H "X-Auth-Token: {AUTH_TOKEN}" \
    -H 'Content-Type: text/plain' \
    -d '{"data": {"recipient_id": "33ca3929ed585e0e423eb39e4ffe1452"}}' \
    https://apps.hostedpbx.ie:8443/v2/accounts/{SENDER(RESELLER)_ACCOUNT_ID}/notifications/customer_update/message

Variations

You can send a message to all users, admins only, or a particular user within an account by adding a user_type field to your payload:

• All users:

    {
        "data": {"user_type": "all_users"}
    }
    ````
  

• Particular user:

    ```json
    {
        "data": {"user_type": "{ACCOUNT_ID}"}
    }
    ````
  

• Admin privileged users only (this is a default and can be omitted):

    ```json
    {
        "data": {"user_type": "admins_only"}
    }
    ````
  

• You can send a message with changed subject, html, and plain text templates by providing the full notification document payload:

    ```json
    {
        "data": {
            "recipient_id": "33ca3929ed585e0e423eb39e4ffe1452",
            "user_type": "3d9b564d5c95d52d81a2e49ea0c57941",
            "id": "customer_update",
            "account_overridden": true,
            "enabled": true,
            "category": "user",
            "friendly_name": "Customer update",
            "from": "info@onnet.su",
            "subject": "Test Reseller customer update",
            "bcc": {
                "email_addresses": [],
                "type": ""
            },
            "cc": {
                "email_addresses": [],
                "type": ""
            },
            "macros": {
                "user.email": {
                    "description": "Email of the user",
                    "friendly_name": "Email",
                    "i18n_label": "user_email"
                },
                "user.first_name": {
                    "description": "First Name",
                    "friendly_name": "First Name",
                    "i18n_label": "first_name"
                },
                "user.last_name": {
                    "description": "Last Name",
                    "friendly_name": "Last Name",
                    "i18n_label": "last_name"
                },
                "user.timezone": {
                    "description": "Timezone of the user",
                    "friendly_name": "Timezone",
                    "i18n_label": "user_timezone"
                },
                "user.username": {
                    "description": "Username",
                    "friendly_name": "Username",
                    "i18n_label": "username"
                }
            },
            "template_charset": "utf-8",
            "html": "PHA+RGVhciB7e3VzZXIuZmlyc3RfbmFtZX19IHt7dXNlci5sYXN0X25hbWV9fS48L3A+CjxwPkhlcmUgYXJlIHNvbWUgbmV3cyB0aGF0IHdlIGhhdmUgc2VsZWN0ZWQgZm9yIHlvdTwvcD4KPHA+QmVzdCByZWdhcmRzLDwvcD4KPHA+T25OZXQgSW5ub3ZhdGlvbnMgTGltaXRlZC48L3A+",
            "plain": "Dear {{user.first_name}} {{user.last_name}}.\n\nHere are some more news that we have selected for you.\n\nBest regards,\nOnNet Innovations Limited.",
            "templates": {
                "text/html": {
                    "length": 161
                },
                "text/plain": {
                    "length": 136
                }
            },
        }
    }
  

• To send an update to a customer from your kapp, you can build a payload that includes your app data (see the "DataBag" field). You can send it over advanced message queuing protocol (AMQP) using either a predefined template (see "Template-ID" field) or your own hardcoded templates (see "HTML" and "Text" fields):

  -spec send_account_update(ne_binary()) -> 'ok'.
  send_account_update(AccountId) ->
      case kz_amqp_worker:call(build_customer_update_payload(AccountId)
                              ,fun kapi_notifications:publish_customer_update/1
                              ,fun kapi_notifications:customer_update_v/1
                              )
      of
          {'ok', _Resp} ->
              lager:debug("published customer_update notification");
          {'error', _E} ->
              lager:debug("failed to publish_customer update notification: ~p", [_E])
      end.
  
  -spec build_customer_update_payload(cb_context:context()) -> kz_proplist().
  build_customer_update_payload(AccountId) ->
      props:filter_empty(
        [{<<"Account-ID">>, kz_services:find_reseller_id(AccountId)}
        ,{<<"Recipient-ID">>, AccountId}
        ,{<<"Template-ID">>, <<"customer_update_billing_period">>}
        ,{<<"DataBag">>, {[{<<"field1">>,<<"value1">>},{<<"field2">>,{[{<<"subfield1">>,<<"subvalue1">>},{<<"subfield2">>,<<"subvalue2">>}]}}]}}
        ,{<<"HTML">>, base64:encode(<<"Dear {{user.first_name}} {{user.last_name}}. <br /> DataBag test: {{databag.field2.subfield1}} <br /> Kind regards,">>)}
        ,{<<"Text">>, <<"Oh Dear {{user.first_name}} {{user.last_name}}.\n\nDataBag test: {{databag.field2.subfield2}}\n\nBest regards,">>}
         | kz_api:default_headers(?APP_NAME, ?APP_VERSION)
        ]).