From b02905610db522e1b97a73ef2c900bbf6e7ff24d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6ran=20Vinzens?= Date: Tue, 17 Dec 2024 09:11:32 +0100 Subject: [PATCH 1/6] doc: add ARI channel_tranfer documentation --- .../index.md | 78 +++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md diff --git a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md new file mode 100644 index 0000000000..996ce95538 --- /dev/null +++ b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md @@ -0,0 +1,78 @@ +--- +title: Overview +pageid: 29396202 +--- + +# Transfer Handling + +## Introduction + +Transfer is a telephony feature. There are two types of transfer, attendant and blind. These names may differ depending on the system you are looking on, or what background you have. + +The ARI transfer handling is supposed to be used in an ARI only environment. Using ARI for ARI Controlled and non ARI controlled Channels is not possible. + +### Attendant Transfer +Attendant transfer happens, if a call on hold and an active call are connected on request of the user. The user can talk to both parties before connecting them. This is also called a consultative transfer. + +### Blind Transfer +Blind transfer happens, if the user transfer the active call to a destination, not knowing the state or reachability of the destination. The user does not talk to the destination before the transfer.Bild transfer is also called a cold transfer. + +## Transfer handling in SIP + +In SIP there is a method called `REFER`. This method, if triggered by the user contains all the known information by the phone about what calls shall be connected. The SIP Server send back a direct response to the user. The Response in case the PBX will try to handle the REFER is an 202 Accepted. After that the PBX will Notify the user by `Notify` method about the current state of the transfer. + +## Transfer handling in ARI + +Asterisk handles the REFER without any config changes by itself. To have ARI handle the transfer you need to change a setting so the ARI events are generated. If done, the `channelTransferEvent` will be generated in case a `REFER` is received. The `channelTransferEvent` contains the information about the transfer. The `channelTransferEvent` is generated for both, blind and attendant transfer. + +### Information within the `channelTransferEvent` + +Asterisk try to get as much information as possible about the transfer. The `REFER` does only contain the corresponding SIP-Call ID. With this SIP-Call ID, asterisk try to resolve the Channel-ID used by ARI for the Channel. + +During a Transfer Scenario there are a lot of moving parts involved. A Typical Setup for an attendant transfer lokks like this: + +Channel A --- Bridge 1 -X- Channel B + +Channel C --- Bridge 2 --- Channel D + +Where the Channel marked with an "X" ist set on hold Channel A should receive MOH but this is not necessary. +Depending on the used Phone a SIP REFER is send to the Channel B or D. Either way, Asterisk tries to resolve all the channel information involved. +the `channelTransferEvent` contains both `refere-to` and `refered-by` information. +The `refere-to` sections will always contain information about the SIP-Call ID in the field `requested-destination`. This is the information we receive from the phone. +In addition, the `refere-to` does contain, as far as the Asterisk could resolve it, the information about the own `channel-id` the `bridge-id` the channel is connected to and the connected `channel-id`. Relating to the schema above the `refere-to` would contain Channel B, Bridge 1 and Channel A, if the REFER is received on Channel D. + +If the Asterisk is not able to resolve the Channel and Bridge IDs the SIP Call ID is transmitted anyhow. If the asterisk is running in a larger environment and cannot resolve the Call ID by itself, the ARI Application MUST keep track of all ongoing SIP Calls and it MUST resolve the corresponding Channel IDs and Bridges by itself. + +Corresponding to the `refere-to` the `refered-by` section contains the information about the Channel and Bridge the REFER was received on. Related to the schema above it would contain Channel D, Bridge 2 and Channel C. + +### Actions after the Event is received + +The ARI application MUST take some action in order to handle the REFER. The Asterisk will not do anything by itself. The First thing to do when received an SIP REFER is acknowledge it. This is done by the Asterisk As well as the first `NOTIFY` telling the Phone an `100 Trying`. After that, the telefon waits for an Notify containing a SIP Frag with `200 OK`. This has to be send by ARI Application manually. + +Actions what needs to be done by ARI Application for the schema above: + +* Remove Channel C from Bridge 2 +* Remove Channel B from Bridge 1 +* Add Channel C to Bridge 1 +* Delete Bridge 2 +* Send a `200 OK` to the Phone +* Delete Channel B +* Delete Channel D (if not done by phone) + + +there is a REST Route to transmit the necessary information to the phone + +`/ari/channels//transfer_progress` where the body does contain the information. + +to transmit the successful transfer to the phone the body must contain `{"states":"channel_answered"}` + +there are different options to transmit the current state: + +* channel_progress +* channel_answered +* channel_unavailable +* channel_declined + +these will result in the corresponding SIP Frag Status Codes tramit via SIP Notify to the phone. `channel_progress` will do nothing but tell the phone to hold on. This is donw by asterisk itself but can be repeated. The other responses will terminate the REFER process in the on or the other way. Using `answered` the phone will most likeley hangup the active channel and will wait for the hangup of the other one. + + From e63dafb99b28e5195ebc8a3e0d5bd8cad95386c8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6ran=20Vinzens?= Date: Tue, 17 Dec 2024 12:11:54 +0100 Subject: [PATCH 2/6] chore: add multi asterisk descrition also: be more specific about blind transfer also: fix typos --- .../index.md | 82 +++++++++++++++++-- 1 file changed, 75 insertions(+), 7 deletions(-) diff --git a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md index 996ce95538..c76bc2a0ad 100644 --- a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md +++ b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md @@ -9,7 +9,7 @@ pageid: 29396202 Transfer is a telephony feature. There are two types of transfer, attendant and blind. These names may differ depending on the system you are looking on, or what background you have. -The ARI transfer handling is supposed to be used in an ARI only environment. Using ARI for ARI Controlled and non ARI controlled Channels is not possible. +The ARI transfer handling is supposed to be used in an ARI only environment. to Control a traditional channel or bridge wie ARI is not possible since it needs to be in an Stasis Context. Please refer to "how to use ARI" for more information. For this scenario all channels and bridges need to bei placed into an ARI context. ### Attendant Transfer Attendant transfer happens, if a call on hold and an active call are connected on request of the user. The user can talk to both parties before connecting them. This is also called a consultative transfer. @@ -27,13 +27,18 @@ Asterisk handles the REFER without any config changes by itself. To have ARI han ### Information within the `channelTransferEvent` +#### Attendant Transfer + Asterisk try to get as much information as possible about the transfer. The `REFER` does only contain the corresponding SIP-Call ID. With this SIP-Call ID, asterisk try to resolve the Channel-ID used by ARI for the Channel. -During a Transfer Scenario there are a lot of moving parts involved. A Typical Setup for an attendant transfer lokks like this: +During a Transfer Scenario there are a lot of moving parts involved. A Typical Setup for an attendant transfer looks like this: +Call schema 1 +``` Channel A --- Bridge 1 -X- Channel B Channel C --- Bridge 2 --- Channel D +``` Where the Channel marked with an "X" ist set on hold Channel A should receive MOH but this is not necessary. Depending on the used Phone a SIP REFER is send to the Channel B or D. Either way, Asterisk tries to resolve all the channel information involved. @@ -41,15 +46,29 @@ the `channelTransferEvent` contains both `refere-to` and `refered-by` informatio The `refere-to` sections will always contain information about the SIP-Call ID in the field `requested-destination`. This is the information we receive from the phone. In addition, the `refere-to` does contain, as far as the Asterisk could resolve it, the information about the own `channel-id` the `bridge-id` the channel is connected to and the connected `channel-id`. Relating to the schema above the `refere-to` would contain Channel B, Bridge 1 and Channel A, if the REFER is received on Channel D. -If the Asterisk is not able to resolve the Channel and Bridge IDs the SIP Call ID is transmitted anyhow. If the asterisk is running in a larger environment and cannot resolve the Call ID by itself, the ARI Application MUST keep track of all ongoing SIP Calls and it MUST resolve the corresponding Channel IDs and Bridges by itself. - Corresponding to the `refere-to` the `refered-by` section contains the information about the Channel and Bridge the REFER was received on. Related to the schema above it would contain Channel D, Bridge 2 and Channel C. +#### Blind Transfer + +Here the information `refer-to` contains the destination to where the call should be placed. This information is dialed by the user and most likely follows the dial schema the user is used to. In most cases the user dialed a phone number. + +The `refered-by` section does contain exactly what it does for the attendant transfer. + +the Call scenario would look like: + +Call schema 2 +``` +Channel A --- Bridge 1 -X- Channel B +``` + +Where the Channel marked with the "X" might be placed on hold, or not. + ### Actions after the Event is received -The ARI application MUST take some action in order to handle the REFER. The Asterisk will not do anything by itself. The First thing to do when received an SIP REFER is acknowledge it. This is done by the Asterisk As well as the first `NOTIFY` telling the Phone an `100 Trying`. After that, the telefon waits for an Notify containing a SIP Frag with `200 OK`. This has to be send by ARI Application manually. +#### Attendant Transfer +The ARI application MUST take some action in order to handle the REFER. The Asterisk will not do anything by itself. The First thing to do when received an SIP REFER is acknowledge it. This is done by the Asterisk, as well as the first `NOTIFY` telling the Phone an `100 Trying` SIP Frag. After that, the telefon waits for a Notify containing a SIP Frag with `200 OK`. This has to be sent by ARI Application manually. -Actions what needs to be done by ARI Application for the schema above: +Actions what needs to be done by ARI Application for the call schema 1 above: * Remove Channel C from Bridge 2 * Remove Channel B from Bridge 1 @@ -73,6 +92,55 @@ there are different options to transmit the current state: * channel_unavailable * channel_declined -these will result in the corresponding SIP Frag Status Codes tramit via SIP Notify to the phone. `channel_progress` will do nothing but tell the phone to hold on. This is donw by asterisk itself but can be repeated. The other responses will terminate the REFER process in the on or the other way. Using `answered` the phone will most likeley hangup the active channel and will wait for the hangup of the other one. +these will result in the corresponding SIP Frag Status Codes transmit via SIP Notify to the phone. `channel_progress` will do nothing but tell the phone to hold on. This is done by asterisk itself but can be repeated. The other responses will terminate the REFER process in the one or the other way. Using `answered` the phone will most likely hangup the active channel and will wait for the hangup of the other one. + + +#### Blind Transfer + +Here the scenario is much simpler. In order to complete the transfer the ARI Application needs to place a new call to the destination, requested within the `refer-to`section of the `channelTransferEvent`. + +Actions what needs to be done by ARI Application for the call schema 2 above: + +* remove Channel B from bridge 1 +* Create and Dial a new Channel to the destination +* Add the new Channel into the Bridge 1 + +## Transfer handling for multi Asterisk setups + +There are installations where the asterisk is used like a media server and sourrounded by SIP Proxy or SBC like Kamailio or OpeSips. In these cases the Asterisk is not used as a traditional PBX and it is not the entry point for calls from phones. In these scenarios it might happen, the asterisk does not know all related channels. + +A scenario could look like this: + + +``` +Phone A --- Kamailio --- Asterisk 1 --- Kamailio - + \ + >--- Phone B + / +Phone C --- Kamailio --- Asterisk 2 --- Kamailio - + +``` +Each Asterisk (1 and 2) is involved but cannot know the other Call ID or Channel. +The ARI Application must be the central point in this case. +``` +Phone A --- Kamailio --- Asterisk 1 --- Kamailio ---- + \ \ + >-- ARI Application >--- Phone B + / / +Phone C --- Kamailio --- Asterisk 2 --- Kamailio ----- + +``` +Both Channels to Phone B are paced by the same ARI Application (or they share the same knowledge about ongoing calls). + +If an SIP `REFER` hits one Asterisk instance, the Asterisk will publish the `channelTransferEvent` without any destination Channel ID or Bridge ID but the SIP Call ID. The ARI Application is now able to establish a new Call between the Asterisk instances to complete the transfer. The Scenario after the Transfer would look like this: + + +``` +Phone A --- Kamailio --- Asterisk 1 -------------- + \ \ + >-- ARI Application | SIP Channel + / / +Phone C --- Kamailio --- Asterisk 2 -------------- +``` From 1023737823c7976d10280b7ecdf0ff402bdd1fdc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6ran=20Vinzens?= Date: Wed, 18 Dec 2024 07:48:37 +0100 Subject: [PATCH 3/6] fix: typo --- .../Introduction-to-ARI-Transfer-Handling/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md index c76bc2a0ad..e2d5acf3e0 100644 --- a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md +++ b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md @@ -9,7 +9,7 @@ pageid: 29396202 Transfer is a telephony feature. There are two types of transfer, attendant and blind. These names may differ depending on the system you are looking on, or what background you have. -The ARI transfer handling is supposed to be used in an ARI only environment. to Control a traditional channel or bridge wie ARI is not possible since it needs to be in an Stasis Context. Please refer to "how to use ARI" for more information. For this scenario all channels and bridges need to bei placed into an ARI context. +The ARI transfer handling is supposed to be used in an ARI only environment. to Control a traditional channel or bridge wie ARI is not possible since it needs to be in a Stasis Context. Please refer to "how to use ARI" for more information. For this scenario all channels and bridges need to bei placed into an ARI context. ### Attendant Transfer Attendant transfer happens, if a call on hold and an active call are connected on request of the user. The user can talk to both parties before connecting them. This is also called a consultative transfer. @@ -107,7 +107,7 @@ Actions what needs to be done by ARI Application for the call schema 2 above: ## Transfer handling for multi Asterisk setups -There are installations where the asterisk is used like a media server and sourrounded by SIP Proxy or SBC like Kamailio or OpeSips. In these cases the Asterisk is not used as a traditional PBX and it is not the entry point for calls from phones. In these scenarios it might happen, the asterisk does not know all related channels. +There are installations where the asterisk is used like a media server and surrounded by SIP Proxy or SBC like Kamailio or OpeSips. In these cases the Asterisk is not used as a traditional PBX and it is not the entry point for calls from phones. In these scenarios it might happen, the asterisk does not know all related channels. A scenario could look like this: From 5e004685dd65aa4aff139782716874f5061fdc85 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6ran=20Vinzens?= Date: Fri, 31 Jan 2025 11:58:54 +0100 Subject: [PATCH 4/6] chore: delete pageid --- .../Introduction-to-ARI-Transfer-Handling/index.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md index e2d5acf3e0..27f2fd39a1 100644 --- a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md +++ b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md @@ -1,8 +1,3 @@ ---- -title: Overview -pageid: 29396202 ---- - # Transfer Handling ## Introduction From 25ff719134d6c12587d4357245c6a7cb8b5dc0ee Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6ran=20Vinzens?= Date: Fri, 31 Jan 2025 16:18:34 +0100 Subject: [PATCH 5/6] fix: typo --- .../index.md | 100 +++++++++--------- 1 file changed, 48 insertions(+), 52 deletions(-) diff --git a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md index 27f2fd39a1..ebf96a70e7 100644 --- a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md +++ b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md @@ -2,107 +2,103 @@ ## Introduction -Transfer is a telephony feature. There are two types of transfer, attendant and blind. These names may differ depending on the system you are looking on, or what background you have. +Transfer is a telephony feature. There are two types of transfer, attended and blind. These names may differ depending on the system you are looking on, or what background you have. -The ARI transfer handling is supposed to be used in an ARI only environment. to Control a traditional channel or bridge wie ARI is not possible since it needs to be in a Stasis Context. Please refer to "how to use ARI" for more information. For this scenario all channels and bridges need to bei placed into an ARI context. +The ARI transfer handling is supposed to be used in an ARI only environment to control a traditional channel or bridge wie ARI is not possible since it needs to be in a Stasis context. Please refer to "how to use ARI" for more information. For this scenario all channels and bridges need to be placed into an ARI context. -### Attendant Transfer -Attendant transfer happens, if a call on hold and an active call are connected on request of the user. The user can talk to both parties before connecting them. This is also called a consultative transfer. +### Attended transfer +Attended transfer happens, if a call on hold and an active call are connected on request of the user. The user can talk to both parties before connecting them. This is also called a consultative transfer. -### Blind Transfer -Blind transfer happens, if the user transfer the active call to a destination, not knowing the state or reachability of the destination. The user does not talk to the destination before the transfer.Bild transfer is also called a cold transfer. +### Blind transfer +Blind transfer happens, if the user transfers the active call to a destination, not knowing the state or reachability of the destination. The user does not talk to the destination before the transfer.Blind transfer is also called a cold transfer. ## Transfer handling in SIP -In SIP there is a method called `REFER`. This method, if triggered by the user contains all the known information by the phone about what calls shall be connected. The SIP Server send back a direct response to the user. The Response in case the PBX will try to handle the REFER is an 202 Accepted. After that the PBX will Notify the user by `Notify` method about the current state of the transfer. +In SIP there is a method called `REFER`. This method, if triggered by the user, contains all the known information by the phone about what calls shall be connected. The SIP Server sends back a direct response to the user. The response in case the PBX will try to handle the REFER is an 202 Accepted. After that the PBX will notify the user by using the `Notify` method about the current state of the transfer. ## Transfer handling in ARI -Asterisk handles the REFER without any config changes by itself. To have ARI handle the transfer you need to change a setting so the ARI events are generated. If done, the `channelTransferEvent` will be generated in case a `REFER` is received. The `channelTransferEvent` contains the information about the transfer. The `channelTransferEvent` is generated for both, blind and attendant transfer. +Asterisk handles the REFER without any config changes by itself. To have ARI handle the transfer you need to change a setting so the ARI events are generated. If done, the `channelTransferEvent` will be generated in case a `REFER` is received. The `channelTransferEvent` contains the information about the transfer. The `channelTransferEvent` is generated for both, blind and attended transfer. ### Information within the `channelTransferEvent` -#### Attendant Transfer +#### Attended transfer -Asterisk try to get as much information as possible about the transfer. The `REFER` does only contain the corresponding SIP-Call ID. With this SIP-Call ID, asterisk try to resolve the Channel-ID used by ARI for the Channel. +Asterisk will try to get as much information as possible about the transfer. The `REFER` does only contain the corresponding SIP-Call ID. With this SIP-Call ID, asterisk try to resolve the channel-ID used by ARI for the channel. -During a Transfer Scenario there are a lot of moving parts involved. A Typical Setup for an attendant transfer looks like this: +During a transfer scenario there are a lot of moving parts involved. A typical setup for an attended transfer looks like this: Call schema 1 ``` -Channel A --- Bridge 1 -X- Channel B +channel A --- bridge 1 -X- channel B -Channel C --- Bridge 2 --- Channel D +channel C --- bridge 2 --- channel D ``` -Where the Channel marked with an "X" ist set on hold Channel A should receive MOH but this is not necessary. -Depending on the used Phone a SIP REFER is send to the Channel B or D. Either way, Asterisk tries to resolve all the channel information involved. +Where the channel marked with an "X" is set on hold, channel A should receive MOH but this is not necessary. +Depending on the used phone a SIP REFER is send to the channel B or D. Either way, Asterisk tries to resolve all the channel information involved. the `channelTransferEvent` contains both `refere-to` and `refered-by` information. The `refere-to` sections will always contain information about the SIP-Call ID in the field `requested-destination`. This is the information we receive from the phone. -In addition, the `refere-to` does contain, as far as the Asterisk could resolve it, the information about the own `channel-id` the `bridge-id` the channel is connected to and the connected `channel-id`. Relating to the schema above the `refere-to` would contain Channel B, Bridge 1 and Channel A, if the REFER is received on Channel D. +In addition, the `refere-to` does contain, as far as the Asterisk could resolve it, the information about the own `channel-id` the `bridge-id` the channel is connected to and the connected `channel-id`. Relating to the schema above the `refere-to` would contain channel B, bridge 1 and channel A, if the REFER is received on channel D. -Corresponding to the `refere-to` the `refered-by` section contains the information about the Channel and Bridge the REFER was received on. Related to the schema above it would contain Channel D, Bridge 2 and Channel C. +Corresponding to the `refere-to` the `refered-by` section contains the information about the channel and bridge the REFER was received on. Related to the schema above it would contain channel D, bridge 2 and channel C. -#### Blind Transfer +#### Blind transfer Here the information `refer-to` contains the destination to where the call should be placed. This information is dialed by the user and most likely follows the dial schema the user is used to. In most cases the user dialed a phone number. -The `refered-by` section does contain exactly what it does for the attendant transfer. +The `refered-by` section does contain exactly what it does for the attended transfer. -the Call scenario would look like: +The call scenario would look like: Call schema 2 ``` -Channel A --- Bridge 1 -X- Channel B +channel A --- bridge 1 -X- channel B ``` -Where the Channel marked with the "X" might be placed on hold, or not. +Where the channel marked with the "X" might be placed on hold, or not. -### Actions after the Event is received +### Actions after the event is received -#### Attendant Transfer -The ARI application MUST take some action in order to handle the REFER. The Asterisk will not do anything by itself. The First thing to do when received an SIP REFER is acknowledge it. This is done by the Asterisk, as well as the first `NOTIFY` telling the Phone an `100 Trying` SIP Frag. After that, the telefon waits for a Notify containing a SIP Frag with `200 OK`. This has to be sent by ARI Application manually. +#### Attended transfer +The ARI application MUST take some action in order to handle the REFER. The Asterisk will not do anything by itself. The first thing to do when received an SIP REFER is acknowledge it. This is done by the Asterisk, as well as the first `NOTIFY` telling the phone an `100 Trying` SIP frag. After that, the telephon waits for a `Notify` containing a SIP frag with `200 OK`. This has to be sent by the ARI application manually. -Actions what needs to be done by ARI Application for the call schema 1 above: +Actions that should be taken by the ARI application in the scenario described in call schema 1: -* Remove Channel C from Bridge 2 -* Remove Channel B from Bridge 1 -* Add Channel C to Bridge 1 -* Delete Bridge 2 -* Send a `200 OK` to the Phone -* Delete Channel B -* Delete Channel D (if not done by phone) +* Remove channel C from bridge 2 +* Remove channel B from bridge 1 +* Add channel C to bridge 1 +* Delete bridge 2 +* Send a `200 OK` to the phone +* Delete channel B +* Delete channel D (if not done by phone) - -there is a REST Route to transmit the necessary information to the phone +There is a REST route to transmit the necessary information to the phone. `/ari/channels//transfer_progress` where the body does contain the information. - -to transmit the successful transfer to the phone the body must contain `{"states":"channel_answered"}` - -there are different options to transmit the current state: +To transmit the successful transfer to the phone the body must contain `{"states":"channel_answered"}` +There are different options to transmit the current state: * channel_progress * channel_answered * channel_unavailable * channel_declined -these will result in the corresponding SIP Frag Status Codes transmit via SIP Notify to the phone. `channel_progress` will do nothing but tell the phone to hold on. This is done by asterisk itself but can be repeated. The other responses will terminate the REFER process in the one or the other way. Using `answered` the phone will most likely hangup the active channel and will wait for the hangup of the other one. - +these will result in the corresponding SIP frag status codes being transmit via SIP notify to the phone. `channel_progress` will do nothing but tell the phone to hold on. This is done by asterisk itself but can be repeated. The other responses will terminate the REFER process in the one or the other way. Using `answered` the phone will most likely hangup the active channel and will wait for the hangup of the other one. -#### Blind Transfer +#### Blind transfer -Here the scenario is much simpler. In order to complete the transfer the ARI Application needs to place a new call to the destination, requested within the `refer-to`section of the `channelTransferEvent`. +Here the scenario is much simpler. In order to complete the transfer, the ARI application needs to place a new call to the destination, requested within the `refer-to`section of the `channelTransferEvent`. -Actions what needs to be done by ARI Application for the call schema 2 above: +Actions that should be taken by the ARI application in the scenario described in call schema 2: -* remove Channel B from bridge 1 -* Create and Dial a new Channel to the destination -* Add the new Channel into the Bridge 1 +* remove channel B from bridge 1 +* Create and dial a new channel to the destination +* Add the new channel into the bridge 1 ## Transfer handling for multi Asterisk setups -There are installations where the asterisk is used like a media server and surrounded by SIP Proxy or SBC like Kamailio or OpeSips. In these cases the Asterisk is not used as a traditional PBX and it is not the entry point for calls from phones. In these scenarios it might happen, the asterisk does not know all related channels. +There are installations where the Asterisk is used like a media server and surrounded by SIP proxy or SBC like Kamailio or OpenSips. In these cases the Asterisk is not used as a traditional PBX and it is not the entry point for calls from phones. In these scenarios it might happen, the asterisk does not know all related channels. A scenario could look like this: @@ -116,18 +112,18 @@ Phone C --- Kamailio --- Asterisk 2 --- Kamailio - ``` Each Asterisk (1 and 2) is involved but cannot know the other Call ID or Channel. -The ARI Application must be the central point in this case. +The ARI application must be the central point in this case. ``` Phone A --- Kamailio --- Asterisk 1 --- Kamailio ---- \ \ - >-- ARI Application >--- Phone B + >-- ARI application >--- Phone B / / Phone C --- Kamailio --- Asterisk 2 --- Kamailio ----- ``` -Both Channels to Phone B are paced by the same ARI Application (or they share the same knowledge about ongoing calls). +Both channels to phone B are placed by the same ARI application (or they share the same knowledge about ongoing calls). -If an SIP `REFER` hits one Asterisk instance, the Asterisk will publish the `channelTransferEvent` without any destination Channel ID or Bridge ID but the SIP Call ID. The ARI Application is now able to establish a new Call between the Asterisk instances to complete the transfer. The Scenario after the Transfer would look like this: +If an SIP `REFER` reaches one Asterisk instance, the Asterisk will publish the `channelTransferEvent` without any destination channel ID or bridge ID but the SIP call ID. The ARI application is now able to establish a new call between the Asterisk instances to complete the transfer. The Scenario after the transfer would look like this: From 625daeeb371485ec21ef5a22ae698c2290d7681c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=B6ran=20Vinzens?= Date: Fri, 31 Jan 2025 16:21:52 +0100 Subject: [PATCH 6/6] fix: typo --- .../Introduction-to-ARI-Transfer-Handling/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md index ebf96a70e7..d39b3421f4 100644 --- a/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md +++ b/docs/Configuration/Interfaces/Asterisk-REST-Interface-ARI/Introduction-to-ARI-Transfer-Handling/index.md @@ -4,7 +4,7 @@ Transfer is a telephony feature. There are two types of transfer, attended and blind. These names may differ depending on the system you are looking on, or what background you have. -The ARI transfer handling is supposed to be used in an ARI only environment to control a traditional channel or bridge wie ARI is not possible since it needs to be in a Stasis context. Please refer to "how to use ARI" for more information. For this scenario all channels and bridges need to be placed into an ARI context. +The ARI transfer handling is supposed to be used in an ARI only environment to control a traditional channel or bridge with ARI is not possible since it needs to be in a Stasis context. Please refer to "how to use ARI" for more information. For this scenario all channels and bridges need to be placed into an ARI context. ### Attended transfer Attended transfer happens, if a call on hold and an active call are connected on request of the user. The user can talk to both parties before connecting them. This is also called a consultative transfer.