Mua số điện thoại và đăng ký nhắn tin qua API

API có thể tìm kiếm các số điện thoại có thể mua, mua chúng và đăng ký doanh nghiệp của bạn để nhắn tin 10DLC — với cùng cách tính phí, yêu cầu và kết quả như khi thực hiện trong ứng dụng. Một số điện thoại được mua qua POST /v1/api/numbers sẽ xuất hiện ngay lập tức trong Cài đặt → Số điện thoại, và một đăng ký được gửi qua API sẽ hiển thị trong thẻ Thiết lập nhắn tin, để bạn có thể can thiệp và quản lý bất kỳ lúc nào từ ứng dụng.

Trước khi bắt đầu

• Khóa API của bạn cần có phạm vi numbers:manage — chip Mua số điện thoại & 10DLC trong Cài đặt → API nhà phát triển. Các khóa truy cập đầy đủ sẽ tự động bao gồm nó. Xem Lấy khóa API Ody của bạn.
• Các quy tắc tương tự như ứng dụng được áp dụng: không gian làm việc của bạn cần có gói hoạt động để mua, và nếu Ody đã yêu cầu bạn xác minh danh tính, điều đó phải được hoàn thành trước — API sẽ trả về 409 failed_precondition cho đến khi hoàn tất.
• Cách tính phí giống hệt trong ứng dụng: gói của bạn bao gồm một số, và mỗi số phụ trội sẽ được tính phí như tiện ích bổ sung số điện thoại với giá 5$/tháng. Xem Thêm số điện thoại bổ sung.

Tìm kiếm số điện thoại có sẵn

GET /v1/api/numbers/available tìm kiếm các số điện thoại bạn có thể mua. Lọc bằng country (mặc định US), startsWith (ví dụ: mã vùng), contains, locality, state, và limit (mặc định 20, tối đa 50):

curl "https://api.ody.co/v1/api/numbers/available?startsWith=512&limit=5" \
  -H "Authorization: Bearer ody_live_…"

Mỗi ứng viên bao gồm số điện thoại của nó và giá hàng tháng bạn thực sự phải trả cho Ody:

{
  "available": [
    {
      "phone_number": "+15125550123",
      "cost_information": { "monthly_cost": "5.00", "upfront_cost": "0.00", "currency": "USD" }
    }
  ]
}

Mua số điện thoại

POST /v1/api/numbers đặt mua một số điện thoại từ kết quả tìm kiếm. Gửi tiêu đề Idempotency-Key để việc thử lại mạng không bao giờ mua số điện thoại hai lần — một lần thử lại trong vòng 24 giờ sẽ phát lại phản hồi gốc với tiêu đề Idempotency-Replayed: true:

curl https://api.ody.co/v1/api/numbers \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboarding-main-line" \
  -d '{"phoneNumber":"+15125550123"}'

Số điện thoại được đặt mua, thêm vào không gian làm việc của bạn và tính phí trên gói đăng ký hiện có của bạn — chính xác như khi nhấp vào Mua trong ứng dụng. Nó xuất hiện ngay lập tức trong Cài đặt → Số điện thoại, nơi bạn (hoặc nhóm của bạn) có thể cấu hình thứ tự đổ chuông, thư thoại, menu điện thoại hoặc tác nhân AI, giống như bất kỳ số điện thoại nào khác. Cuộc gọi hoạt động ngay lập tức; nhắn tin từ một số địa phương bị giới hạn cho đến khi đăng ký 10DLC được phê duyệt (bên dưới).

Đăng ký nhắn tin (10DLC)

Các nhà mạng US yêu cầu đăng ký doanh nghiệp trước khi một số điện thoại địa phương có thể gửi tin nhắn — API phản ánh quy trình Thiết lập nhắn tin trong ứng dụng.

Kiểm tra trạng thái với GET /v1/api/messaging. step trong phản hồi sẽ dẫn qua quá trình xem xét doanh nghiệp (thương hiệu) và sau đó là xem xét chiến dịch, và canText sẽ chuyển thành true ngay khi các nhà mạng phê duyệt — nhắn tin sau đó sẽ hoạt động ở mọi nơi, cả ứng dụng và API.

Gửi đăng ký của bạn với POST /v1/api/messaging/registration. Khối business yêu cầu displayName, email, vertical, street, city, state, và postalCode — cộng với companyName và EIN hợp pháp của bạn, trừ khi bạn đăng ký với tư cách là chủ doanh nghiệp tư nhân (entityType: "SOLE_PROPRIETOR" với firstName, lastName, và một số điện thoại liên hệ thay thế). Khối campaign là tùy chọn; các giá trị mặc định hợp lý (một trường hợp sử dụng Hỗn hợp với xử lý STOP/HELP tuân thủ) sẽ được áp dụng:

curl https://api.ody.co/v1/api/messaging/registration \
  -H "Authorization: Bearer ody_live_…" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: acme-plumbing-10dlc" \
  -d '{
    "business": {
      "displayName": "Acme Plumbing",
      "email": "[email protected]",
      "vertical": "PROFESSIONAL",
      "companyName": "Acme Plumbing LLC",
      "ein": "12-3456789",
      "street": "600 Congress Ave",
      "city": "Austin",
      "state": "TX",
      "postalCode": "78701"
    },
    "campaign": {
      "description": "Customer care and appointment notifications",
      "samples": ["Acme Plumbing: your appointment is confirmed for Tuesday at 9am."]
    }
  }'

Một hồ sơ được gửi qua API sẽ được tính phí chính xác như một hồ sơ trong ứng dụng, bao gồm phí đăng ký một lần 20$. Sử dụng POST /v1/api/messaging/refresh để kiểm tra lại quá trình xem xét của nhà mạng và đẩy nhanh quy trình; việc phê duyệt cũng tự động tiến triển.

Từ trợ lý AI (MCP)

Các khả năng tương tự có sẵn dưới dạng công cụ MCP, vì vậy một trợ lý được kết nối có thể chạy toàn bộ quy trình này cho bạn: search_numbers, buy_number, get_messaging_status, và submit_10dlc_registration. Xem Kết nối công cụ AI với MCP.

Chế độ thử nghiệm

Với khóa ody_test_…, POST /numbers sẽ trả về một giao dịch mua mô phỏng ("simulated": true) — không có gì được đặt hàng, cung cấp hoặc tính phí — và các đăng ký 10DLC sẽ được gửi ở chế độ mô phỏng: toàn bộ quy trình sẽ chạy mà không cần gửi đăng ký và không mất phí. Xem Xây dựng an toàn với chế độ thử nghiệm.

Các bài viết liên quan

• Mua số điện thoại
• Đăng ký nhắn tin 10DLC
• Thực hiện cuộc gọi AI và quản lý Astra qua API
• Xây dựng an toàn với chế độ thử nghiệm