Призначення номера кампанії повідомлень

Призначення номера для надсилання кампанії

Використовуйте цю операцію після того, як ваш бренд повідомлень і робоча кампанія зареєстровані, а кампанія активна. Вона прив’язує один номер із підтримкою SMS у вашому обліковому записі до кампанії. Вона не створює бренд, не створює та не затверджує кампанію, не купує номер і не надсилає повідомлення.

Поточний портал використовує цей маршрут під час призначення кампанії номеру. Публічний API приймає ідентифікатор кампанії; бренд він визначає з кампанії, що належить обліковому запису, а не приймає окремий ідентифікатор бренду.

Запит

Надішліть POST у форматі form-encoded через HTTPS, використовуючи ваш увімкнений обліковий запис API та дозволену для нього IP-адресу джерела. Використовуйте справжні ідентифікатори номера та кампанії з вашого облікового запису. Номер у цьому прикладі вигаданий.

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	campaignId кампанії зі статусом ACTIVE, що належить автентифікованому обліковому запису. Її бренд також має належати цьому обліковому запису. Кампанію, явно позначену як sandbox, не можна призначити реальним номерам для надсилання. Для 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, явно позначена як sandbox, або її бренд недоступний обліковому запису.
503: інтеграція з обміном повідомленнями недоступна. Зверніться до служби підтримки замість того, щоб змінювати облікові дані або вигадувати значення конфігурації.
502: запит до сервісу повідомлень не вдався, перевищив час очікування або повернув HTTP-статус, відмінний від 2xx. Може бути повернуто providerStatus. Перевищення часу очікування не доводить, що партнер не вніс жодних змін.
500 із partial=true: партнер з обміну повідомленнями повернув успішний HTTP-статус, але локальну прив’язку не вдалося підтвердити. Перш ніж повторювати запит, звірте номер у порталі або зверніться до служби підтримки.

Перевіряйте код статусу API та тіло відповіді, а не лише результат HTTP. Не повторюйте наосліп запит після перевищення часу очікування або часткового результату. У цього обробника немає ключа ідемпотентності на рівні запиту, транзакційного відкату чи перевірки завершення реєстрації кампанії. Повторне локальне призначення з тими самими значеннями може повернути успіх, навіть якщо база даних повідомляє про відсутність змінених рядків.

Область дії та наслідки

Ця операція змінює маршрутизацію номера для надсилання та його збережену прив’язку до кампанії/бренду. У перевіреному обробнику вона не містить прямого списання з облікового запису, створення кампанії, покупки чи надсилання повідомлень. Це не цінова пропозиція і не обіцянка безкоштовного обслуговування: наявні плати за номер, кампанію та повідомлення продовжують нараховуватися згідно з умовами вашого облікового запису.

У порталі перехід на іншу кампанію спочатку видаляє попередню прив’язку, а потім додає нову. Це окремі запити. Якщо другий запит не вдасться, попередня прив’язка може вже бути видалена. Не припускайте, що ці два запити відкочуються разом.