Назначение номера кампании сообщений

Назначение номера для отправки кампании

Используйте эту операцию после того, как ваш бренд сообщений и рабочая кампания зарегистрированы, а кампания активна. Она привязывает один номер с поддержкой 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. Не повторяйте вслепую запрос после превышения времени ожидания или частичного результата. У этого обработчика нет ключа идемпотентности на уровне запроса, транзакционного отката или проверки завершения регистрации кампании. Повторное локальное назначение с теми же значениями может вернуть успех, даже если база данных сообщает об отсутствии изменённых строк.

Область действия и последствия

Эта операция изменяет маршрутизацию номера для отправки и его сохранённую привязку к кампании/бренду. В проверенном обработчике она не содержит прямого списания с учётной записи, создания кампании, покупки или отправки сообщений. Это не ценовое предложение и не обещание бесплатного обслуживания: существующие платежи за номер, кампанию и сообщения продолжают начисляться согласно условиям вашей учётной записи.

В портале переход на другую кампанию сначала удаляет предыдущую привязку, а затем добавляет новую. Это отдельные запросы. Если второй запрос завершится ошибкой, предыдущая привязка уже может быть удалена. Не предполагайте, что эти два запроса откатываются вместе.