Protocol provider details reference

The following sections contain details on how to configure each type of protocol provider in xMatters. The availability of each protocol provider will depend on your xMatters software license.

APPLE_PUSH

The following table describes the settings for APPLE_PUSH protocol providers.

Setting	Description
Name	Name of the protocol provider. (e.g., APPLE_PUSH)
Description	A brief description of the provider (optional). (e.g., Apple Push Service Provider)
Maximum retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum session size	Number of notifications per connection/session; allowable values are from 1 to 99.
Notification Expiry	Amount of time in seconds after which the APNs (Apple Push Notification service) discards the notification. If the target device is offline at the time of delivery, the APNs will wait until the Notification Expiry period has elapsed before discarding the notification Note:This affects only the push notifications displayed on the device, not the ability to view all notifications via My Alerts within the application.

GCM

The following table describes the settings for GCM (Google Cloud Messaging) protocol providers.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum Session Size	Number of notifications per connection/session; allowable values are from 1 to 99.
Split long message	Controls whether notifications that exceed the number of characters specified by the Split size setting are split into multiple smaller messages or sent as a single message.
Split size	Determines the maximum number of characters per message sent to this protocol provider. This setting applies only if the Split long message check box is selected.
Maximum message length	If enforced by this provider, the maximum number of characters allowed per notification. For more information, see Set maximum message length.
Maximum PIN length	If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer than the maximum PIN length, the leading characters are truncated.
Server Address	The target URL to which the Device Engine submits the request. Note that while this field is editable, the default value is already set to the correct URL.
Server Port	The port used by the server at the Server Address URL. Note that while this field is editable, the default value is already set to the correct port.
Account	The Google account used to process communications between xMatters and the notification recipient.
Password	The password for the Google account.
SSL Flag	Indicates whether the service provider uses Secure Socket Layer (SSL) encryption.

HTTP Generic

The following table describes the settings for HTTP Generic protocol providers.

Example Use Cases:

For more information about how to configure this protocol provider, see the following:

Configure a fax provider

