Lk phone numbers #1146

nishadmusthafa · 2025-07-28T23:38:52Z

No description provided.

changeset-bot · 2025-07-28T23:38:55Z

🦋 Changeset detected

Latest commit: 0007077

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

💥 An error occurred when fetching the changed packages and changesets in this PR

Some errors occurred when validating the changesets config:
The package or glob expression "github.com/livekit/protocol" specified in the `fixed` option does not match any package in the project. You may have misspelled the package name or provided an invalid glob expression. Note that glob expressions must be defined according to https://www.npmjs.com/package/micromatch.

dennwc · 2025-08-14T11:44:02Z

protobufs/livekit_phone_number.proto

+  string area_code = 3;           // Area code (e.g., "415")
+  string locality = 4;            // City/locality (e.g., "San Francisco")
+  string region = 5;              // State/region (e.g., "CA")
+  string capabilities = 6;        // Comma-separated capabilities (e.g., "voice,sms")


Suggested change

string capabilities = 6; // Comma-separated capabilities (e.g., "voice,sms")

repeated string capabilities = 6; // a list of capabilities (e.g., ["voice", "sms"])

dennwc · 2025-08-14T11:44:27Z

protobufs/livekit_phone_number.proto

+  string locality = 4;            // City/locality (e.g., "San Francisco")
+  string region = 5;              // State/region (e.g., "CA")
+  string capabilities = 6;        // Comma-separated capabilities (e.g., "voice,sms")
+  int64 monthly_cost_cents = 7;   // Monthly cost in cents


Do we expect other currencies going forward?

will change

dennwc · 2025-08-14T11:45:20Z

protobufs/livekit_phone_number.proto

