Conferencias a tres bandas

English: Three-way conference calls.

Usa una conferencia cuando el agente y el consumidor necesiten sumar a una persona más a una llamada activa. La llamada original entre agente y consumidor se mantiene mientras el tercero entra por un tramo aparte.

Base del contrato: core v0.95.0. Esta guía describe el contrato de la API en ese release publicado.

Antes de añadir a un tercero

El acceso a conferencias viene apagado por defecto y se controla por tenant:

• conference_enabled abre conferencias con un destino interno del roster.
• conference_external_enabled permite además un número externo registrado y requiere conference_enabled.

Son ajustes del operador de la plataforma. Una aplicación del tenant puede leer la capacidad interna efectiva con GET /v1/me:

{
  "capabilities": {
    "conference": true
  }
}

Si capabilities.conference es false, las dos rutas de conferencia devuelven 404 not_found. Es un cierre en falso: no se lee el cuerpo de la petición, no se busca la llamada y no se gasta presupuesto de tasa.

Autenticación y control

Las rutas de añadir y quitar aceptan una llave de API del tenant (dd_) o un token de sesión de usuario (ddu_). El llamante debe además controlar la llamada. Un agente que ya no la controla recibe 403 forbidden. Los tokens de widget (ddw_) no pueden llamar a estas rutas y reciben 403 forbidden.

Elegir y configurar el destino

El campo destination acepta uno de estos valores:

• el sip_extension de un agente activo del roster;
• el UUID de un agente activo del roster;
• con la conferencia externa activada, el UUID de un destino de transferencia vigente o su número registrado en E.164 estricto.

El servidor recorta destination; el resultado no puede quedar en blanco ni medir más de 64 bytes. Un valor con forma de número debe usar E.164 estricto (+ seguido de 8 a 15 dígitos).

Un número externo debe registrarse primero con POST /v1/transfer-destinations. Esa ruta de gestión acepta una llave dd_ o una sesión de usuario account_admin; una sesión member recibe 403 role_forbidden.

curl -sS -X POST "$API/v1/transfer-destinations" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "number": "+13125550170",
    "label": "Legal department",
    "line_type": "landline"
  }'

number y label son obligatorios. label se recorta, no puede quedar en blanco y está limitado a 120 caracteres. line_type es opcional; sus valores son mobile, landline, voip y unknown, con unknown por defecto. Registrar un número no omite el cumplimiento: el tramo externo sigue pasando por el registro de destinos, la salida, el caller ID, el plan, la capacidad y las puertas previas a la marcación.

Añadir al tercero

Llama a POST /v1/calls/{call_id}/conference/add con un cuerpo JSON:

curl -sS -X POST "$API/v1/calls/$CALL_ID/conference/add" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"destination":"1001"}'

La petición tiene dos campos:

Campo	Obligatorio	Significado
destination	sí	Extensión interna o UUID de agente; con la conferencia externa activada, un UUID de destino registrado o un número en E.164 estricto.
consumer_agreed	solo externo	Atestación booleana de que el consumidor aceptó que el tercero externo escuche la llamada. Debe ser el literal true; un valor no booleano es 400 bad_request.

Para un destino externo:

curl -sS -X POST "$API/v1/calls/$CALL_ID/conference/add" \
  -H "Authorization: Bearer $TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "destination": "+13125550170",
    "consumer_agreed": true
  }'

La respuesta 200 contiene un resultado de control call. Se devuelve solo después de que la fila de auditoría es durable y el tramo del tercero está arriba.

En una llamada solo puede haber una conferencia abierta. Una conferencia y una consulta de transferencia atendida son mutuamente excluyentes, y una transferencia no puede empezar mientras haya una conferencia abierta.

Quitar al tercero

Llama a POST /v1/calls/{call_id}/conference/remove sin cuerpo de petición:

curl -sS -X POST "$API/v1/calls/$CALL_ID/conference/remove" \
  -H "Authorization: Bearer $TOKEN"

Quitar cuelga solo el tramo de la conferencia. El agente y el consumidor siguen en su llamada original. Si el switch ya perdió el tramo del tercero, quitar igualmente devuelve 200, porque se alcanzó el estado pedido. Si no hay ninguna conferencia abierta, la ruta devuelve 409 no_conference.

Quitar no ejecuta las puertas de plan ni de cumplimiento: retira exposición y por eso se permite incluso cuando un añadir sería rechazado.

Comportamiento de la grabación

Cuando la llamada original se está grabando, la voz del tercero se mezcla en la grabación existente del consumidor. La conferencia no crea una pista aparte ni una grabación aparte para esa persona, y después no se puede separar al tercero del consumidor.

La atestación de conferencia externa registra que el consumidor aceptó que el tercero escuche la llamada. No añade un aviso hablado de grabación. Decide el aviso y el consentimiento necesarios antes de activar la conferencia externa en un tenant.

CDR: una fila por tramo de conferencia

Cada tramo de tercero tiene su propia fila de solo anexar en call_attempts. Léela con GET /v1/call_attempts, siguiendo next_cursor hasta que sea null cuando pueda haber más de una página.

La fila del tramo lleva estos valores en compliance_snapshot:

• leg: "conference";
• conference_kind: "internal" o "external";
• conference_of: el UUID de la llamada del consumidor a la que se unió el tercero.

Usa conference_of para correlacionar el tramo con la llamada original. El tramo no pertenece a ningún deudor ni a ningún agente. Un tramo interno no tiene operador telefónico y no se factura. Un tramo externo registra su operador telefónico y se factura desde su propia contestación, no desde el acuse de la API. Los originales tienen corrects_id: null; las filas de corrección posteriores apuntan al original, y la última corrección contiene la disposición final.

Errores y comportamiento de cierre en falso

Ramifica por error.code, no por el mensaje legible.

HTTP	Códigos y significado
400	bad_request: JSON mal formado, tipo de campo inválido, destino en blanco o demasiado largo.
401	unauthorized: bearer ausente, desconocido o revocado.
402	plan_inactive: el plan está inactivo o no se puede leer su estado, por lo que se rechaza la exposición añadida.
403	forbidden: tenant suspendido, token de widget o llamante que no controla la llamada.
404	not_found: la conferencia está deshabilitada, o la llamada no existe o está fuera de este tenant.
409	conference_in_progress, consultation_in_progress o no_conference.
422	consumer_agreement_required, destination_not_found, destination_not_supported, destination_unavailable, caller_id_unavailable, conference_unanswered o compliance_blocked. Un rechazo del registro usa reason_code: destination_unregistered; un rechazo de cumplimiento previo a la marcación incluye gate: pre_dial y un decision_id cuando el motor corrió.
429	rate_limited; para un tramo externo, también carrier_cps, tenant_channels o tenant_cps.
502	call_control_failed: el switch rechazó el comando de control y la fila de auditoría se liquida como fallida.
503	audit_unavailable, esl_unavailable; para un tramo externo, también no_route o capacity_unavailable.

Un añadir que no puede escribir su evidencia, evaluar una puerta requerida, reservar capacidad o establecer el tramo del tercero no recurre a una ruta menos protegida. La llamada existente entre agente y consumidor continúa sin conferencia.