Mensajería

Generado desde DialerDigital/core commit bbb8e373d900 — especificación openapi/dialer-v1.yaml v0.151.0. No se edita a mano; consulta Cómo se construye esta referencia. Descargar la especificación OpenAPI.

English version

Traducción en curso

Esta referencia se genera desde la especificación OpenAPI. Las cadenas que todavía no tienen traducción aparecen en inglés.

Registro de marcas y campañas 10DLC a través del proveedor de SMS, y los números de una campaña aprobada. Las tarifas del proveedor se cargan al saldo a coste.

Endpoints

Método	Ruta	Resumen
`GET`	`/v1/messaging/brands`	Listar las marcas 10DLC del tenant
`POST`	`/v1/messaging/brands`	Registrar una marca 10DLC con el proveedor de SMS
`GET`	`/v1/messaging/brands/{id}`	Obtener una marca 10DLC
`POST`	`/v1/messaging/brands/{id}/refresh`	Pedir al proveedor el estado actual de una marca pendiente
`GET`	`/v1/messaging/campaigns`	Listar las campañas 10DLC del tenant
`POST`	`/v1/messaging/campaigns`	Registrar una campaña 10DLC para una marca aprobada
`GET`	`/v1/messaging/campaigns/{id}`	Obtener una campaña 10DLC
`POST`	`/v1/messaging/campaigns/{id}/refresh`	Pedir al proveedor el estado actual de una campaña pendiente
`GET`	`/v1/messaging/campaigns/{id}/numbers`	Listar los números de una campaña
`POST`	`/v1/messaging/campaigns/{id}/numbers`	Asignar un número a una campaña aprobada

Listar las marcas 10DLC del tenant

http

GET /v1/messaging/brands

Respuestas

`200`

Las marcas, de la más reciente a la más antigua.

Campo	Tipo	Obligatorio
`brands`	arreglo de MessagingBrand	sí
`brands[].id`	string (uuid)	sí
`brands[].legal_name`	string	sí
`brands[].display_name`	string	sí
`brands[].entity_type`	`private_profit` · `public_profit` · `non_profit` · `government` · `sole_proprietor`	sí
`brands[].ein_last4`	string	no
`brands[].vertical`	string	no
`brands[].website`	string	no
`brands[].email`	string	no
`brands[].phone`	string	no
`brands[].street`	string	no
`brands[].city`	string	no
`brands[].state`	string	no
`brands[].postal_code`	string	no
`brands[].country`	string	no
`brands[].vetting_requested`	boolean	no
`brands[].status`	`pending` · `approved` · `rejected`	sí
`brands[].rejection_reason`	string,null	no
`brands[].provider_brand_id`	string	no
`brands[].registry`	`mock` · `telnyx`	sí
`brands[].created_at`	string (date-time)	no
`brands[].updated_at`	string (date-time)	no

`401` — Unauthorized

