phone-numbers

電話番号

使用するタイミング

電話番号の検索、購入、管理を行うコードを作成するときに、このスキルを使用します。利用可能な番号の検索、購入、規制要件、送信者の割り当てを扱います。

利用可能な番号を検索する

const result = await zavu.phoneNumbers.searchAvailable({
  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 (paid plans include one US number, once per account)
}

Python：

result = zavu.phone_numbers.search_available(
    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.PhoneNumberSearchAvailableParams{
    CountryCode: "US",
    Type:        zavudev.PhoneNumberTypeLocal,
    Contains:    zavudev.String("555"),
    Limit:       zavudev.Int(10),
})
for _, number := range result.Items {
    fmt.Println(number.PhoneNumber, number.Pricing.MonthlyPrice)
}

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：

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

電話番号を購入する

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

電話番号の購入には有料プランが必要です。 Free プランでは電話番号を購入できません（API はコード paid_plan_required とともに 402 を返します）。有料プランでは、アカウントごとに一度だけ、番号を1つ無料で利用できます。対象は、月額 $20 以下の米国またはカナダの番号（+1 の番号）です。検索結果の pricing.isFreeEligible は、条件を満たす番号を示します。

電話番号の種類

種類	説明
local	都市または地域に紐づく地理的な番号
national	国内全域で有効な非地理的な番号
mobile	携帯電話向けの番号。一部の国では在庫がある唯一の種類であり、一部の市場では SMS を受信できる唯一の種類です
tollFree	フリーダイヤル番号

電話番号を管理する

// 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.retrieve("pn_abc123");

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

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

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

// Release number (must not be assigned to a sender)
await zavu.phoneNumbers.release("pn_abc123");

規制要件

番号に規制情報（住所、書類、またはテキスト）が必要かどうかは、固定の国別リストではなく、番号ごとにキャリアが決定します。購入時には、課金を行う前に対象の番号について要件を照会します。この一連の処理はすべて API 経由で行います。

1. GET /v1/phone-numbers/requirements?phoneNumber=%2B4930123456&type=local（+ は %2B にエンコードしてください。エンコードされていない + も使用できます）。レスポンスは、その番号の購入時に検証される要件のリストです。番号固有の要件を解決できない場合は、その国と type に対応するリストになります。items が空の場合、その番号に必要な情報はありません。そのまま通常どおり購入してください。502 requirements_unavailable が返された場合は照会に失敗しています。再試行し、「要件なし」として扱わないでください（それでも、米国とカナダの番号は要件なしの番号として販売されます）。
2. requirementTypes[] の各項目について、address の場合は同じプロジェクト内で POST /v1/addresses を使って作成し（firstName と lastName は必須です）、その id を使用します。document の場合は、1 件アップロードし（下記参照）、その id を使用します。textual の場合はテキスト自体を使用します。action の場合は何も送信しません。ID ごとに 1 項目を指定します。
3. type（要件を送信する場合は必須）と regulatoryRequirements を指定して購入します。これらのフィールドはまだ SDK に含まれていないため、REST を呼び出してください。

curl -X POST https://api.zavu.dev/v1/phone-numbers \
  -H "Authorization: Bearer $ZAVUDEV_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phoneNumber": "+4930123456",
    "type": "local",
    "regulatoryRequirements": [
      { "requirementType": "<requirementTypes[].id>", "fieldValue": "<address id>" },
      { "requirementType": "<requirementTypes[].id>", "fieldValue": "<document id>" }
    ]
  }'

4. 番号は regulatoryStatus: "pending_review" の状態で、購入と課金が同時に行われます。regulatoryStatus が "approved" になるまで、メッセージの送信や通話の発信はできません。ステータスは 6 時間ごとに再確認されるため、GET /v1/phone-numbers/{phoneNumberId} をポーリングしてください。
5. 承認の前後を問わず、senderId を指定して PATCH /v1/phone-numbers/{phoneNumberId} を呼び出し、番号を送信元に割り当てます。審査中に割り当てた番号は、承認後にその送信元へ接続されるまで再試行されます。API 経由で作成された送信元は、割り当ての一環として SMS 用にセットアップされます。rejected 状態の番号は割り当てできず（400）、長時間 pending_review のままの番号についてはサポートにお問い合わせください。

以下のエラーでは、いずれも課金されません。

レスポンス	意味
400 regulatory_compliance_required	番号に情報が必要ですが、情報が送信されていないか、再利用できる情報がありません。details.missingRequirements に { id, name, type } の一覧が含まれます。
400 invalid_request	必須 ID がない、ID が不明または重複している、住所／書類がこのプロジェクトのものではないか却下された、または審査に登録できなかった場合に返されます。details に要件が示されます。
400 number_unavailable	番号がなくなっているか、送信された type の一覧に含まれていません。
502 requirements_unavailable	要件を照会できませんでした。再試行してください。米国とカナダの番号では返されません。

再利用：送信した情報は、番号の国と type に基づいてプロジェクト用に保持されます。その国で後から購入する際、保持されている情報がその番号のすべての要件を満たし、かつ含まれるすべての住所と書類がプロジェクトに属している場合に限り、regulatoryRequirements を省略できます。それ以外の場合は 400 regulatory_compliance_required が返されます。

