Gán một số cho chiến dịch nhắn tin

Gán số gửi cho một chiến dịch

Sử dụng thao tác này sau khi thương hiệu nhắn tin và chiến dịch sản xuất của bạn đã được đăng ký và chiến dịch đang hoạt động. Thao tác này liên kết một số có hỗ trợ SMS trên tài khoản của bạn với chiến dịch. Thao tác này không tạo thương hiệu, không tạo hay phê duyệt chiến dịch, không mua số và không gửi tin nhắn.

Cổng thông tin hiện tại sử dụng tuyến này khi gán một chiến dịch cho một số. API công khai chấp nhận một mã định danh chiến dịch; API suy ra thương hiệu từ chiến dịch thuộc sở hữu của tài khoản thay vì chấp nhận một mã định danh thương hiệu riêng.

Yêu cầu

Gửi một yêu cầu POST mã hóa dạng biểu mẫu qua HTTPS bằng tài khoản API đã được bật và địa chỉ IP nguồn được phép của tài khoản đó. Sử dụng số và mã định danh chiến dịch thực tế từ tài khoản của bạn. Số trong ví dụ này là hư cấu.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=add' \
  --data-urlencode "campaign=$CAMPAIGN_ID" \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Tham số gán chiến dịch
Tham số	Bắt buộc	Ý nghĩa
action	Có	Sử dụng add để gán hoặc delete để gỡ bỏ liên kết chiến dịch hiện tại của số. Chữ hoa/thường và khoảng trắng bao quanh được chuẩn hóa.
campaign	Đối với add	campaignId của một chiến dịch ACTIVE thuộc sở hữu của tài khoản đã xác thực. Thương hiệu của chiến dịch cũng phải thuộc về tài khoản. Một chiến dịch được đánh dấu rõ ràng là sandbox không thể được gán cho các số gửi thật. Bỏ qua tham số này đối với delete; việc gỡ bỏ sử dụng liên kết hiện có của số.
number	Có	Số gửi thuộc sở hữu của bạn, đang hoạt động, chưa bị vô hiệu và có hỗ trợ SMS. Đối với số ở Bắc Mỹ, sử dụng mã quốc gia 1 theo sau là mười chữ số của số đó, không có dấu cộng. Trình xử lý loại bỏ các ký tự không phải chữ số và cũng tra cứu các dạng tương đương có tiền tố dấu cộng và dạng mười chữ số. Việc chuẩn hóa này không phải là kiểm tra tính hợp lệ chung của số điện thoại.

Thao tác này thay đổi một số. Thao tác không có phân trang, tham số xử lý hàng loạt hay tùy chọn chạy thử. Không sử dụng điểm cuối tạo chiến dịch chỉ để gắn một số vào một chiến dịch đã có.

Gỡ bỏ liên kết hiện tại

Sử dụng action=delete với số thuộc sở hữu của bạn. Thao tác này gỡ bỏ liên kết chiến dịch gửi của số và xóa các trường thương hiệu/chiến dịch đã lưu cho số đó. Thao tác này không xóa chiến dịch hay thương hiệu, không giải phóng số điện thoại, không hủy dịch vụ của số và không dừng việc tính phí định kỳ của chiến dịch.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=delete' \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Phản hồi và xác minh

Ví dụ hư cấu này minh họa phong bì phản hồi API thông thường và một số trường kết quả được chọn. Số trả về giữ nguyên định dạng được lưu trong tài khoản của bạn. brandId và campaignId là chuỗi rỗng sau khi gỡ bỏ thành công.

{
  "status": {"code": 200, "msg": "Campaign assignment updated."},
  "response": {
    "number": "+12025550123",
    "brandId": "BRAND_FROM_ACCOUNT",
    "campaignId": "CAMPAIGN_FROM_ACCOUNT",
    "providerStatus": 200
  }
}

providerStatus là trạng thái HTTP của đối tác nhắn tin. Trình xử lý chấp nhận phản hồi truyền tải 2xx rồi cập nhật bản ghi số cục bộ; trình xử lý không diễn giải nội dung phản hồi của đối tác để lấy một kết quả chấp nhận riêng ở mức nghiệp vụ. Do đó, một phản hồi thành công không phải là bằng chứng cho thấy việc đăng ký nhắn tin đã hoàn tất hay việc gửi sẽ thành công. Hãy xem lại trạng thái chiến dịch của số trên cổng thông tin trước khi gửi lưu lượng sản xuất.

Không coi riêng liên kết cục bộ là sự phê duyệt gửi tin. Việc phê duyệt chiến dịch và thương hiệu, cấp phát số, quyền của tài khoản, quy tắc nội dung và các giới hạn nhắn tin thông thường vẫn được áp dụng.

Lỗi và kết quả một phần

401: không có tài khoản đã xác thực nào khả dụng cho trình xử lý.
400: action hoặc number bị thiếu/không hợp lệ, hoặc một yêu cầu add không có mã định danh chiến dịch.
404: số này không phải là số SMS thuộc sở hữu của bạn, đang hoạt động và chưa bị vô hiệu.
409: chiến dịch không khả dụng cho tài khoản, không ở trạng thái ACTIVE, được đánh dấu rõ ràng là sandbox, hoặc thương hiệu của chiến dịch không khả dụng cho tài khoản.
503: tích hợp nhắn tin không khả dụng. Hãy liên hệ bộ phận hỗ trợ thay vì thay đổi thông tin đăng nhập tài khoản hoặc tự bịa ra các giá trị cấu hình.
502: yêu cầu nhắn tin đã thất bại, hết thời gian chờ hoặc trả về trạng thái HTTP không phải 2xx. providerStatus có thể được trả về. Việc hết thời gian chờ không chứng minh rằng đối tác không thực hiện thay đổi nào.
500 kèm partial=true: đối tác nhắn tin đã trả về trạng thái HTTP thành công, nhưng liên kết cục bộ không thể được xác nhận. Hãy đối soát số trên cổng thông tin hoặc liên hệ bộ phận hỗ trợ trước khi thử lại.

Hãy kiểm tra mã trạng thái API và nội dung phản hồi cũng như kết quả HTTP. Không thử lại một cách mù quáng khi hết thời gian chờ hoặc nhận kết quả một phần. Trình xử lý này không có khóa idempotency ở mức yêu cầu, không có cơ chế hoàn tác giao dịch và không kiểm tra việc hoàn tất đăng ký chiến dịch. Một lần gán cục bộ lặp lại và trùng khớp có thể trả về thành công ngay cả khi cơ sở dữ liệu báo cáo không có hàng nào thay đổi.

Phạm vi và tác động

Thao tác này thay đổi định tuyến của số gửi và liên kết chiến dịch/thương hiệu đã lưu của số đó. Trong trình xử lý đã được rà soát, thao tác không chứa bất kỳ khoản ghi nợ tài khoản trực tiếp, việc tạo chiến dịch, mua hàng hay gửi tin nhắn nào. Đây không phải là báo giá hay lời hứa về dịch vụ miễn phí: các khoản phí hiện có cho số, chiến dịch và nhắn tin vẫn tiếp tục theo điều khoản tài khoản của bạn.

Trên cổng thông tin, việc chuyển sang một chiến dịch khác trước tiên sẽ gỡ bỏ liên kết trước đó rồi mới thêm liên kết mới. Đó là hai yêu cầu riêng biệt. Nếu yêu cầu thứ hai thất bại, liên kết trước đó có thể đã bị gỡ bỏ. Không giả định rằng hai yêu cầu này sẽ cùng được hoàn tác.