Asignar un número a una campaña de mensajería

Asignar un número de envío a una campaña

Utilice esta operación después de que su marca de mensajería y su campaña de producción estén registradas y la campaña esté activa. Asocia un número habilitado para SMS de su cuenta con la campaña. No crea una marca, no crea ni aprueba una campaña, no compra un número ni envía un mensaje.

El portal actual utiliza esta ruta al asignar una campaña a un número. La API pública acepta un identificador de campaña; deriva la marca de la campaña propiedad de la cuenta en lugar de aceptar un identificador de marca independiente.

Solicitud

Envíe una solicitud POST codificada como formulario a través de HTTPS utilizando su cuenta de API habilitada y su dirección IP de origen permitida. Utilice los identificadores reales de número y campaña de su cuenta. El número de este ejemplo es ficticio.

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'

La operación cambia un solo número. No tiene paginación, parámetro de lote ni opción de simulación. No utilice un punto de conexión de creación de campañas simplemente para adjuntar un número a una campaña existente.

Eliminar la asociación actual

Utilice action=delete con el número propio. Esto elimina su asociación de campaña de envío y borra los campos de marca/campaña guardados para ese número. No elimina la campaña ni la marca, no libera el número de teléfono, no cancela el servicio del número ni detiene la facturación recurrente de la campaña.

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

Respuesta y verificación

Este ejemplo ficticio ilustra el sobre de respuesta ordinario de la API y algunos campos de resultado seleccionados. El número devuelto conserva el formato almacenado en su cuenta. brandId y campaignId son cadenas vacías después de una eliminación correcta.

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

providerStatus es el estado HTTP del socio de mensajería. El controlador acepta una respuesta de transporte 2xx y luego actualiza el registro local del número; no interpreta el cuerpo de la respuesta del socio para obtener un resultado de aceptación comercial independiente. Por lo tanto, una respuesta correcta no demuestra que el registro de mensajería esté completo ni que la entrega vaya a tener éxito. Revise el estado de campaña del número en el portal antes de enviar tráfico de producción.

No considere una asociación local por sí sola como aprobación de entrega. La aprobación de la campaña y de la marca, el aprovisionamiento del número, los permisos de la cuenta, las reglas de contenido y los límites de mensajería ordinarios siguen aplicándose.

Errores y resultados parciales

• 401: no hay ninguna cuenta autenticada disponible para el controlador.
• 400: falta action o number o no es válido, o una solicitud add no tiene identificador de campaña.
• 404: el número no es un número SMS propio, activo y no anulado.
• 409: la campaña no está disponible para la cuenta, no está ACTIVE, es explícitamente sandbox, o su marca no está disponible para la cuenta.
• 503: la integración de mensajería no está disponible. Póngase en contacto con el soporte en lugar de cambiar las credenciales de la cuenta o inventar valores de configuración.
• 502: la solicitud de mensajería falló, agotó el tiempo de espera o devolvió un estado HTTP distinto de 2xx. Es posible que se devuelva providerStatus. Un tiempo de espera agotado no demuestra que el socio no haya realizado ningún cambio.
• 500 con partial=true: el socio de mensajería devolvió un estado HTTP correcto, pero no se pudo confirmar la asociación local. Concilie el número en el portal o póngase en contacto con el soporte antes de reintentar.

Compruebe el código de estado de la API y el cuerpo de la respuesta, además del resultado HTTP. No reintente a ciegas tras un tiempo de espera agotado o un resultado parcial. Este controlador no tiene clave de idempotencia a nivel de solicitud, reversión transaccional ni comprobación de finalización del registro de campaña. Una asignación local repetida e idéntica puede devolver éxito incluso cuando la base de datos no informa de filas modificadas.

Alcance y efectos

Esta operación cambia el enrutamiento del número de envío y su asociación de campaña/marca guardada. No contiene ningún cargo directo a la cuenta, creación de campaña, compra ni envío de mensajes en el controlador revisado. Esto no es un presupuesto ni una promesa de servicio gratuito: los cargos existentes por número, campaña y mensajería continúan según las condiciones de su cuenta.

En el portal, cambiar a una campaña diferente primero elimina la asociación anterior y luego añade la nueva. Son solicitudes independientes. Si la segunda solicitud falla, es posible que la asociación anterior ya se haya eliminado. No asuma que las dos solicitudes se revierten juntas.