phone-numbers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Phone Numbers

电话号码

When to Use

使用场景

Use this skill when building code to search for, purchase, or manage phone numbers. Covers available number search, purchasing, regulatory requirements, and sender assignment.

当你需要编写代码来搜索、购买或管理电话号码时，可以使用此Skill。涵盖可用号码搜索、购买、合规要求以及发送方分配等功能。

Search Available Numbers

搜索可用号码

typescript

const result = await zavu.phoneNumbers.available.list({
  countryCode: "US",
  type: "local",
  contains: "555",
  limit: 10,
});

for (const number of result.items) {
  console.log(number.phoneNumber);       // +15551234567
  console.log(number.friendlyName);      // (555) 123-4567
  console.log(number.locality);          // San Francisco
  console.log(number.capabilities);      // { sms: true, voice: true, mms: true }
  console.log(number.pricing.monthlyPrice); // 1.25
  console.log(number.pricing.isFreeEligible); // true (first US number is free)
}

Python:

python

result = zavu.phone_numbers.available.list(
    country_code="US",
    type="local",
    contains="555",
    limit=10,
)
for number in result.items:
    print(number.phone_number, number.pricing.monthly_price)

Go:

result, err := client.PhoneNumbers.SearchAvailable(context.TODO(), zavudev.PhoneNumberSearchParams{
    CountryCode: zavudev.String("US"),
    Type:        zavudev.String("local"),
    Contains:    zavudev.String("555"),
    Limit:       zavudev.Int(10),
})
for _, number := range result.Items {
    fmt.Println(number.PhoneNumber, number.Pricing.MonthlyPrice)
}

Ruby:

ruby

result = client.phone_numbers.search_available(country_code: "US", type: "local", contains: "555", limit: 10)
result.items.each { |number| puts "#{number.phone_number} #{number.pricing.monthly_price}" }

PHP:

php

$result = $client->phoneNumbers->searchAvailable([
    'countryCode' => 'US', 'type' => 'local', 'contains' => '555', 'limit' => 10,
]);
foreach ($result->items as $number) {
    echo $number->phoneNumber . ' ' . $number->pricing->monthlyPrice . "\n";
}

typescript

const result = await zavu.phoneNumbers.available.list({
  countryCode: "US",
  type: "local",
  contains: "555",
  limit: 10,
});

for (const number of result.items) {
  console.log(number.phoneNumber);       // +15551234567
  console.log(number.friendlyName);      // (555) 123-4567
  console.log(number.locality);          // San Francisco
  console.log(number.capabilities);      // { sms: true, voice: true, mms: true }
  console.log(number.pricing.monthlyPrice); // 1.25
  console.log(number.pricing.isFreeEligible); // true (first US number is free)
}

Python:

python

result = zavu.phone_numbers.available.list(
    country_code="US",
    type="local",
    contains="555",
    limit=10,
)
for number in result.items:
    print(number.phone_number, number.pricing.monthly_price)

Go:

result, err := client.PhoneNumbers.SearchAvailable(context.TODO(), zavudev.PhoneNumberSearchParams{
    CountryCode: zavudev.String("US"),
    Type:        zavudev.String("local"),
    Contains:    zavudev.String("555"),
    Limit:       zavudev.Int(10),
})
for _, number := range result.Items {
    fmt.Println(number.PhoneNumber, number.Pricing.MonthlyPrice)
}

Ruby:

ruby

result = client.phone_numbers.search_available(country_code: "US", type: "local", contains: "555", limit: 10)
result.items.each { |number| puts "#{number.phone_number} #{number.pricing.monthly_price}" }

PHP:

php

$result = $client->phoneNumbers->searchAvailable([
    'countryCode' => 'US', 'type' => 'local', 'contains' => '555', 'limit' => 10,
]);
foreach ($result->items as $number) {
    echo $number->phoneNumber . ' ' . $number->pricing->monthlyPrice . "\n";
}

Purchase Phone Number

购买电话号码

typescript

const result = await zavu.phoneNumbers.create({
  phoneNumber: "+15551234567",
  name: "Primary Line",
});
console.log(result.phoneNumber.id);     // pn_abc123
console.log(result.phoneNumber.status); // "active"

First US number is free for each team.

typescript

const result = await zavu.phoneNumbers.create({
  phoneNumber: "+15551234567",
  name: "Primary Line",
});
console.log(result.phoneNumber.id);     // pn_abc123
console.log(result.phoneNumber.status); // "active"

每个团队的首个美国号码免费

Phone Number Types

电话号码类型

Type	Description
`local`	Local phone number
`mobile`	Mobile number
`tollFree`	Toll-free number

Type	描述
`local`	本地电话号码
`mobile`	手机号码
`tollFree`	免费电话号码

Manage Phone Numbers

管理电话号码

typescript

// List owned numbers
const numbers = await zavu.phoneNumbers.list({ status: "active" });
for (const pn of numbers.items) {
  console.log(pn.id, pn.phoneNumber, pn.status);
}

// Get details
const pn = await zavu.phoneNumbers.get({ phoneNumberId: "pn_abc123" });

// Rename
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  name: "Support Line",
});

// Assign to sender
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  senderId: "snd_abc123",
});

// Unassign from sender
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  senderId: null,
});

// Release number (must not be assigned to a sender)
await zavu.phoneNumbers.delete({ phoneNumberId: "pn_abc123" });

typescript

// List owned numbers
const numbers = await zavu.phoneNumbers.list({ status: "active" });
for (const pn of numbers.items) {
  console.log(pn.id, pn.phoneNumber, pn.status);
}

