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 }