github.com/livekit/protocol@v1.16.1-0.20240517185851-47e4c6bba773/protobufs/livekit_sip.proto (about)

     1  // Copyright 2023 LiveKit, Inc.
     2  //
     3  // Licensed under the Apache License, Version 2.0 (the "License");
     4  // you may not use this file except in compliance with the License.
     5  // You may obtain a copy of the License at
     6  //
     7  //     http://www.apache.org/licenses/LICENSE-2.0
     8  //
     9  // Unless required by applicable law or agreed to in writing, software
    10  // distributed under the License is distributed on an "AS IS" BASIS,
    11  // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    12  // See the License for the specific language governing permissions and
    13  // limitations under the License.
    14  
    15  syntax = "proto3";
    16  
    17  package livekit;
    18  
    19  option go_package = "github.com/livekit/protocol/livekit";
    20  option csharp_namespace = "LiveKit.Proto";
    21  option ruby_package = "LiveKit::Proto";
    22  
    23  /*
    24     LiveKit's SIP API is built with 3 high level primitives
    25     - SIP Trunk
    26     - SIP Dispatch Rule
    27     - SIP Participant
    28  
    29  
    30     The `SIP Trunk` is used to accept and make calls. A `SIP Trunk` is configured with
    31     the IPs/Ports and Authentication details of your SIP Provider. When a call is accepted from
    32     the `SIP Trunk` it is then handled by the `SIP Dispatch Rules`. When a `SIP Participant` is created
    33     for a outbound call a `SIP Trunk` is chosen to make the call with.
    34  
    35  
    36     The `SIP Dispatch Rule` is a list of rules that dictate how a incoming SIP call should be handled.
    37     LiveKit currently supports 2 types, but may support more in the future.
    38  
    39     - `Direct Dispatch` puts a caller into a existing room, possibly choosing between multiple rooms with a pin
    40     - `Individual Dispatch` puts a caller into a new room created for the call
    41  
    42  
    43     The `SIP Participant` represents an active SIP Session. These SIP Sessions are always associated with
    44     a Participant on LiveKit side. Inbound calls create Participants directly (with a `SIP` kind), while outbound
    45     calls must be initiated with `CreateSIPParticipant`.
    46  */
    47  
    48  
    49  service SIP {
    50    rpc CreateSIPTrunk(CreateSIPTrunkRequest) returns (SIPTrunkInfo);
    51    rpc ListSIPTrunk(ListSIPTrunkRequest) returns (ListSIPTrunkResponse);
    52    rpc DeleteSIPTrunk(DeleteSIPTrunkRequest) returns (SIPTrunkInfo);
    53  
    54    rpc CreateSIPDispatchRule(CreateSIPDispatchRuleRequest) returns (SIPDispatchRuleInfo);
    55    rpc ListSIPDispatchRule(ListSIPDispatchRuleRequest) returns (ListSIPDispatchRuleResponse);
    56    rpc DeleteSIPDispatchRule(DeleteSIPDispatchRuleRequest) returns (SIPDispatchRuleInfo);
    57  
    58    rpc CreateSIPParticipant(CreateSIPParticipantRequest) returns (SIPParticipantInfo);
    59  }
    60  
    61  
    62  message CreateSIPTrunkRequest {
    63    // CIDR or IPs that traffic is accepted from
    64    // An empty list means all inbound traffic is accepted.
    65    repeated string inbound_addresses = 1;
    66  
    67    // IP that SIP INVITE is sent too
    68    string outbound_address = 2;
    69  
    70    // Number used to make outbound calls
    71    string outbound_number = 3;
    72  
    73    repeated string inbound_numbers_regex = 4 [deprecated=true];
    74  
    75    // Accepted `To` values. This Trunk will only accept a call made to
    76    // these numbers. This allows you to have distinct Trunks for different phone
    77    // numbers at the same provider.
    78    repeated string inbound_numbers = 9;
    79  
    80    // Username and password used to authenticate inbound and outbound SIP invites
    81    // May be empty to have no Authentication
    82    string inbound_username = 5;
    83    string inbound_password = 6;
    84    string outbound_username = 7;
    85    string outbound_password = 8;
    86  
    87    // Optional human-readable name for the Trunk.
    88    string name = 10;
    89    // Optional user-defined metadata for the Trunk.
    90    string metadata = 11;
    91  }
    92  
    93  message SIPTrunkInfo {
    94    string sip_trunk_id = 1;
    95  
    96    // CIDR or IPs that traffic is accepted from
    97    // An empty list means all inbound traffic is accepted.
    98    repeated string inbound_addresses = 2;
    99  
   100    // IP that SIP INVITE is sent too
   101    string outbound_address = 3;
   102  
   103    // Number used to make outbound calls
   104    string outbound_number = 4;
   105  
   106    repeated string inbound_numbers_regex = 5 [deprecated=true];
   107  
   108    // Accepted `To` values. This Trunk will only accept a call made to
   109    // these numbers. This allows you to have distinct Trunks for different phone
   110    // numbers at the same provider.
   111    repeated string inbound_numbers = 10;
   112  
   113    // Username and password used to authenticate inbound and outbound SIP invites
   114    // May be empty to have no Authentication
   115    string inbound_username = 6;
   116    string inbound_password = 7;
   117    string outbound_username = 8;
   118    string outbound_password = 9;
   119  
   120    // Human-readable name for the Trunk.
   121    string name = 11;
   122    // User-defined metadata for the Trunk.
   123    string metadata = 12;
   124  }
   125  
   126  message ListSIPTrunkRequest {
   127  }
   128  
   129  message ListSIPTrunkResponse {
   130    repeated SIPTrunkInfo items = 1;
   131  }
   132  
   133  message DeleteSIPTrunkRequest {
   134    string sip_trunk_id = 1;
   135  }
   136  
   137  message SIPDispatchRuleDirect {
   138    // What room should call be directed into
   139    string room_name = 1;
   140  
   141    // Optional pin required to enter room
   142    string pin = 2;
   143  }
   144  
   145  message SIPDispatchRuleIndividual {
   146    // Prefix used on new room name
   147    string room_prefix = 1;
   148  
   149    // Optional pin required to enter room
   150    string pin = 2;
   151  }
   152  
   153  message SIPDispatchRule {
   154    oneof rule {
   155      // SIPDispatchRuleDirect is a `SIP Dispatch Rule` that puts a user directly into a room
   156      // This places users into an existing room. Optionally you can require a pin before a user can
   157      // enter the room
   158      SIPDispatchRuleDirect dispatch_rule_direct = 1;
   159  
   160      // SIPDispatchRuleIndividual is a `SIP Dispatch Rule` that creates a new room for each caller.
   161      SIPDispatchRuleIndividual dispatch_rule_individual = 2;
   162    }
   163  }
   164  
   165  message CreateSIPDispatchRuleRequest {
   166    SIPDispatchRule rule = 1;
   167  
   168    // What trunks are accepted for this dispatch rule
   169    // If empty all trunks will match this dispatch rule
   170    repeated string trunk_ids = 2;
   171  
   172    // By default the From value (Phone number) is used as the participant identity
   173    // If true a random value will be used instead
   174    bool hide_phone_number = 3;
   175  
   176    // Dispatch Rule will only accept a call made to these numbers (if set).
   177    repeated string inbound_numbers = 6;
   178  
   179    // Optional human-readable name for the Dispatch Rule.
   180    string name = 4;
   181    // Optional user-defined metadata for the Dispatch Rule.
   182    string metadata = 5;
   183  
   184    // NEXT ID: 7
   185  }
   186  
   187  message SIPDispatchRuleInfo {
   188    string sip_dispatch_rule_id = 1;
   189    SIPDispatchRule rule = 2;
   190    repeated string trunk_ids = 3;
   191    bool hide_phone_number = 4;
   192    // Dispatch Rule will only accept a call made to these numbers (if set).
   193    repeated string inbound_numbers = 7;
   194  
   195    // Human-readable name for the Dispatch Rule.
   196    string name = 5;
   197    // User-defined metadata for the Dispatch Rule.
   198    // Participants created by this rule will inherit this metadata.
   199    string metadata = 6;
   200  
   201    // NEXT ID: 8
   202  }
   203  
   204  message ListSIPDispatchRuleRequest {
   205  }
   206  
   207  message ListSIPDispatchRuleResponse {
   208    repeated SIPDispatchRuleInfo items = 1;
   209  }
   210  
   211  message DeleteSIPDispatchRuleRequest {
   212    string sip_dispatch_rule_id = 1;
   213  }
   214  
   215  // A SIP Participant is a singular SIP session connected to a LiveKit room via
   216  // a SIP Trunk into a SIP DispatchRule
   217  message CreateSIPParticipantRequest {
   218    // What SIP Trunk should be used to dial the user
   219    string sip_trunk_id = 1;
   220  
   221    // What number should be dialed via SIP
   222    string sip_call_to = 2;
   223  
   224    // What LiveKit room should this participant be connected too
   225    string room_name = 3;
   226  
   227    // Optional identity of the participant in LiveKit room
   228    string participant_identity = 4;
   229  
   230    // Optional name of the participant in LiveKit room
   231    string participant_name = 7;
   232  
   233    // Optional user-defined metadata. Will be attached to a created Participant in the room.
   234    string participant_metadata = 8;
   235  
   236    // Optionally send following DTMF digits (extension codes) when making a call.
   237    // Character 'w' can be used to add a 0.5 sec delay.
   238    string dtmf = 5;
   239  
   240    // Optionally play ringtone in the room as an audible indicator for existing participants
   241    bool play_ringtone = 6;
   242  
   243    // NEXT ID: 9
   244  }
   245  
   246  message SIPParticipantInfo {
   247    string participant_id = 1;
   248    string participant_identity = 2;
   249    string room_name = 3;
   250    string sip_call_id = 4;
   251  }