If you are configuring this protocol provider to work with xMatters SMS, you must have simple SMS responses enabled, as explained in Configure simple SMS replies.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum Session Size	Number of notifications per connection/session; allowable values are from 1 to 99.
Split long message	Controls whether notifications that exceed the number of characters specified by the Split size setting are split into multiple smaller messages or sent as a single message.
Split size	Determines the maximum number of characters per message sent to this protocol provider. This setting applies only if the Split long message check box is selected.
Maximum message length	If enforced by this provider, the maximum number of characters allowed per notification. For more information, see Set maximum message length.
Maximum PIN length	If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer than the maximum PIN length, the leading characters are truncated.
API URL	The target URL to which the device engine submits the HTTP POST operation. initially (e.g., http://webapi.somecompany.com:8080).
Username	Typically, the username supplied by the web API provider; required if the URL uses HTTP authentication.
Password	Typically, the password supplied by the web API provider; required if the URL uses HTTP authentication.
Response URL	The URL of the xMatters web server to which the device engine forwards the web API's response from the initial submission (e.g., http://<webserver>:<port>/services/clickatell or http://yourwebserver/processResponse.jsp). Note that the web server must be able to receive update information from the provider's server.
Request Parameters	This area displays an editable list of HTTP request parameters available to this provider. This list is typically specified by the web API. Click Add New Name/Value Pair to create a new request parameter, and then specify a Name and Value in the related fields. To remove a request parameter, select the related check box and then click Remove Selected Name/Value Pair.

HTTP Conference

The following table describes the settings for HTTP Conference protocol providers.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10. (Some providers may have separate retry logic; for example, even if you set Maximum Retries to 0, the provider may run through its own retry paradigm. Further, be aware that increasing Maximum Retries by one increment may result in more than one retry, as the provider will still carry out its retry logic based on the nature of the previous call failure.)
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum Session Size	Number of notifications per connection/session; allowable values are from 1 to 99.
API URL	URL to which the device engine initially submits (e.g., http://webapi.somecompany.com: 8080).
Username	Typically, the username supplied by the web API provider; required if the URL uses HTTP authentication.
Password	Typically, the password supplied by the web API provider; required if the URL uses HTTP authentication.
Response URL	Web server URL to which the device engine forwards the web API's response from the initial submission (e.g., http://yourwebserver/exampleResponse.jsp).
Request Parameters	This area displays an editable list of HTTP request parameters available to this provider. This list is typically specified by the web API. Click Add New Name/Value Pair to create a new request parameter, and then specify a Name and Value in the related fields. To remove a request parameter, select the related check box and then click Remove Selected Name/Value Pair.

HTTP xMatters Conference

The following table describes the settings for HTTP Conference protocol providers.

The HTTP xMatters Conference service is provided by xMatters; contact Customer Support to set up an account, and for help with the required values for this page.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum Session Size	Number of notifications per connection/session; allowable values are from 1 to 99.
API URL	URL to which the device engine initially submits (e.g., http://webapi.somecompany.com: 8080).
Username	Typically, the username supplied by the web API provider; required if the URL uses HTTP authentication.
Password	Typically, the password supplied by the web API provider; required if the URL uses HTTP authentication.
From	The phone number to use as the caller ID that identifies the source of outgoing messages. Must be a valid outgoing caller ID for your account and formatted using "+" and a country code; e.g., "+16175551212".
To	The target phone number for the notifications.
Status Call Back URL	Web server URL to which status responses should be sent.
Response URL	Web server URL to which the device engine forwards the web API's response from the initial submission (i.e.., http://yourwebserver/voicexml/processResponse.jsp).
Interaction Script URL	Web server URL at which the responses can access the interaction script.
Request Parameters	This area displays an editable list of HTTP request parameters available to this provider. This list is typically specified by the web API. Click Add New Name/Value Pair to create a new request parameter, and then specify a Name and Value in the related fields. To remove a request parameter, select the related check box and then click Remove Selected Name/Value Pair.

HTTP xMatters SMS

The following table describes the settings for HTTP xMatters SMS protocol providers. For information on how xMatters processes SMS messages and responses, see Configure SMS messages and replies.

The HTTP xMatters SMS service is provided by xMatters; contact Customer Support to set up an account, and for help with the required values for this page.

The xMatters SMS service requires that you have simple SMS responses enabled, as explained in Configure simple SMS replies.

HTTP SMS Provider Details
Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum Session Size	Number of notifications per connection/session; allowable values are from 1 to 99.
Split long message	Controls whether notifications that exceed the number of characters specified by the Split size setting are split into multiple smaller messages or sent as a single message.
Split size	Determines the maximum number of characters per message sent to this protocol provider. This setting applies only if the Split long message check box is selected. If you are using the SAR concatenation method, refer to Protocol provider details referencefor more information about this setting.
Maximum message length	If enforced by this provider, the maximum number of characters allowed per notification. For more information, see Set maximum message length.
Maximum PIN length	If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer than the maximum PIN length, the leading characters are truncated.
Short Code Compliance	Select an option to specify when xMatters should send a notification explaining terms of service to each SMS Device: None: xMatters will not send a notification to the Device when it is added, modified, or activated. Send Welcome: xMatters will send a Welcome notification to an SMS Device when it is added, modified, or activated. (The content of this message is defined in the SMSCONFIRMMSG Constant.) Send Custom: xMatters will send a Custom notification to an SMS Device when it is added, modified, or activated. (The content of this message is defined in the SMSFIRSTMMSG Constant.) Send Welcome and Custom: Sends both the Welcome and the Custom messages. In addition to modifying the content of the Custom message, you can modify its behavior and other properties using the xMatters scripts. For example, you could extend the functionality of the Custom message to include a validation request, and then select the "Send Welcome and Custom" option. Whenever a User added a new Device, xMatters would send a Welcome message containing the standard terms and conditions, and then automatically send a validation request to the Device three seconds later. Note that specific content for these messages may be required by local regulations or your SMS provider. After changing this value, you must restart any device engines using this protocol provider for the changes to be applied.
API URL	URL to which the device engine initially submits (e.g., http://webapi.somecompany.com: 8080).
Username	Typically, the username supplied by the web API provider; required if the URL uses HTTP authentication.
Password	Typically, the password supplied by the web API provider; required if the URL uses HTTP authentication.
From	The phone number to use as the caller ID that identifies the source of outgoing messages. Must be a valid outgoing caller ID for your account.
Source TON	The type of number (TON) for the source address to be used during the server session. The TON indicates whether the source address is an international number that includes the country code, a domestic number that does not include the country code, an alphanumeric sender ID, or another format such as a local US number without an area code.
Response URL	Web server URL to which the device engine forwards the web API's response from the initial submission (i.e., http://yourwebserver/services/xmsms).
Request Type	Select one of the following options to specify how you want xMatters to create the POST request body: Parameters: when selected, the page will display an editable list of HTTP request parameters available to this provider. This list is typically specified by the web API. When the notification request is submitted to the protocol provider, xMatters will build the POST request body using these parameters. Click Add New Name/Value Pair to create a new request parameter, and then specify a Name and Value in the related fields. To remove a request parameter, select the related check box and then click Remove Selected Name/Value Pair. For example, to add an API ID (as required by some providers to identify your account), add an "api_id" parameter and set the value to your ID number. Body: when selected, the page will display Content Type and Content fields that allow you to create a custom string to use as the request body. Note that you cannot change this setting if you have already specified country code overrides.
Encoding Type	Select one of the following options to set the encoding type for SMS messages sent using this provider: Prefer Unicode: use UCS2 encoding if there is at least one multi-byte character in the message; otherwise, use 7BIT encoding regardless of the message length. Most Multi-bytes: use UCS2 encoding if the message length is less than 70 characters or if the message (excluding non-letter characters) contains more than 50% multi-byte characters; otherwise, use 7BIT encoding. Unicode: use fixed Unicode encoding. GSM: use fixed GSM encoding.
Country-Specific Overrides	You can set country-specific overrides for the protocol provider's source address: if a country override exists that matches the country specified for a user's text phone device details, the protocol provider will use the source address overrides. For more information, see Country code overrides. Note: This feature requires that you have configured simple SMS replies, as described in Configure simple SMS replies.

Plivo Bridge

Plivo Bridge is a voice and SMS provider API that can be used as an xMatters protocol provider. You require an active Plivo account to use this protocol provider. Log on to your Plivo account to retrieve your authorization ID and authorization token.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
API URL	The Plivo REST API for making calls. This URL is in the format https://api.plivo.com/v1/Account/<PlivoAuthorizationID>/Call/. Replace <PlivoAuthorizationID> with your Plivo authorization token. Example: https://api.plivo.com/v1/Account/MENGSIEFISIFJDJESPPPW/Call
Username	The Plivo authorization ID. Example: MENGSIEFISIFJDJESPPPW
Password	The Plivo authorization token. Example: MDkyNSdsOWkdRUWlwZZGU6LSmSERIT9NiMzshMaFL
Response URL	The xMatters URL that consumes HTTP responses. This URL is in the format http://[ws_username]:[ws_password]@hostname:port/voicexml/rest/plivobridge/processResponse.
Request Body Content	A JSON object that contains the following fields: from: The phone number that the call appears to be from. to: Use $(phone) to represent the phone number. The phone number is replaced by the recipient phone number at run time. answer_url: The xMatters URL that Plivo accesses when the call is established. This enables xMatters to continue with the message flow. hangup_url: The xMatters URL that Plivo access when the call is disconnected or the user hangs up. The answer_url and hangup_url fields use variable username, password, and $(webserverURI). username: a web service user in the xMatters default company password: the password of the web service user webserverURI: Replace $(webserverURI) with the IP address and port number of the xMatters instance. If this value is not replaced, then xMatters uses value from the global constant WEBSERVERURL. Example: { "from": "15555551212", "to": $(phone), "answer_url" : "http//username:password@$(webserverURI)/voicexml/plivobridge/outbound.jsp?requreAuthentication-$(requireAuthentication)&ntfn_id=$(ntfa_id)&node_id=$(node_id)&bridgeNumber=$(bridgenumber)", "hangup_url": "http://username:password@$(webserverURI)/voicexml/plivobridge/hangup.jsp?ntfn_id=$(ntfn_id)&node_id=$(node_id)&bridgeNuumber-(bridgeNumber)" }

SendGrid

The following section explains the rules and settings required to configure SendGrid protocol providers.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Account	Your SendGrid account name.
Password	Your SendGrid account password.
Email Sender	The email sender address of emails created by SendGrid. The email sender display name may be configured in the xMatters user interface.
Reply To	The reply-to email address of emails created by SendGrid (optional). This value must also be configured in your SendGrid account.

SMTP

The following table describes the settings for SMTP protocol providers.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum session size	Number of notifications per connection/session; allowable values are from 1 to 99.
Split long message	Controls whether notifications that exceed the number of characters specified by the Split size setting are split into multiple smaller messages or sent as a single message.
Split size	Determines the maximum number of characters per message sent to this protocol provider. This setting applies only if the Split long message check box is selected.
Maximum message length	If enforced by this provider, the maximum number of characters allowed per notification. For more information, see Set maximum message length.
Maximum PIN length	If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer than the maximum PIN length, the leading characters are truncated. For email Protocol Providers (i.e., SMTP, Lotus Notes, and MAPI), the maximum pin length applies only if all of the characters before the @ symbol are digits. In this case, the Maximum PIN Length setting controls how many digits are allowed before the @ symbol.
Authenticate	Specifies whether the service provider requires authentication.
Account	If authentication is active, the authentication account name.
Password	If authentication is active, the password for the associated account.
Email Sender	Email address used to send notifications (appears in the “From:” field on email messages).
Reply To	Email address to which responses to notifications should be sent. When a recipient responds to an email notification from this provider, the “To:” field on the reply is automatically populated with this email account. If this account is not specified, responses are sent to the account specified as the Email Sender.
Server Address	URL or IP address for the protocol provider’s server.
Server Port	Port number of the protocol provider’s server.
Domain Name	If required, the domain name for the Email Sender address.
Use SSL	Indicates whether the provider uses encryption.

The S/MIME (Secure/Multipurpose Internet Mail Extensions) standard is not supported for email responses.

SNPP

The following table describes the settings for SNPP protocol providers.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum session size	Number of notifications per connection/session; allowable values are from 1 to 99.
Split long message	Controls whether notifications that exceed the number of characters specified by the Split size setting are split into multiple smaller messages or sent as a single message.
Split size	Determines the maximum number of characters per message sent to this protocol provider. This setting applies only if the Split long message check box is selected.
Maximum message length	If enforced by this provider, the maximum number of characters allowed per notification. For more information, see Set maximum message length.
Maximum PIN length	If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer than the maximum PIN length, the leading characters are truncated.
Server Address	URL or IP address for the protocol provider’s server.
Server Port	Port number of the protocol provider’s server.
Account	Account name, if required by your service provider. Note: Some SNPP Providers, such as PageOne, require a password, but do not supply or require an account name. If this is the case, enter your password in the Account field, and leave the Password field blank.
Password	Password, if required by your service provider; see note in Account field, above.
Two Way	Specifies whether the service is two-way.
Multiple Notifications per Session	When selected, the provider will process multiple notifications per connection session. If this option is not selected, the provider must reconnect with the SNPP server for each notification processed.
Default Poll Period	The provider’s default polling period, in seconds.

Twilio

You can configure two Twilio protocol providers in xMatters: use Twilo-Callout for callouts and Twilio-Bridge for conference bridges. You require a Twilio account to use this protocol provider.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
Maximum Session Size	Number of notifications per connection/session; allowable values are from 1 to 99.
API URL	URL to the API interface provided by Twilio for POST requests. Example: https://api.twilio.com/2010-04-01/Accounts/ACf28404d03446a5588cdbbcb7956fff8/Calls
Username	The user ID of your Twilio account.
Password	The password of your Twilio account.
From	The phone number that the call appears to be from.
To	Use $(phone) to represent the phone number being called. This placeholder is replaced by the recipient phone number at run time.
Status Call Back URL	The xMatters URL to be called when the status changes. Replace username and password with the logon credentials of a web service user in the default company, and replace myco.na1.xmatters.com with the URL and port number of your xMatters installation. Example (Twilio Callout): http://username:password@myco.na1.xmatters.com/voicexml/twiliocallout/statuschange.jsp?requireAuthentication=$(requireAuthentication)&ntfn_id=$(ntfn_id)&node_id=$(node_id)&max_retries=$(max_retries)
Response URL	The xMatters URL to be called when a user responds to a call. Replace username and password with the logon credentials of a web service user in the default company, and replace myco.na1.xmatters.com with the URL and port number of your xMatters installation. Example: http://username:password@myco.na1.xmatters.com/voicexml/processResponse.jsp
Interaction Script URL	The xMatters interaction script. Replace username and password with the logon credentials of a web service user in the default company, and replace myco.na1.xmatters.com with the URL and port number of your xMatters installation. Example (Twilio Callout): http://username:password@myco.na1.xmatters.com/voicexml/rest-integration/twiliocallout/initiate?requireAuthentication=$(requireAuthentication)&ntfnId=$(ntfn_id)&nodeId=$(node_id)

Voxeo

The following sections explain the rules and settings required to configure Voxeo protocol providers.

This release supports only events created and injected via an xMatters communication plan. Events from other sources, such as integrations or device validation, will not be delivered via Voxeo providers. This release also does not support conferencing over Voxeo providers.

It is recommended that you assign a secondary protocol provider, such as SIP, to each user service provider using a Voxeo protocol provider.

Routing and failover rules

For all of the following examples, assume that a user service provider has a Voxeo protocol provider listed first, followed by a SIP provider.

The basic routing conditions for a Voxeo notification are as follows:

If the event was initiated via an xMatters communication plan or from a communication plan voice recording, and does not include conference bridging, then it is considered viable for Voxeo notification.
If a callout is made using Voxeo, only events initiated via a communication plan or communication plan voice recordings will be presented to the user. (If the callout is made over SIP, all events are presented to the User.)
If the first protocol provider does not apply, xMatters immediately fails over to the next available protocol provider.
- For example, if a User attempts to validate a voice device, the notification will immediately failover to the SIP provider as the Voxeo provider does not support device validation.
If the device engine for the first protocol provider is not running, the notification will immediately failover to the next protocol provider.
If the notification meets the Voxeo requirements but the connection cannot be established, xMatters will retry the same protocol provider until the maximum number of attempts have been made, and then failover to the next available protocol provider.
If there are no valid protocol providers remaining, or the notification does not meet the requirements, then the notification will not failover, and will be marked as a failure to deliver.

Settings

The following table describes the settings for Voxeo protocol providers.

Setting	Description
Name	Name of the protocol provider.
Description	A brief description of the provider (optional).
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry Interval	Amount of time in seconds to wait between retries; allowable values are from 5 to 999.
API URL	URL to the API interface provided by Voxeo to post requests; for example: http://api.voxeo.net/SessionControl/XXX111.start
Response URL	URL within the xMatters interface called by the device engine when a response is received from Voxeo. If the response is successful, xMatters calls the Response URL to audit the relevant information the syntax for this URL is as follows: http://wsuser:wspass@host:port/voicexml/voxeo/processVoxeoResponse.jsp Replace "wsuser" with the web services user's name and "wspass" with their password. Replace "host:port" with the host name or IP address and port number of the xMatters web server.
API Key	The token provided by Voxeo to authenticate and validate the HTTP session.
Request Parameters	This area displays an editable list of HTTP request parameters available to this provider. This list is typically specified by the web API. Click Add New Name/Value Pair to create a new request parameter, and then specify a Name and Value in the related fields. To remove a request parameter, select the related check box and then click Remove Selected Name/Value Pair. Note that all Voxeo protocol providers include mandatory request parameters used by the node as placeholders; they are replaced with actual values during notification processing. These default parameters cannot be modified or removed.

WCTP

The following table describes the settings for WCTP protocol providers.

Setting	Description
Name	Name of the service provider.
Description	Description of the provider.
Maximum Retries	Number of times to resend a notification before potentially using an alternate service provider; allowable values are from 0 to 10.
Retry interval	Amount of time in seconds to wait between retries.
Maximum session size	Number of notifications per connection/session
Split long message	Controls whether notifications that exceed the number of characters specified by the Split size setting are split into multiple smaller messages or sent as a single message.
Split size	Determines the maximum number of characters per message sent to this protocol provider. This setting applies only if the Split long message check box is selected.
Maximum message length	If enforced by this provider, the maximum number of characters allowed per notification. For more information, see Set maximum message length.
Maximum PIN length	If enforced by this provider, the maximum number of characters allowed in a PIN. If the PIN is longer than the maximum PIN length, the leading characters are truncated.
Server Address	URL or IP address for the protocol provider’s server; e.g.: http://100.100.100.100:8888/applications/myapp https://wctp.url.com/wctp
Account	Account name, if required by your service provider.
Password	Password, if required by your service provider.
Default Poll Period	Specifies how long, in seconds, the device engine should continue to poll the WCTP server every minute for responses to each notification; the default is 3600 (one hour). Note that this setting does not specify how often the WCTP server should be polled.