// Get details
const pn = await zavu.phoneNumbers.get({ phoneNumberId: "pn_abc123" });

// Rename
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  name: "Support Line",
});

// Assign to sender
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  senderId: "snd_abc123",
});

// Unassign from sender
await zavu.phoneNumbers.update({
  phoneNumberId: "pn_abc123",
  senderId: null,
});

// Release number (must not be assigned to a sender)
await zavu.phoneNumbers.delete({ phoneNumberId: "pn_abc123" });

Regulatory Requirements

合规要求

Some countries require additional documentation before phone numbers can be activated:

typescript

// Check requirements for a country
const requirements = await zavu.phoneNumbers.requirements.list({
  countryCode: "DE",
  type: "local",
});

for (const req of requirements.items) {
  console.log(req.countryCode, req.phoneNumberType, req.action);
  for (const rt of req.requirementTypes) {
    console.log(`  ${rt.name}: ${rt.type} - ${rt.description}`);
  }
}

部分国家在激活电话号码前需要额外的文件：

typescript

// Check requirements for a country
const requirements = await zavu.phoneNumbers.requirements.list({
  countryCode: "DE",
  type: "local",
});

for (const req of requirements.items) {
  console.log(req.countryCode, req.phoneNumberType, req.action);
  for (const rt of req.requirementTypes) {
    console.log(`  ${rt.name}: ${rt.type} - ${rt.description}`);
  }
}

Requirement Types

要求类型

Type	Description
`textual`	Text field (name, business name)
`address`	Physical address
`document`	Identity document (passport, ID, etc.)
`action`	Action to perform

Type	描述
`textual`	文本字段（姓名、企业名称）
`address`	实际地址
`document`	身份证明文件（护照、身份证等）
`action`	需要执行的操作

Create Regulatory Address

创建合规地址

typescript

const address = await zavu.addresses.create({
  firstName: "John",
  lastName: "Doe",
  streetAddress: "123 Main St",
  locality: "Berlin",
  postalCode: "10115",
  countryCode: "DE",
});
console.log(address.address.status); // "pending" -> "verified"

typescript

const address = await zavu.addresses.create({
  firstName: "John",
  lastName: "Doe",
  streetAddress: "123 Main St",
  locality: "Berlin",
  postalCode: "10115",
  countryCode: "DE",
});
console.log(address.address.status); // "pending" -> "verified"

Upload Regulatory Document

上传合规文件

typescript

// 1. Get upload URL
const upload = await zavu.documents.uploadUrl();

// 2. Upload file to the presigned URL (use fetch/axios)
await fetch(upload.uploadUrl, {
  method: "PUT",
  body: fileBuffer,
  headers: { "Content-Type": "image/jpeg" },
});

// 3. Create document record
const doc = await zavu.documents.create({
  name: "Passport Scan",
  documentType: "passport",
  storageId: "kg2abc123...",
  mimeType: "image/jpeg",
  fileSize: 102400,
});
console.log(doc.document.status); // "pending" -> "verified"

typescript

// 1. Get upload URL
const upload = await zavu.documents.uploadUrl();

// 2. Upload file to the presigned URL (use fetch/axios)
await fetch(upload.uploadUrl, {
  method: "PUT",
  body: fileBuffer,
  headers: { "Content-Type": "image/jpeg" },
});

// 3. Create document record
const doc = await zavu.documents.create({
  name: "Passport Scan",
  documentType: "passport",
  storageId: "kg2abc123...",
  mimeType: "image/jpeg",
  fileSize: 102400,
});
console.log(doc.document.status); // "pending" -> "verified"

Document Types

文件类型

Type	Description
`passport`	Passport
`national_id`	National ID card
`drivers_license`	Driver's license
`utility_bill`	Utility bill
`tax_id`	Tax ID document
`business_registration`	Business registration
`proof_of_address`	Proof of address
`other`	Other document

Type	描述
`passport`	护照
`national_id`	国民身份证
`drivers_license`	驾照
`utility_bill`	水电费账单
`tax_id`	税务身份证明文件
`business_registration`	企业注册文件
`proof_of_address`	地址证明
`other`	其他文件

10DLC (US A2P Messaging)

10DLC（美国A2P消息服务）

For US application-to-person messaging at scale, you may need 10DLC registration:

Brand Registration - Register your business identity
Campaign Registration - Register your messaging use case
Number Assignment - Assign registered numbers to campaigns

10DLC registration is managed through the Zavu dashboard. Contact support for high-volume US messaging requirements.

对于美国大规模的应用到个人（A2P）消息服务，你可能需要进行10DLC注册：

品牌注册 - 注册你的企业身份
活动注册 - 注册你的消息使用场景
号码分配 - 将已注册号码分配给活动

10DLC注册通过Zavu控制台进行管理。如需处理高容量美国消息服务需求，请联系支持团队。

Constraints

限制条件

First US phone number is free per team
Phone number name: max 100 characters
Phone numbers must be unassigned from senders before release
Regulatory addresses and documents go through verification (pending -> verified/rejected)
Country code: 2-letter ISO format (e.g.,
```
US
```
,
```
DE
```
,
```
BR
```
)
Search results: max 50 per request
Some countries require verified address + document before number activation

每个团队的首个美国电话号码免费
电话号码名称：最多100个字符
释放号码前必须先解除与发送方的关联
合规地址和文件需要经过审核（待审核 -> 已审核/被拒绝）
国家代码：2位ISO格式（例如：
```
US
```
、
```
DE
```
、
```
BR
```
）
搜索结果：每次请求最多50条
部分国家在激活号码前需要已验证的地址和文件