Add documentation for simwood sip extensions

docs/wholesale/sip_extensions/v1.2.md

@@ -0,0 +1,180 @@
+---
+
+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 standardised on the X-simwoodprefix 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 fllter 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 special function as detailed below)
+
+examples:
+```json
+
+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:
+
+```json
+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 use of different username/passwords or dedicated IP addresses
+
+Example:
+
+```json
+ 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
+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:
+
+```json
+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:
+
+```json
+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.**
+
+```json
+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.**
+
+```json
+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'],
+      },
     ]
 
   },