+}
+
+// ListPhoneNumberInventoryRequest - Request to list available phone numbers
+message ListPhoneNumberInventoryRequest {


Do we need a filter for capabilities here? And a provider, maybe?

I didn't want to add capability in the request from the get go as we wanted to mostly focus on voice now. SMS certainly is something that should be supported when we support that as a channel.

For provider, my thought was to keep it separate from this request and be able to make config changes like which provider for which country in a different place. Right now, that is more in the cloud. My gut tells me that the implementations will look quite different between cloud and OSS for that.

dennwc · 2025-08-14T11:47:02Z

protobufs/livekit_phone_number.proto

+// ListPhoneNumberInventoryResponse - Response containing available phone numbers
+message ListPhoneNumberInventoryResponse {
+  repeated PhoneNumberInventoryItem items = 1;  // List of available phone numbers
+  int32 total_count = 2;                        // Total number of available numbers


Is it practical to return the total number of all the numbers available for purchase? I assume that's a very long list and some providers may not even return the count.

Good point. I think it might make sense as an optional field in case we receive it.

Decided to leave it out for now.

dennwc · 2025-08-14T11:48:27Z

protobufs/livekit_phone_number.proto

+  repeated PhoneNumberInventoryItem items = 1;  // List of available phone numbers
+  int32 total_count = 2;                        // Total number of available numbers
+  int32 limit = 3;                              // Limit used in the request
+  int32 offset = 4;                             // Offset used in the request


Offset would work for most providers, I guess, but I was thinking maybe a more generic string token or string next would make sense? This way we could still pass the next page number for certain providers and possibly a different kind of pagination token for others.

dennwc · 2025-08-14T11:54:02Z

protobufs/livekit_phone_number.proto

+  string phone_number = 1;        // Phone number in E.164 format (e.g., "+14155552671")
+  string country_code = 2;        // Country code (e.g., "US")
+  string area_code = 3;           // Area code (e.g., "415")
+  string locality = 4;            // City/locality (e.g., "San Francisco")
+  string region = 5;              // State/region (e.g., "CA")


These fields are very similar to ones in PurchasedPhoneNumber, maybe we could make a PhoneNumberInfo with all the common ones? We did this mistake with original SIP in the past by duplicating fields, adding anew new common field becomes very error-prone. So if we put it into a common struct the code can just pass it along without the need for explicit conversion of fields.

I actually had a different thought here. Will make changes.

actually I went with more or less what you suggested. I added some changes to make the pricing data better.

dennwc · 2025-08-14T11:55:30Z

protobufs/livekit_phone_number.proto

+import "google/protobuf/empty.proto";
+
+// Public Phone Number Service - External API for phone number management
+service PhoneNumberService {


If this makes it to OSS, do you think we could adapt it to Twilio API for example?

yeah, I think that's a good idea. Would take a stab at it in a later iteration. Also as I mentioned in the comment below, we might have variations in how that is implemented in cloud/oss for things like what is supported. Billing probably is not something we might support in OSS as it would be something very custom to implementation.

dennwc · 2025-08-14T11:57:18Z

protobufs/livekit_phone_number.proto

+
+// PurchasePhoneNumberRequest - Request to purchase a phone number
+message PurchasePhoneNumberRequest {
+  string phone_number = 1;        // Phone number to purchase (e.g., "+1234567890")


Do you think making it an array makes sense to allow batch orders?

Yeah, I actually gave this some thought. In this iteration, I didn't really look into batching as much. This variation you suggested is one kind of batch implementation. There's also another where you can just give an area code and say you want 10 numbers and you don't care about what the numbers are. But I think definitely makes sense to make this an array.

Only thing to keep in mind here is what would happen if the provider doesn't have a bulk api. We'd need to implement that additional logic. maybe we could validate to only do one in the beginning and add that capability in the future. In the immediate term, this is not an issue as bulk apis exist.

dennwc · 2025-08-14T11:59:09Z

protobufs/livekit_phone_number.proto

+  string country_code = 3;        // Country code (e.g., "US")
+  string area_code = 4;           // Area code (e.g., "415")
+  string national_number = 5;     // National number without country code (e.g., "4155552671")
+  bool is_mobile = 6;             // Whether this is a mobile number


Are there any other kinds? I've seen "toll-free" as a separate category as well, for example. If so, we might need an enum here.

dennwc · 2025-08-14T11:59:51Z

protobufs/livekit_phone_number.proto

+  string area_code = 4;           // Area code (e.g., "415")
+  string national_number = 5;     // National number without country code (e.g., "4155552671")
+  bool is_mobile = 6;             // Whether this is a mobile number
+  string status = 7;              // Current status ("active", "pending", "released")


The number of these states seem fixed, we probably could define most of them upfront as an enum.

…nd pricing for the same

…sage

dennwc · 2025-08-18T07:29:56Z

protobufs/livekit_phone_number.proto

+  string number_type  = 5;        // e.g., local, toll-free, national, mobile
+  string locality = 6;            // City/locality (e.g., "San Francisco")
+  string region = 7;              // State/region (e.g., "CA")
+  int64 spam_score = 8;           // can be used later for fraud detection


Suggested change

int64 spam_score = 8; // can be used later for fraud detection

double spam_score = 8; // can be used later for fraud detection

dennwc · 2025-08-18T07:31:49Z

protobufs/livekit_phone_number.proto

+  int64 created_at = 9;           // timestamp when created
+  int64 updated_at = 10;          // timestamp when updated


Suggested change

int64 created_at = 9; // timestamp when created

int64 updated_at = 10; // timestamp when updated

google.protobuf.Timestamp created_at = 9; // timestamp when created

google.protobuf.Timestamp updated_at = 10; // timestamp when updated

We should use Timestamp type in the new protos, since it's always unclear in which units the int timestamp is.

dennwc · 2025-08-18T07:32:34Z

protobufs/livekit_phone_number.proto

Suggested change

int64 assigned_at = 3; // Timestamp when the number was assigned

int64 released_at = 4; // Timestamp when the number was released (if applicable)

google.protobuf.Timestamp assigned_at = 3; // Timestamp when the number was assigned

google.protobuf.Timestamp released_at = 4; // Timestamp when the number was released (if applicable)

dennwc · 2025-08-18T07:35:00Z

protobufs/livekit_phone_number.proto

-  int32 total_count = 2;                        // Total number of available numbers
-  int32 limit = 3;                              // Limit used in the request
-  int32 offset = 4;                             // Offset used in the request
+  string next_page_token = 2;                   // Token for next page (empty if no more pages)


Maybe we should make a new TokenPagination in the livekit_models.proto, similar to existing Pagination. It will allow us to write a generic pagination code an reuse it for all models.

nishadmusthafa and others added 5 commits August 11, 2025 12:25

Public facing api for livekit phone numbers

c6b3db2

more changes

773d9bd

Adding internal apis

0d58aa7

Adding some more changes to the proto

ec1d8be

generated protobuf

dc846fd

nishadmusthafa force-pushed the lk-phone-numbers branch from 7b9b4ca to dc846fd Compare August 11, 2025 19:26

github-actions bot and others added 3 commits August 11, 2025 19:27

generated protobuf

bc68db3

Updating to remove internal apis

1d59a15

Adding changeset

479e6a5

nishadmusthafa requested a review from a team August 13, 2025 17:52

nishadmusthafa marked this pull request as ready for review August 13, 2025 17:52

dennwc reviewed Aug 14, 2025

View reviewed changes

nishadmusthafa and others added 6 commits August 15, 2025 16:05

Clean up and changes around common fields for Phone number messages a…

b30b095

…nd pricing for the same

generated protobuf

2a22379

Using a more generic costing model based on resources

4b79d2b

generated protobuf

96712b9

Adding a reference to SipDispatchRule in the PurchasedPhoneNumber mes…

f2388a2

…sage

generated protobuf

21a009e

dennwc reviewed Aug 18, 2025

View reviewed changes

nishadmusthafa and others added 2 commits August 18, 2025 11:15

Using google protobuf timestamp and adding a struct for TokenPagination

cb716e9

generated protobuf

0007077

	string capabilities = 6; // Comma-separated capabilities (e.g., "voice,sms")
	repeated string capabilities = 6; // a list of capabilities (e.g., ["voice", "sms"])

	int64 spam_score = 8; // can be used later for fraud detection
	double spam_score = 8; // can be used later for fraud detection

		int64 created_at = 9; // timestamp when created
		int64 updated_at = 10; // timestamp when updated

-  int64 assigned_at = 3;               // Timestamp when the number was assigned
-  int64 released_at = 4;               // Timestamp when the number was released (if applicable)
+  google.protobuf.Timestamp assigned_at = 3;               // Timestamp when the number was assigned
+  google.protobuf.Timestamp released_at = 4;               // Timestamp when the number was released (if applicable)

Lk phone numbers #1146

Are you sure you want to change the base?

Lk phone numbers #1146

Conversation

nishadmusthafa commented Jul 28, 2025

Uh oh!

changeset-bot bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

changeset-bot bot commented Jul 28, 2025 •

edited

Loading