diff --git a/docs/wholesale/sip_extensions/v1.2.md b/docs/wholesale/sip_extensions/v1.2.md new file mode 100644 index 0000000..f4e213c --- /dev/null +++ b/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 \ No newline at end of file diff --git a/sidebars.js b/sidebars.js index edbd84f..ea2320f 100644 --- a/sidebars.js +++ b/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'], + }, ] },