Add documentation for simwood sip extensions

docs/wholesale/sip_extensions/v1.2.md

@@ -0,0 +1,187 @@
+---
+
+title: SIP Extensions
+
+---
+
+## Overview
+
+### What is it?
+
+The Simwood SIP Extensions extend the SIP protocol using additional headers to control call flow and enable advanced call control, fraud prevention and billing/accounting features.
+
+### Intended Audience
+
+This document is aimed at developers, operators and integrators who are familiar with the SIP protocol.
+
+## How to Use
+
+### SIP Protocol
+
+The SIP Extensions are all implemented by means of custom headers that are prefixed X-simwood and should be sent with the initial INVITE when placing the call.
+
+### X-Headers
+
+The X- prefix has been established over many years, initially in RFC 691, to be used for “experimental” additions to protocols and in later years [RFC 1154, 2616] to be used to denote “implementation-specific use”.
+
+Whilst there has been an attempt to deprecate them [RFC 6648], we have standardized on the X-simwood prefix for the following reasons:
+
+- The established X- prefix ensures that most SIP platforms will ignore, but forward, any X- header contained within a SIP message.
+- Use of X-simwood ensures that there is no risk of any of our extensions already being used by any other application, or your own platform.
+- It is easy to filter X-simwood-prefixed headers at your SIP proxies to prevent them being exposed to your end users.
+
+### X-Reason
+
+In addition to X-simwood, you will occasionally receive X-Reason headers [RFC 3326] which may contain information pertaining to your account or trunk-specific restrictions. We would therefore generally recommend that you also filter these in responses that are sent to your end users.
+
+**NB** The content and format of the X-Reason header is intended to be human-readable and is subject to change without notice. It should not be relied upon for automatic processing.
+
+### Custom Headers
+
+#### Billing Reconciliation / Call Tagging
+
+The call tag is visible in your CDRs and can be used during your own post-processing; however, please note it is not currently possible to search for a call by tag. If you wish to group calls in a searchable manner, you should use individual trunks, which can be created and managed via the API.
+
+##### X-simwood-tag: [STRING]
+
+Sets a ‘tag’ on a per-call basis that will be displayed in the CDRs alongside the other call details.
+
+This can contain any freeform text, e.g., the caller’s extension, your own account ID, or your own local call identifier to enable easier billing reconciliation.
+
+**NB** Most printable characters can be used, but we strongly advise using only A-Za-z0-9 and _ (please note: a single dash has a special function as detailed below)
+
+Examples:
+
+```
+X-simwood-tag: A010349
+X-simwood-tag: 07700900123
+X-simwood-tag: Acme Products
+X-simwood-tag: fb254080_3517_11e4_ad0b_0002a5d5c51b
+```
+
+Multiple tag search terms may be separated with the - (single dash) character. If you need to be able to search on a unique ID that contains a -, we would recommend replacing it with an underscore or similar character.
+
+The following example would be returned as shown, but you could search on both the terms CUST001 and AB384720 (but not the term CUST001-AB384720 as a whole)
+
+Example:
+
+```
+X-simwood-tag: CUST001-AB384720
+```
+
+##### Trunk Selection
+
+Please note that this header, where present, takes precedence over the trunk associated with the IP address which the call originates from. Therefore, an IP that is normally associated with your -L001 trunk can be used to effectively place calls ‘on’ any trunk.
+
+##### X-simwood-trunk: [STRING]
+
+Associate a call with another trunk on your account.
+
+This allows you to split calls by customer trunk and take advantage of per-trunk limitations (e.g., channel or rate limits) without necessitating the use of different username/passwords or dedicated IP addresses.
+
+Example:
+
+```
+X-simwood-trunk: 920700-L001
+X-simwood-trunk: 920700-ACMEPRODUCTS
+```
+
+#### Fraud Prevention / Revenue Protection
+
+These functions can be used for fraud prevention (e.g., a default maxcpc/maxcpm of 0.10 on all your customer calls will prevent any calls in excess of 0.10/min being made on your account, effectively limiting your exposure to fraudulent traffic to high-value international destinations).
+
+Likewise, you may wish to use this when providing NTS-like services to ensure the destination number cannot cost more than the revenue received from the inbound leg.
+
+You can also limit a call by cost or duration dynamically with SIP headers, perhaps preventing a customer from exceeding their balance or credit limit, by calculating the maximum call duration or cost price in advance.
+
+##### X-simwood-maxcpc: [DECIMAL]
+
+Maximum cost per connection, specified in your account currency, intended to be used in conjunction with maxcpm (below). Where the connection cost exceeds this value, the call will be rejected.
+
+If maxcpm (below) is specified, and maxcpc is not, the maxcpc value defaults to 0.
+
+Example:
+
+```
+X-simwood-maxcpc: 0.10
+```
+
+##### X-simwood-maxcpm: [DECIMAL]
+
+Maximum cost per minute. Where the cost per minute will exceed this value, the call will be rejected.
+
+Example:
+
+```
+X-simwood-maxcpm: 0.10
+```
+
+**NB** These are designed to be used together, and where a maxcpm value is specified, a maxcpc of 0 is assumed, which will prevent calls to any number that incurs a connection charge or fixed fee.
+
+##### X-simwood-maxcost: [DECIMAL]
+
+Maximum cost of a call, specified in your account currency. Unlike the above maxcpc and maxcpm options, this is not considered at the start of a call but instead implements a limit on the maximum cost of the call, when this cost is exceeded, the call will be automatically cleared by Simwood.
+
+**Please note that this is an approximation, and there is a possibility that calls will exceed the specified limit by a small amount, and is intended for fraud prevention and revenue protection, not accurate credit control purposes.**
+
+```
+X-simwood-maxcost: 10.00
+```
+
+##### X-simwood-maxdur: [INTEGER (Seconds)]
+
+Maximum duration of a call in seconds. Much like maxcost above, this implements a limit on the maximum duration of the call, when this duration is reached, the call will be automatically cleared by Simwood.
+
+**Please note that this is an approximation, and there is a possibility that calls will exceed the specified limit by a small amount, and is intended for fraud prevention and revenue protection, not accurate credit control purposes.**
+
+```
+X-simwood-maxdur: 7200
+```
+
+#### X-Reason Responses
+
+The following is a non-exhaustive list of possible responses contained within the X-Reason header that you may receive when a call is rejected or cleared automatically.
+
+This is designed to be illustrative - the content and format of the X-Reason header is intended to be human-readable and is subject to change without notice. It should not be relied upon for automatic processing.
+
+**Origination Errors**
+
+```
+Invalid Trunk
+Invalid CLI
+Blacklisted Destination
+```
+
+**User-Controlled Limits**
+
+```
+Blacklisted Destination
+User account rate limit of X [type] calls per Y
+User trunk rate limit of X [type] calls per Y
+Channel Limit Exceeded [(type)]
+Maximum Cost Reached
+Maximum Duration Reached
+```
+
+**Account Limits**
+
+```
+Channel Limit Exceeded [(type)]
+Balance now below limit
+Balance exhausted
+Credit limit exceeded
+Balance-Related Channel Limit Exceeded
+Balance-Related account rate limit of X calls per Y
+```
+
+#### X-Warning Responses
+
+From time to time, we may send an X-Warning header with a response. The call will complete as intended; however, it warns of an irregularity with the initial INVITE message, which may result in the call failing over some carriers or, in the future, may be rejected.
+
+As above, the following is a non-exhaustive list that is intended to be illustrative of the errors that you may receive when sending calls;
+
+**Origination Errors**
+
+```
+Invalid CLI
+```

sidebars.js

@@ -57,6 +57,11 @@ const sidebars = {
         label: 'APIs',
         items: ['wholesale/api/v3'],
       },
+      {
+        type: 'category',
+        label: 'SIP Extensions',
+        items: ['wholesale/sip_extensions/v1.2'],
+      },
     ]
 
   },