// Requirements for a country and type (the SDK has no per-number variant yet;
// the purchase checks the exact number, so prefer the REST call in step 1)
const requirements = await zavu.phoneNumbers.requirements({
  countryCode: "DE",
  type: "local",
});

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

要件の種類

種類	説明
textual	テキストフィールド（氏名、事業者名）
address	物理住所
document	身分証明書類（パスポート、ID など）
action	実行するアクション

規制対応住所の作成

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"

// List and inspect
const addresses = await zavu.addresses.list();
const one = await zavu.addresses.retrieve("addr_abc123");
await zavu.addresses.delete("addr_abc123");

規制関連書類のアップロード

3つの手順で行います。1回限りのアップロードURLを取得し、ファイルのバイト列をそこへPOSTしてから、アップロード時に返されたstorageIdを使って書類レコードを作成します。API自体はファイル形式やサイズを確認しませんが、ダッシュボードのアップローダーで受け付けるのは最大10MBのJPEG、PNG、PDFです。その範囲内に収めてください。レコードの作成時には、同じリクエスト内でファイルが確認のために通信事業者へ転送されます。拒否された場合、呼び出しは400を返し、レコードは保存されません。

作成した住所のステータスはpending、書類のステータスはuploadedで返されます。その後、APIによっていずれかがverifiedまたはrejectedに変更されることはありません。購入にあたって、これらのステータスを確認する必要はありません。承認状況は番号のregulatoryStatusで追跡されるため、代わりにそちらをポーリングしてください。

// 1. Get upload URL (POST /v1/documents/upload-url)
const upload = await zavu.regulatoryDocuments.uploadURL();

// 2. POST the file to the presigned URL; the response carries the storageId
const uploaded = await fetch(upload.uploadUrl, {
  method: "POST",
  body: file, // a Blob or File
  headers: { "Content-Type": file.type },
});
const { storageId } = await uploaded.json();

// 3. Create document record (POST /v1/documents)
const doc = await zavu.regulatoryDocuments.create({
  name: "Passport Scan",
  documentType: "passport",
  storageId,
  mimeType: file.type,
  fileSize: file.size,
});
console.log(doc.document.status); // "uploaded"

// List, inspect, delete (verified documents cannot be deleted)
const docs = await zavu.regulatoryDocuments.list();
const detail = await zavu.regulatoryDocuments.retrieve("doc_xyz789");
await zavu.regulatoryDocuments.delete("doc_xyz789");

書類の種類

種類	説明
passport	パスポート
national_id	国民IDカード
drivers_license	運転免許証
utility_bill	公共料金の請求書
tax_id	納税者番号の書類
business_registration	事業者登録書類
proof_of_address	住所確認書類
other	その他の書類

10DLC（米国のA2Pメッセージング）

米国で大規模なアプリケーション対人（A2P）メッセージングを行う場合、10DLC登録が必要になることがあります。

1. ブランド登録 - 事業者の身元を登録します
2. キャンペーン登録 - メッセージングのユースケースを登録します
3. 番号の割り当て - 登録済みの番号をキャンペーンに割り当てます

登録手数料は、The Campaign Registry独自の料金を残高から差し引き、実費のまま転嫁する形で、次の2種類の料金として請求されます。

料金	1回限り	月額
ブランド（POST /v1/10dlc/brands/{brandId}/submit）	$4	—
キャンペーン、標準的なユースケース（POST /v1/10dlc/campaigns/{campaignId}/submit）	$15	有効期間中は$10
キャンペーン、LOW_VOLUMEユースケース	$2	有効期間中は$2

1回限りの料金は申請時に請求され、通信事業者に登録が拒否された場合、または登録が通信事業者に届かなかった場合に、1回だけ返金されます。月額のキャンペーン料金は上記の公表料金で、キャンペーンの承認初日から請求されます。

ステータスは自動的に更新されます。保留中のキャンペーンは30分ごとに通信事業者から再取得されるため、GET /v1/10dlc/campaigns/{campaignId}をポーリングすれば十分です。電話番号の割り当てステータスはpending、active、またはfailedです（通信事業者に番号が拒否された場合はfailedとなりますが、再度割り当てできます）。削除した割り当ては一覧に表示されなくなります。ブランドのeinは9桁（XX-XXXXXXX）、websiteは完全なURLでなければならず、そうでない場合はリクエストが400で拒否されます。

10DLC登録はZavuダッシュボードから管理します。米国で大量のメッセージングを行う場合の要件については、サポートにお問い合わせください。

制約事項

• 電話番号を購入するには有料プランが必要です（Freeでは402 paid_plan_required）。有料プランにはアカウントごとに1回、電話番号1つが含まれます（Proでは米国の番号です）
• 電話番号の名前は最大100文字です
• 番号を解放する前に、送信者への割り当てを解除する必要があります
• 住所はpending、書類はuploadedとして作成され、そのままの状態が維持されます。これらではなく、番号のregulatoryStatusをポーリングしてください
• 国コードは2文字のISO形式です（例：US、DE、BR）
• 検索結果は1リクエストあたり最大50件です
• 要件のある番号はtypeとregulatoryRequirementsを指定して購入します。regulatoryStatus: "pending_review"で開始し、approvedになるまでは送信も通話もできません。承認後に送信者へ割り当ててください