[WAZO-3963] selectable caller id

website/uc-doc/administration/callerid.md

@@ -1,19 +1,19 @@
 ---
-title: CallerID
+title: Caller ID
 ---
 
-The CallerID is what users see on their phones when they emit or receive a call, e.g.
+The Caller ID is what users see on their phones when they emit or receive a call, e.g.
 `Rick Sanchez 963-555-9296`.
 
-The CallerID is composed of two parts: the CallerID name and the CallerID number.
+The Caller ID is composed of two parts: the Caller ID name and the Caller ID number.
 
 In Wazo, the format is: `"Rick Sanchez" <9635559296>`.
 
-## CallerID for internal calls
+## Caller ID for internal calls
 
-Users calling each other will see the CallerID configured in the `caller_id` field of each user.
+Users calling each other will see the Caller ID configured in the `caller_id` field of each user.
 
-## CallerID for outgoing calls (through a trunk)
+## Caller ID for outgoing calls (through a trunk)
 
 There are multiple settings coming into play:
 
@@ -24,19 +24,19 @@ There are multiple settings coming into play:
 
 The current logic for outgoing calls is:
 
-- If the call uses dynamic caller ID selection use the received CallerID
-- If the call is not emitted by a user: use the outgoing call's CallerID
+- If the call uses dynamic caller ID selection use the received Caller ID
+- If the call is not emitted by a user: use the outgoing call's Caller ID
 - If the call is emitted by a user:
-  - If the `outgoing_caller_id` is Default, use the outgoing call's CallerID
-  - If the `outgoing_caller_id` is Anonymous, remove the CallerID
+  - If the `outgoing_caller_id` is Default, use the outgoing call's Caller ID
+  - If the `outgoing_caller_id` is Anonymous, remove the Caller ID
   - If the `outgoing_caller_id` is set, use it
 
-Once the call is sent into the trunk, the operator may still override the CallerID before routing
-the call to the destination. Each operator has its own rules about CallerID: some will always
-rewrite the CallerID that is attached to the trunk, others will leave the CallerID untouched, some
-operators will only rewrite the CallerID if you use an unauthorized CallerID, etc.
+Once the call is sent into the trunk, the operator may still override the Caller ID before routing
+the call to the destination. Each operator has its own rules about Caller ID: some will always
+rewrite the Caller ID that is attached to the trunk, others will leave the Caller ID untouched, some
+operators will only rewrite the Caller ID if you use an unauthorized Caller ID, etc.
 
-### Anonymous CallerID
+### Anonymous Caller ID
 
 If the user needs to do anonymous calls there are a few things to consider.
 
@@ -56,7 +56,7 @@ be possible to select a caller ID for the extensions.
 If this is not possible the `callerid` field of the `endpoint` section of the trunk can also be
 configured.
 
-Finaly, the PJSIP `endpoint` options `send_pai` and `trust_id_outbound` can be set to `yes`. This
+Finally, the PJSIP `endpoint` options `send_pai` and `trust_id_outbound` can be set to `yes`. This
 will send internal information to the provider for all calls made using that trunk instead of a
 public phone number.
 
@@ -66,39 +66,72 @@ For more information conserning anonymous caller ID see the following links
 - https://www.ietf.org/rfc/rfc3323.txt
 - https://www.ietf.org/rfc/rfc3325.txt
 
-### Dynamic Caller ID Choice {#dynamic-caller-id}
+### Dynamic client-side Caller ID selection {#dynamic-caller-id}
 
-Wazo allows the client SIP user agent to specify a caller ID when a call is launched. This is done
+Wazo allows the client SIP user agent to specify a caller ID when a call is initiated. This is done
 using the `X-Wazo-Selected-Caller-ID` SIP header on the `INVITE` of the call. This method of
