API "SIP dial-out"

[nickvergessen]

• Overview at ☎️ SIP dial-out #10346

---

• feat(phonenumber): Add OCP wrapper for PhoneNumber utils library server#40620

[fancycode]

1. Request to send from Talk to backend endpoint of Signaling Server:

• Request

{
  "type": "dialout",
  "dialout": {
    "number": "the-e164-number",
    "options": {
      "actorId": "the-actor-id",
      "actorType": "the-actor-type",
      ...optional additional properties...
    }
  }
}

• Answer will either be success:

{
  "type": "dialout",
  "dialout": {
    "callid": "the-call-id"
  }
}

• Or an error:

{
  "type": "dialout",
  "dialout": {
    "error": {
      "code": "error-code",
      "message": "Human readable error.",
      "details": {
        ...optional-details-object...
      }
    }
  }
}

[fancycode]

2. API required in Talk to be called by SIP bridge workflow

• Receives the room token, number and options from dialout request from above.
• Verifies that the dial-out is actually allowed (a safe-guard as the dial-out is triggered by a different service than what receives the dial-out request initially).
• Should return the same structure as the existing API to check participant PINs from the SIP bridge.

  spreed/docs/participant.md

  Line 254 in c67c782

  ## Get a participant by their pin

[fancycode]

3. Events sent to all sessions in a room for outgoing call status changes

Will use transient data to store the state of outgoing calls. This is so sessions that are joining later will receive the current state of calls automatically.

The key is callstatus_<the-call-id>, the value details on the status:

Dial-out request was accepted for processing:

{"callid":"the-call-id","status":"accepted"}

Outgoing call is rejected by the SIP provider:

{"callid":"the-call-id","status":"rejected","cause":"EndedByTemporarilyUnavailable","code":480,"message":"Temporarily Unavailable (Call limit)"}

Outgoing call is ringing:

{"callid":"the-call-id","status":"ringing"}

Outgoing call is connected:

{"callid":"the-call-id","status":"connected"}

Outgoing call is cleared:

{"callid":"the-call-id","status":"cleared","cause":"EndedByRemote"}

Status entries for cleared and rejected are only present for a short time (a few seconds) so clients can update their UI and will be removed afterwards.

[fancycode]

4. Existing API to notify joining / leaving

• The calls will use the existing API to join / leave the room:
  

  spreed/lib/Controller/SignalingController.php

  Line 584 in c67c782

  private function backendRoom(array $roomRequest): DataResponse {

[fancycode]

Draft PR for signaling server available at strukturag/nextcloud-spreed-signaling#563

[nickvergessen]

• The same number might have to be called multiple times (call centers, etc) so might not be able to use that as actor-id

[nickvergessen]

• The number format should be E164

 * INTERNATIONAL and NATIONAL formats are consistent with the definition in ITU-T Recommendation
 * E123. For example, the number of the Google Switzerland office will be written as
 * "+41 44 668 1800" in INTERNATIONAL format, and as "044 668 1800" in NATIONAL format.
 * E164 format is as per INTERNATIONAL format but with no formatting applied, e.g.
 * "+41446681800". RFC3966 is as per INTERNATIONAL format, but with all spaces and other
 * separating symbols replaced with a hyphen, and with any phone number extension appended with
 * ";ext=". It also will have a prefix of "tel:" added, e.g. "tel:+41-44-668-1800".

[nickvergessen]

@fancycode for the database structure:

• callId is a string as I read in the Golang code, any max length known? 64? 255?

---

Events sent to all sessions in a room for outgoing call status changes

• The above is not sent to the server, so a potential later joining user would not know the state of the SIP contact? Doesn't look like it would change frequently, so we could store it in the nextcloud server?

---

• When a user types more numbers on a callId (to proceed in a call center), does the users frontend send this info directly to SIP/HPB or to the nextcloud server and the server then tells the HPB/SIP to type number X on callId Y?

[nickvergessen]

Tech details

• Callid 255 chars can be wiped after call
• callid status will be saved as transient data and so be available for people that join later, storing on the server is not necessary at the moment
• SIP bridge will send a DELETE when the call was denied by the SIP gateway or hangup
• DTMF (numbers dialed later) are sent directly to the HPB (+ callId)

[fancycode]

See #10410 (comment) for details on the call status with transient data.

[fancycode]

Possible SIP status codes are available e.g. from here:
https://en.wikipedia.org/wiki/List_of_SIP_response_codes

[fancycode]

5. Send events to established calls (both incoming and outgoing)

As DTMF and hangup also apply to incoming phone calls, I defined a generic way to send these:
strukturag/nextcloud-spreed-signaling@d4763f8

Basically you have to get the session id of phone calls from the joined event (you can match this through the call id) and then send a control message to these sessions to hangup or send DTMF (or to mute them).