메시징 캠페인에 번호 할당

발신 번호를 캠페인에 할당

이 작업은 메시징 브랜드와 프로덕션 캠페인이 등록되고 캠페인이 활성화된 후에 사용하십시오. 계정의 SMS 지원 번호 하나를 캠페인에 연결합니다. 브랜드를 생성하거나, 캠페인을 생성 또는 승인하거나, 번호를 구매하거나, 메시지를 보내지 않습니다.

현재 포털은 번호에 캠페인을 할당할 때 이 경로를 사용합니다. 공개 API는 캠페인 식별자를 받으며, 별도의 브랜드 식별자를 받는 대신 계정이 소유한 캠페인에서 브랜드를 도출합니다.

요청

활성화된 API 계정과 허용된 원본 IP 주소를 사용하여 HTTPS를 통해 폼 인코딩된 POST 요청을 보내십시오. 계정의 실제 번호와 캠페인 식별자를 사용하십시오. 이 예시의 번호는 가상의 번호입니다.

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'

캠페인 할당 매개변수
매개변수	필수	의미
action	예	add를 사용하여 할당하거나 delete를 사용하여 번호의 현재 캠페인 연결을 제거합니다. 대소문자와 앞뒤 공백은 정규화됩니다.
campaign	add인 경우	인증된 계정이 소유한 ACTIVE 캠페인의 campaignId입니다. 해당 브랜드도 계정에 속해야 합니다. 명시적으로 샌드박스로 표시된 캠페인은 실제 발신 번호에 할당할 수 없습니다. delete의 경우 이 매개변수를 생략하십시오. 제거에는 번호의 기존 연결이 사용됩니다.
number	예	소유하고 있으며 활성 상태이고 무효화되지 않은 SMS 지원 발신 번호입니다. 북미 번호의 경우 더하기 기호 없이 국가 코드 1 다음에 열 자리 숫자를 입력하십시오. 핸들러는 숫자가 아닌 문자를 제거하고 더하기 기호가 붙은 형식과 열 자리 형식도 함께 조회합니다. 이 정규화는 일반적인 전화번호 유효성 검사가 아닙니다.

이 작업은 번호 하나를 변경합니다. 페이지 매김, 배치 매개변수 또는 드라이런 옵션이 없습니다. 기존 캠페인에 번호를 연결하는 목적만으로 캠페인 생성 엔드포인트를 사용하지 마십시오.

현재 연결 제거

소유한 번호와 함께 action=delete를 사용하십시오. 이렇게 하면 발신 캠페인 연결이 제거되고 해당 번호에 저장된 브랜드/캠페인 필드가 지워집니다. 캠페인이나 브랜드를 삭제하거나, 전화번호를 해제하거나, 번호의 서비스를 취소하거나, 캠페인의 정기 청구를 중지하지 않습니다.

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

응답 및 확인

이 가상의 예시는 일반적인 API 응답 봉투와 일부 결과 필드를 보여줍니다. 반환되는 번호는 계정에 저장된 형식을 유지합니다. 제거가 성공하면 brandId 및 campaignId 항목은 빈 문자열이 됩니다.

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

providerStatus는 메시징 파트너의 HTTP 상태입니다. 핸들러는 2xx 전송 응답을 수락한 다음 로컬 번호 레코드를 업데이트합니다. 파트너의 응답 본문을 해석하여 별도의 비즈니스 수준 수락 결과를 판단하지는 않습니다. 따라서 성공 응답이 메시징 등록이 완료되었거나 전달이 성공할 것이라는 증거는 아닙니다. 프로덕션 트래픽을 보내기 전에 포털에서 번호의 캠페인 상태를 검토하십시오.

로컬 연결만으로 전달이 승인된 것으로 간주하지 마십시오. 캠페인 및 브랜드 승인, 번호 프로비저닝, 계정 권한, 콘텐츠 규칙 및 일반적인 메시징 제한은 계속 적용됩니다.

오류 및 부분 결과

401: 핸들러가 사용할 수 있는 인증된 계정이 없습니다.
400: action 또는 number 항목이 누락되었거나 유효하지 않거나, add 요청에 캠페인 식별자가 없습니다.
404: 번호가 소유하고 있으며 활성 상태이고 무효화되지 않은 SMS 번호가 아닙니다.
409: 캠페인을 계정에서 사용할 수 없거나, ACTIVE 상태가 아니거나, 명시적으로 샌드박스이거나, 해당 브랜드를 계정에서 사용할 수 없습니다.
503: 메시징 통합을 사용할 수 없습니다. 계정 자격 증명을 변경하거나 구성 값을 임의로 만들지 말고 지원팀에 문의하십시오.
502: 메시징 요청이 실패했거나, 시간이 초과되었거나, 2xx가 아닌 HTTP 상태를 반환했습니다. providerStatus가 반환될 수 있습니다. 시간 초과가 파트너가 아무것도 변경하지 않았다는 증거는 아닙니다.
500 및 partial=true: 메시징 파트너가 성공 HTTP 상태를 반환했지만 로컬 연결을 확인할 수 없었습니다. 재시도하기 전에 포털에서 번호의 실제 상태를 확인하고 불일치를 해결하거나 지원팀에 문의하십시오.

HTTP 결과뿐 아니라 API 상태 코드와 응답 본문도 확인하십시오. 시간 초과나 부분 결과를 무턱대고 재시도하지 마십시오. 이 핸들러에는 요청 수준 멱등성 키, 트랜잭션 롤백 또는 캠페인 등록 완료 검사가 없습니다. 동일한 로컬 할당을 반복하면 데이터베이스가 변경된 행이 없다고 보고하더라도 성공을 반환할 수 있습니다.

범위 및 영향

이 작업은 발신 번호 라우팅과 저장된 캠페인/브랜드 연결을 변경합니다. 검토된 핸들러에는 직접적인 계정 차감, 캠페인 생성, 구매 또는 메시지 전송이 포함되어 있지 않습니다. 이는 가격 견적이나 무료 서비스 약속이 아닙니다. 기존 번호, 캠페인 및 메시징 요금은 계정 약관에 따라 계속 부과됩니다.

포털에서 다른 캠페인으로 변경하면 먼저 이전 연결이 제거된 다음 새 연결이 추가됩니다. 이는 별도의 요청입니다. 두 번째 요청이 실패하면 이전 연결은 이미 제거되었을 수 있습니다. 두 요청이 함께 롤백된다고 가정하지 마십시오.