-selecting the caller ID has precedence over any other method for choosing a caller ID.
-
-The `X-Wazo-Selected-Caller-ID` header must have the following format where `5555551234` and
-`John Doe` can be replaced with appropriate values:
-
-- `anonymous`
-- `5555551234`
-- `"John Doe" <5555551234>`
-
-The client can use the resource `/api/confd/1.1/users/<uuid>/callerids/outgoing` to find which
-caller ID they can use.
-
-**Note**: The operator will not allow the user to send a caller ID it does not recongnize as valid.
-The number must either be a DID that has been bought from that provider or another number that has
-been verified by the provider.
-
-## CallerID for incoming calls (from a trunk)
+selecting the caller ID has precedence over any other caller id selection method.
+
+The `X-Wazo-Selected-Caller-ID` header must follow the following formats, where `+15555551234` and
+`John Doe` can be replaced with analogous caller id number and caller id name values:
+
+- `anonymous` (a special value for anonymous calls)
+- `+15555551234` (a caller id number with no caller id name)
+- `"John Doe" <+15555551234>` (a caller id with both a name and number)
+
+The client can use the REST API resource
+[`/api/confd/1.1/users/<uuid>/callerids/outgoing`](/documentation/api/configuration.html#tag/users/operation/list_user_callerid_outgoing)
+to list the caller IDs that are available to use.  
+This API relies on caller id information registered in other resources of the Wazo system.  
+Currently, the values provided through this API are based on those resources:
+
+- [`incalls`](/uc-doc/administration/incall) directly routed to the user(using a `User` destination
+  type), yielding caller ids of type `associated`
+- [`phone numbers`](/uc-doc/administration/phone_numbers) with the `shared` or `main` flag, yielding
+  caller ids of type `shared` and `main` respectively
+
+For example:
+
+```json
+{
+  "total": 4,
+  "items": [
+    {
+      "number": "+18001234567",
+      "type": "main"
+    },
+    {
+      "number": "8191110000",
+      "type": "associated"
+    },
+    {
+      "type": "anonymous"
+    }
+  ]
+}
+```
+
+**Note**: Most operators will not allow the user to send a caller ID they do not recongnize as
+valid. The number must either be a DID that has been bought from the same trunk provider the call is
+going through or another number that has been verified by that provider.
+
+Refer to
+[outcalls](/uc-doc/administration/interconnections/wazo_with_voip_provider#voip-provider-outcall)
+documentation for how to control the routing of outgoing calls.
+
+## Caller ID for incoming calls (from a trunk)
 
 There are multiple settings coming into play, in order of priority:
 
-1. SIP trusting remote-party CallerID
+1. SIP trusting remote-party Caller ID
 2. The `caller_id` of endpoint of trunk
-3. CallerID number normalization
+3. Caller ID number normalization
 4. The Incoming Call's `caller_id_mode`
 5. Reverse lookup
 
-### SIP CallerID
+### SIP Caller ID
 
-To accept the CallerID sent via all SIP trunks, modify the `global` SIP template for your tenant
+To accept the Caller ID sent via all SIP trunks, modify the `global` SIP template for your tenant
 
 - `PUT /endpoints/sip/templates/<global_template_uuid>`
 
@@ -114,24 +147,24 @@ To accept the CallerID sent via all SIP trunks, modify the `global` SIP template
 
 This option may also be enabled on specific SIP trunks, instead of globally.
 
-### Trunk CallerID
+### Trunk Caller ID
 
-The endpoint trunk's `caller_id` option overwrites the incoming CallerID. Usually, this options is
-left blank to leave the incoming CallerID untouched.
+The endpoint trunk's `caller_id` option overwrites the incoming Caller ID. Usually, this options is
+left blank to leave the incoming Caller ID untouched.
 
-### CallerID number normalization
+### Caller ID number normalization
 
 See [Incoming caller number display](/uc-doc/installation/postinstall#callerid-num-normalization)
 for details.
 
-### Incoming Call CallerID
+### Incoming Call Caller ID
 
-The Incoming Call's `caller_id_mode` can prepend, append or overwrite the incoming CallerID.
+The Incoming Call's `caller_id_mode` can prepend, append or overwrite the incoming Caller ID.
 
 ### Reverse Lookup
 
-Reverse lookup is the operation of finding the CallerID name from the CallerID number. Wazo can
+Reverse lookup is the operation of finding the Caller ID name from the Caller ID number. Wazo can
 lookup this information in multiple sources.
 
-This operation is only triggered when the incoming CallerID has no CallerID name or when the
-CallerID name equals the CallerID number.
+This operation is only triggered when the incoming Caller ID has no Caller ID name or when the
+Caller ID name equals the Caller ID number.

website/uc-doc/administration/incall.md

@@ -4,11 +4,12 @@ title: Incall
 
 ## General Configuration
 
-You can configure incoming calls with `/incalls` endpoints.
+You can configure incoming calls with the
+[`/incalls`](https://wazo-platform.org/documentation/api/configuration.html#tag/incalls) endpoints.
 
 ### DID (Direct Inward Dialing) Configuration
 
-When a `+` character is prepended a called DID, the `+` character is discarded.
+When a `+` character is prepended to a called DID, the `+` character is discarded.
 
 #### Example:
 

website/uc-doc/administration/interconnections/wazo_with_voip_provider.md

@@ -22,7 +22,12 @@ You need the following information from your provider:
 - a password
 - the name of the provider VoIP server
 - a public phone number
-- `POST /trunks {"context": "ctx-<tenant slug>-incall-<UUID>"}` (or another incoming call context)
+- (optionally) the correct format for caller id on outgoing calls
+
+The following requests allow configuring a SIP trunk:
+
+- [`POST /trunks {"context": "ctx-<tenant slug>-incall-<UUID>", "outgoing_caller_id_format": "+E164"}`](/documentation/api/configuration.html#tag/trunks/operation/create_trunk)
+  (or another incoming call context and supported outgoing caller id format type)
 - `POST /endpoints/sip {"username": <username>, "secret": <password>, "type": "peer", "host": "voip.provider.example.com"}`
 - `PUT /trunks/{trunk_id}/endpoints/sip/{sip_id}`
 - `POST /registers/sip {"auth_username": <username>, "auth_password": <password>, "transport": "udp", "remote_host": "voip.provider.example.com"}`
@@ -41,6 +46,15 @@ value of this cycle period, you have to select the appropriate value of the foll
 At that point, the Asterisk command `sip show registry` should print a line showing that you are
 registered, meaning your trunk is established.
 
+### Trunk outgoing caller id format{#voip-provider-trunk-outgoing-caller-id-format}
+
+Trunks may be configured with a `outgoing_caller_id_format` attribute(see
+[API reference](/documentation/api/configuration.html#tag/trunks/operation/create_trunk)) which
+controls the type of formatting the trunk operator expects for the caller id number value. This
+setting currently applies to the
+[dynamic caller id number](/uc-doc/administration/callerid#dynamic-caller-id) provided by client
+applications through SIP, before the call is connected to the outgoing trunk.
+
 ## Set the outgoing calls {#voip-provider-outcall}
 
 The outgoing calls configuration will allow Wazo to know which extensions will be called through the
@@ -62,6 +76,15 @@ The most useful special characters to match extensions are:
 You can find more details about pattern matching in Asterisk (hence in Wazo) on
 [the Asterisk wiki](https://docs.asterisk.org/Configuration/Dialplan/Pattern-Matching).
 
+### Outgoing caller id{#voip-provider-outcall-outgoing-caller-id}
+
+Outcall extensions may be optionally configured with a `caller_id` attribute(see
+[API reference](/documentation/api/configuration.html#tag/extensions/operation/associate_outcall_extension)),
+which is the caller id that will be used when connecting the calls matched by this outcall extension
+to the outcall's associated trunks.
+
+This caller id is used as is and not subject to the trunk's `outgoing_caller_id_format` setting.
+
 ## Set the incoming calls {#voip-provider-incall}
 
 Now that we have calls going out, we need to route incoming calls.