Clave de API ausente, desconocida o revocada (o, en /v1/admin/*, un token de administración incorrecto o sin definir; en webhooks, una firma incorrecta o ausente). Una sesión del dashboard (ddu_) que un inicio de sesión más reciente de la misma persona haya cerrado responde en cambio con el código session_superseded (indicador de tenant single_session_enforced), para que la pantalla pueda explicar por qué se cerró la sesión; un cierre de sesión, un token vencido o uno desconocido siguen siendo unauthorized.

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

El tenant está suspendido. Una sesión del dashboard (ddu_) de un tenant cuya política de inicio de sesión (ADR 227) está en modo enforce responde 403 con el código login_policy_denied ante una solicitud desde una dirección o en una hora que la política no permite — el mismo cuerpo en ambos casos; la sesión no se revoca y una solicitud posterior dentro de la política se procesa. Un token de widget (ddw_) de un puesto queda sujeto a la misma política en cada solicitud (indicador widget_login_honors_policy). Un tenant sintético (demo) responde 403 con el código synthetic_tenant en toda ruta que llegaría a un tercero — marcación manual, pierna de transferencia externa o de conferencia, envío de SMS. Ningún pago lo cambia.

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`429` — ApiKeyRateLimited

Esta clave de API ha superado su cuota de peticiones, o las claves del tenant en conjunto han superado el techo del tenant (code rate_limited). La petición no se procesó. Espera Retry-After segundos y reintenta; un rechazo no cuenta contra el presupuesto, así que esa espera siempre basta. Acotado por clave de API y, por encima de las claves, por tenant (api_tenant_requests_per_minute): una clave hermana no se ve afectada hasta que las claves del tenant en conjunto alcanzan ese techo. La cuota se aplica a toda operación alcanzable con una clave dd_, así que las operaciones que nombran un 429 más específico (control de llamadas, disposiciones, SMS, …) PUEDEN responder TAMBIÉN este, con sus cabeceras X-RateLimit-*.

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Registrar una marca 10DLC con el proveedor de SMS

http

POST /v1/messaging/brands

Registra la marca del tenant en The Campaign Registry a través del proveedor de SMS y guarda su estado: pending, approved o rejected con rejection_reason. El EIN viaja al proveedor y no se almacena; la respuesta lleva ein_last4. La tarifa de marca del proveedor (y la de vetting, cuando vetting_requested) se carga al saldo a coste como líneas de ledger messaging_fee. registry indica si el registro fue mock (simulado: no se registra ni se cobra nada) o telnyx (real, controlado por el flag messaging_10dlc_live, desactivado por defecto). 503 fee_schedule_unset si el proveedor real no tiene tarifario configurado; entonces no se registra nada. 422 vetting_unsupported para vetting_requested: true con el proveedor real: el pedido externo de vetting no está implementado todavía, así que se rechaza antes de cualquier llamada o cobro (el registro simulado lo acepta).

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`legal_name`	string	sí
`display_name`	string	sí
`entity_type`	`private_profit` · `public_profit` · `non_profit` · `government` · `sole_proprietor`	sí
`ein`	string	no	9 dígitos; solo de escritura, nunca se almacena completo.
`vertical`	string	sí
`website`	string	no
`email`	string	sí
`phone`	string	sí
`street`	string	sí
`city`	string	sí
`state`	string	sí
`postal_code`	string	sí
`country`	string	no
`vetting_requested`	boolean	no

Respuestas

`201`

La marca registrada.

Campo	Tipo	Obligatorio
`brand`	object (MessagingBrand)	sí
`brand.id`	string (uuid)	sí
`brand.legal_name`	string	sí
`brand.display_name`	string	sí
`brand.entity_type`	`private_profit` · `public_profit` · `non_profit` · `government` · `sole_proprietor`	sí
`brand.ein_last4`	string	no
`brand.vertical`	string	no
`brand.website`	string	no
`brand.email`	string	no
`brand.phone`	string	no
`brand.street`	string	no
`brand.city`	string	no
`brand.state`	string	no
`brand.postal_code`	string	no
`brand.country`	string	no
`brand.vetting_requested`	boolean	no
`brand.status`	`pending` · `approved` · `rejected`	sí
`brand.rejection_reason`	string,null	no
`brand.provider_brand_id`	string	no
`brand.registry`	`mock` · `telnyx`	sí
`brand.created_at`	string (date-time)	no
`brand.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`422` — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

json

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

`502` — BadGateway

Una dependencia ascendente (el sandbox del runtime de IA) devolvió una respuesta inesperada o fallida.

json

{
  "error": {
    "code": "bad_gateway",
    "message": "the AI runtime sandbox could not be reached"
  }
}

Obtener una marca 10DLC

http

GET /v1/messaging/brands/{id}

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

La marca.

Campo	Tipo	Obligatorio
`brand`	object (MessagingBrand)	sí
`brand.id`	string (uuid)	sí
`brand.legal_name`	string	sí
`brand.display_name`	string	sí
`brand.entity_type`	`private_profit` · `public_profit` · `non_profit` · `government` · `sole_proprietor`	sí
`brand.ein_last4`	string	no
`brand.vertical`	string	no
`brand.website`	string	no
`brand.email`	string	no
`brand.phone`	string	no
`brand.street`	string	no
`brand.city`	string	no
`brand.state`	string	no
`brand.postal_code`	string	no
`brand.country`	string	no
`brand.vetting_requested`	boolean	no
`brand.status`	`pending` · `approved` · `rejected`	sí
`brand.rejection_reason`	string,null	no
`brand.provider_brand_id`	string	no
`brand.registry`	`mock` · `telnyx`	sí
`brand.created_at`	string (date-time)	no
`brand.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Pedir al proveedor el estado actual de una marca pendiente

http

POST /v1/messaging/brands/{id}/refresh

Una marca que ya no está pending se devuelve tal cual; no se llama al proveedor.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

La marca con su estado actual.

Campo	Tipo	Obligatorio
`brand`	object (MessagingBrand)	sí
`brand.id`	string (uuid)	sí
`brand.legal_name`	string	sí
`brand.display_name`	string	sí
`brand.entity_type`	`private_profit` · `public_profit` · `non_profit` · `government` · `sole_proprietor`	sí
`brand.ein_last4`	string	no
`brand.vertical`	string	no
`brand.website`	string	no
`brand.email`	string	no
`brand.phone`	string	no
`brand.street`	string	no
`brand.city`	string	no
`brand.state`	string	no
`brand.postal_code`	string	no
`brand.country`	string	no
`brand.vetting_requested`	boolean	no
`brand.status`	`pending` · `approved` · `rejected`	sí
`brand.rejection_reason`	string,null	no
`brand.provider_brand_id`	string	no
`brand.registry`	`mock` · `telnyx`	sí
`brand.created_at`	string (date-time)	no
`brand.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

`502` — BadGateway

Una dependencia ascendente (el sandbox del runtime de IA) devolvió una respuesta inesperada o fallida.

json

{
  "error": {
    "code": "bad_gateway",
    "message": "the AI runtime sandbox could not be reached"
  }
}

Listar las campañas 10DLC del tenant

http

GET /v1/messaging/campaigns

Respuestas

`200`

Las campañas, de la más reciente a la más antigua.

Campo	Tipo	Obligatorio	Descripción
`campaigns`	arreglo de MessagingCampaign	sí
`campaigns[].id`	string (uuid)	sí
`campaigns[].brand_id`	string (uuid)	sí
`campaigns[].use_case`	string	sí
`campaigns[].description`	string	no
`campaigns[].message_flow`	string	no
`campaigns[].sample_messages`	arreglo de string	no
`campaigns[].help_message`	string	no
`campaigns[].optin_keywords`	string	no
`campaigns[].optout_keywords`	string	no
`campaigns[].status`	`pending` · `approved` · `rejected`	sí
`campaigns[].rejection_reason`	string,null	no
`campaigns[].provider_campaign_id`	string	no
`campaigns[].monthly_fee_usd`	string	no	Cadena decimal; la tarifa mensual del proveedor, a coste.
`campaigns[].registry`	`mock` · `telnyx`	sí
`campaigns[].created_at`	string (date-time)	no
`campaigns[].updated_at`	string (date-time)	no

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Registrar una campaña 10DLC para una marca aprobada

http

POST /v1/messaging/campaigns

Registra una campaña para una marca cuyo estado es approved (409 brand_not_approved en otro caso) y guarda su estado. La tarifa mensual de campaña del proveedor del primer mes se carga al saldo a coste como una línea messaging_fee; los meses siguientes se facturan exactamente una vez al mes. Un texto desde un número local de EE. UU. solo sale por un número asignado a una campaña approved (en otro caso 422 sms_10dlc_campaign_required en POST /v1/sms/messages).

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio
`brand_id`	string (uuid)	sí
`use_case`	string	sí
`description`	string	sí
`message_flow`	string	sí
`sample_messages`	arreglo de string	sí
`help_message`	string	no
`optin_keywords`	string	no
`optout_keywords`	string	no

Respuestas

`201`

La campaña registrada.

Campo	Tipo	Obligatorio	Descripción
`campaign`	object (MessagingCampaign)	sí
`campaign.id`	string (uuid)	sí
`campaign.brand_id`	string (uuid)	sí
`campaign.use_case`	string	sí
`campaign.description`	string	no
`campaign.message_flow`	string	no
`campaign.sample_messages`	arreglo de string	no
`campaign.help_message`	string	no
`campaign.optin_keywords`	string	no
`campaign.optout_keywords`	string	no
`campaign.status`	`pending` · `approved` · `rejected`	sí
`campaign.rejection_reason`	string,null	no
`campaign.provider_campaign_id`	string	no
`campaign.monthly_fee_usd`	string	no	Cadena decimal; la tarifa mensual del proveedor, a coste.
`campaign.registry`	`mock` · `telnyx`	sí
`campaign.created_at`	string (date-time)	no
`campaign.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`409` — Conflict

Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.

json

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

`422` — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

json

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

`502` — BadGateway

Una dependencia ascendente (el sandbox del runtime de IA) devolvió una respuesta inesperada o fallida.

json

{
  "error": {
    "code": "bad_gateway",
    "message": "the AI runtime sandbox could not be reached"
  }
}

Obtener una campaña 10DLC

http

GET /v1/messaging/campaigns/{id}

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

La campaña.

Campo	Tipo	Obligatorio	Descripción
`campaign`	object (MessagingCampaign)	sí
`campaign.id`	string (uuid)	sí
`campaign.brand_id`	string (uuid)	sí
`campaign.use_case`	string	sí
`campaign.description`	string	no
`campaign.message_flow`	string	no
`campaign.sample_messages`	arreglo de string	no
`campaign.help_message`	string	no
`campaign.optin_keywords`	string	no
`campaign.optout_keywords`	string	no
`campaign.status`	`pending` · `approved` · `rejected`	sí
`campaign.rejection_reason`	string,null	no
`campaign.provider_campaign_id`	string	no
`campaign.monthly_fee_usd`	string	no	Cadena decimal; la tarifa mensual del proveedor, a coste.
`campaign.registry`	`mock` · `telnyx`	sí
`campaign.created_at`	string (date-time)	no
`campaign.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Pedir al proveedor el estado actual de una campaña pendiente

http

POST /v1/messaging/campaigns/{id}/refresh

Una campaña que ya no está pending se devuelve tal cual; no se llama al proveedor.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

La campaña con su estado actual.

Campo	Tipo	Obligatorio	Descripción
`campaign`	object (MessagingCampaign)	sí
`campaign.id`	string (uuid)	sí
`campaign.brand_id`	string (uuid)	sí
`campaign.use_case`	string	sí
`campaign.description`	string	no
`campaign.message_flow`	string	no
`campaign.sample_messages`	arreglo de string	no
`campaign.help_message`	string	no
`campaign.optin_keywords`	string	no
`campaign.optout_keywords`	string	no
`campaign.status`	`pending` · `approved` · `rejected`	sí
`campaign.rejection_reason`	string,null	no
`campaign.provider_campaign_id`	string	no
`campaign.monthly_fee_usd`	string	no	Cadena decimal; la tarifa mensual del proveedor, a coste.
`campaign.registry`	`mock` · `telnyx`	sí
`campaign.created_at`	string (date-time)	no
`campaign.updated_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

`502` — BadGateway

Una dependencia ascendente (el sandbox del runtime de IA) devolvió una respuesta inesperada o fallida.

json

{
  "error": {
    "code": "bad_gateway",
    "message": "the AI runtime sandbox could not be reached"
  }
}

Listar los números de una campaña

http

GET /v1/messaging/campaigns/{id}/numbers

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Respuestas

`200`

Los números.

Campo	Tipo	Obligatorio
`numbers`	arreglo de MessagingCampaignNumber	sí
`numbers[].id`	string (uuid)	sí
`numbers[].campaign_id`	string (uuid)	sí
`numbers[].e164`	string	sí
`numbers[].created_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

Asignar un número a una campaña aprobada

http

POST /v1/messaging/campaigns/{id}/numbers

El número debe ser un número activo del tenant (422 number_not_owned) y la campaña debe estar approved (409 campaign_not_approved). Repetir la misma asignación devuelve la fila existente; un número de otra campaña es 409 number_assigned_elsewhere.

Parámetros

Nombre	En	Tipo	Obligatorio	Descripción
`id`	path	string (uuid)	sí	UUID del recurso. Los ids mal formados o de otro tenant se leen como `404`.

Cuerpo de la petición (JSON, obligatorio)

Campo	Tipo	Obligatorio	Descripción
`e164`	string	sí

Respuestas

`201`

La asignación.

Campo	Tipo	Obligatorio
`number`	object (MessagingCampaignNumber)	sí
`number.id`	string (uuid)	sí
`number.campaign_id`	string (uuid)	sí
`number.e164`	string	sí
`number.created_at`	string (date-time)	no

`400` — BadRequest

Petición mal formada (errores de forma/tipo, filtros no válidos, marcas de tiempo erróneas).

json

{
  "error": {
    "code": "bad_request",
    "message": "from must be RFC-3339"
  }
}

`401` — Unauthorized

json

{
  "error": {
    "code": "unauthorized",
    "message": "invalid or revoked API key"
  }
}

`403` — Forbidden

json

{
  "error": {
    "code": "forbidden",
    "message": "tenant is suspended"
  }
}

`404` — NotFound

Id desconocido, mal formado (no UUID) O id de otro tenant: RLS devuelve cero filas, así que los tres son indistinguibles por diseño (sin fuga de existencia, nunca un 403 para ids ajenos).

json

{
  "error": {
    "code": "not_found",
    "message": "resource not found for this tenant"
  }
}

`409` — Conflict

Transición de estado no válida, conflicto de unicidad, o un asiento que está ocupado/reservado.

json

{
  "error": {
    "code": "conflict",
    "message": "invalid state transition"
  }
}

`422` — Unprocessable

La forma es correcta, la semántica no (regla de dominio incumplida).

json

{
  "error": {
    "code": "unprocessable",
    "message": "scheduled_at is closer than the minimum notice for a callback (10 minutes unless the tenant's callback_min_notice_seconds says otherwise)"
  }
}

`429` — ApiKeyRateLimited

json

{
  "error": {
    "code": "rate_limited",
    "message": "API key request quota exceeded; retry after the interval in Retry-After"
  }
}

`502` — BadGateway

Una dependencia ascendente (el sandbox del runtime de IA) devolvió una respuesta inesperada o fallida.

json

{
  "error": {
    "code": "bad_gateway",
    "message": "the AI runtime sandbox could not be reached"
  }
}

Mensajería ​

Endpoints ​

Listar las marcas 10DLC del tenant ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

429 — ApiKeyRateLimited ​

Registrar una marca 10DLC con el proveedor de SMS ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

422 — Unprocessable ​

429 — ApiKeyRateLimited ​

502 — BadGateway ​

Obtener una marca 10DLC ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Pedir al proveedor el estado actual de una marca pendiente ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

502 — BadGateway ​

Listar las campañas 10DLC del tenant ​

200 ​

401 — Unauthorized ​

403 — Forbidden ​

429 — ApiKeyRateLimited ​

Registrar una campaña 10DLC para una marca aprobada ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

422 — Unprocessable ​

429 — ApiKeyRateLimited ​

502 — BadGateway ​

Obtener una campaña 10DLC ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Pedir al proveedor el estado actual de una campaña pendiente ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

502 — BadGateway ​

Listar los números de una campaña ​

200 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

429 — ApiKeyRateLimited ​

Asignar un número a una campaña aprobada ​

201 ​

400 — BadRequest ​

401 — Unauthorized ​

403 — Forbidden ​

404 — NotFound ​

409 — Conflict ​

422 — Unprocessable ​

429 — ApiKeyRateLimited ​

502 — BadGateway ​

Mensajería

Endpoints

Listar las marcas 10DLC del tenant

`200`

`401` — Unauthorized

`403` — Forbidden

`429` — ApiKeyRateLimited

Registrar una marca 10DLC con el proveedor de SMS

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`422` — Unprocessable

`429` — ApiKeyRateLimited

`502` — BadGateway

Obtener una marca 10DLC

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

Pedir al proveedor el estado actual de una marca pendiente

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

`502` — BadGateway

Listar las campañas 10DLC del tenant

`200`

`401` — Unauthorized

`403` — Forbidden

`429` — ApiKeyRateLimited

Registrar una campaña 10DLC para una marca aprobada

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`422` — Unprocessable

`429` — ApiKeyRateLimited

`502` — BadGateway

Obtener una campaña 10DLC

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

Pedir al proveedor el estado actual de una campaña pendiente

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

`502` — BadGateway

Listar los números de una campaña

`200`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`429` — ApiKeyRateLimited

Asignar un número a una campaña aprobada

`201`

`400` — BadRequest

`401` — Unauthorized

`403` — Forbidden

`404` — NotFound

`409` — Conflict

`422` — Unprocessable

`429` — ApiKeyRateLimited

`502` — BadGateway