API de códigos de disposición

La API de códigos de disposición permite que tu integración haga lo siguiente:

  • Obtener listas de códigos de disposición para una instancia, una fila o una sesión

  • Actualizar los códigos de disposición o las notas (o ambos) para una llamada o una sesión de chat completadas anteriormente

Autenticación y URL base

Todos los extremos de este documento usan la autenticación estándar de tokens de API con un token de usuario de API (token de portador).

URL base: https://SUBDOMAIN.REGION_CODE.ccaiplatform.com

Obtén la lista de códigos de disposición

Obtén los códigos de disposición disponibles. Puedes consultar a nivel de instancia, fila y sesión.

Por instancia

Muestra el árbol de códigos de disposición completo de la instancia, incluidos todos los códigos de disposición de varios niveles.

Ejemplo de solicitud

La siguiente solicitud obtiene la lista completa de códigos de disposición:

GET /api/v1/disposition_codes
Authorization: Bearer {token}
Content-Type: application/json

Ejemplo de respuesta

En el siguiente ejemplo de respuesta, se muestra la lista completa de códigos de disposición:

{
  "disposition_codes": [
    {
      "id": 1,
      "name": "Issue Resolved",
      "full_path": "/Support/Issue Resolved",
      "children": []
    },
    {
      "id": 2,
      "name": "Escalated",
      "full_path": "/Support/Escalated",
      "children": [
        {
          "id": 3,
          "name": "Tier 2",
          "full_path": "/Support/Escalated/Tier 2",
          "children": []
        }
      ]
    }
  ]
}

Por fila

Muestra los códigos de disposición asignados a una fila. Si no se configura una lista específica de la fila, se muestra la lista global (a nivel de la instancia).

Ejemplo de solicitud

La siguiente solicitud obtiene códigos de disposición para una fila:

GET /api/v1/disposition_codes?queue_id=QUEUE_ID
Authorization: Bearer TOKEN
Content-Type: application/json

Parámetros de consulta

Parámetro Tipo Obligatorio Descripción
queue_id integer Sí Es el ID de la fila para la que se obtendrán los códigos de disposición.

Por sesión

Muestra los códigos de disposición disponibles para un ID de sesión determinado, según la última fila por la que se enrutó la sesión.

Ejemplo de solicitud

La siguiente solicitud obtiene códigos de disposición para una sesión:

GET /api/v1/disposition_codes?session_id=SESSION_ID
Authorization: Bearer TOKEN
Content-Type: application/json

Parámetros de consulta

Parámetro Tipo Obligatorio Descripción
session_id integer Sí Es el ID de sesión.

Actualiza el código de disposición y las notas

Envía un código de disposición o notas actualizados (o ambos) para una llamada o una sesión de chat completadas anteriormente. Esto crea un nuevo registro de disposición y una nota de CRM. No edita el registro de CRM original.

Ejemplo de solicitud

La siguiente solicitud actualiza el código de disposición o las notas de una sesión:

POST /api/v1/sessions/SESSION_ID/disposition
Authorization: Bearer TOKEN
Content-Type: application/json

Parámetros de ruta

Parámetro Tipo Obligatorio Descripción
session_id integer Sí Es el ID de sesión de la llamada o el chat que se actualizará.

Ejemplo de cuerpo de la solicitud

En el siguiente ejemplo, se muestra un cuerpo de la solicitud:

{
  "disposition_code": {
    "id": 5,
    "full_path": "/Support/Verification/Pending Documents"
  },
  "notes": "Customer must upload documents via portal."
}

Parámetros del cuerpo de la solicitud

Parámetro Tipo Obligatorio Descripción
disposition_code objeto Condicional Es el código de disposición actualizado. Debe estar presente al menos uno de disposition_code o notes.
disposition_code.id integer Sí (si se especificó disposition_code) Es el ID del código de disposición.
disposition_code.full_path string Sí (si se especificó disposition_code) Es la ruta jerárquica completa del código de disposición, por ejemplo, /Support/Verification/Pending Documents. Se usa para la validación en el árbol de disposición de la sesión.
notes string No Son las notas del agente actualizadas. Consulta la tabla Comportamiento de las notas.

Comportamiento de las notas

Valor Comportamiento
Presente con texto, por ejemplo, "notes": "Updated notes" Reemplaza la nota existente por el texto nuevo.
Presente como cadena vacía ("notes": "") Borra explícitamente la nota existente. El archivo de metadatos de la sesión ya no incluirá la nota. El historial de CRM conserva los registros anteriores.
Omitido (campo ausente de la solicitud) Deja la nota existente sin cambios.

Disposición de no llamar (DNC)

Para enviar una disposición de "No llamar", usa disposition_code.id: -1. Esto solo se acepta cuando la instancia tiene habilitada la función de no llamar y se configura una disposición de DNC. De lo contrario, la API muestra 422 Unprocessable Entity con el mensaje: "Do Not Call disposition is not enabled for this tenant."

Atribución del agente

La API no incluye una identidad del agente. El sistema atribuye la disposición a lo siguiente, en orden de prioridad:

  1. El agente que envió originalmente la disposición para esta sesión

  2. Si no existe una disposición original, el participante del agente más reciente en la llamada o el chat

Si no existe ninguno, la API muestra 422 Unprocessable Entity.

Validación

En la siguiente lista, se describen las reglas de validación:

  • Debe haber finalizado la llamada o el chat de la sesión. Si intentas actualizar la disposición en una sesión activa, se muestra 422 Unprocessable Entity.

  • Los parámetros disposition_code.id y disposition_code.full_path se validan en el árbol de disposición de la sesión (según la fila por la que se enrutó la sesión por última vez).

  • El parámetro de configuración del administrador allow_disposition_edit es un control solo de la IU. La API pública siempre puede actualizar los datos de disposición, independientemente de este parámetro de configuración.

Ejemplo de respuesta

En el siguiente ejemplo, se muestra una respuesta a una solicitud exitosa:

{
  "session_id": 12345,
  "disposition": {
    "id": 5,
    "name": "Verification Pending",
    "full_path": "/Support/Verification/Pending Documents",
    "notes": "Customer must upload documents via portal.",
    "submitted_at": "2026-03-13T10:15:01Z"
  }
}

Nota: El campo name es resuelto por el servidor del árbol de disposición según los valores id y full_path especificados. Se muestra en la respuesta para mayor comodidad.

Metadatos de sesión

Cuando se actualiza una disposición con esta API, sucede lo siguiente:

  • Almacenamiento externo: Se vuelve a generar el archivo de metadatos de la sesión y se reemplaza el archivo de metadatos existente.

  • CRM: Se crea una nota nueva, lo que preserva el registro de auditoría.

Manejo de errores

En esta sección, se describe el manejo de errores.

Códigos de estado comunes

Estado Condición Mensaje de ejemplo
400 Bad Request Faltan campos obligatorios (ausentes disposition_code y notes) o el formato no es válido. "At least one of disposition_code or notes must be present."
401 Unauthorized El token de API no es válido o falta. "Unauthorized"
403 Forbidden El usuario de la API no tiene acceso a la sesión o el arrendatario especificados. "Forbidden"
404 Not Found No se encontró la sesión o no existe. "Session not found."
422 Unprocessable Entity Varias fallas de validación. Consulta la tabla Situaciones de entidad no procesable 422. Consulta la tabla Situaciones de entidad no procesable 422.

Situaciones de entidad no procesable 422

Situación Mensaje de error
La llamada o la sesión de chat aún están activas "Session has not ended. Disposition can only be updated for completed sessions."
No se encontró el ID del código de disposición en el árbol de la sesión "Disposition code is invalid for this session's queue."
Se envió la disposición de DNC, pero la función no está habilitada "Do Not Call disposition is not enabled for this tenant."
No se puede resolver ningún participante del agente para la atribución "Unable to determine agent for disposition attribution."

Ejemplo de respuesta

En el siguiente ejemplo, se muestra una respuesta de error:

{
  "error": {
    "code": "session_not_ended",
    "message": "Session has not ended. Disposition can only be updated for completed sessions.",
    "details": {
      "session_id": 12345
    }
  }
}

Flujo de integración típico

El siguiente es un flujo de integración típico:

  1. Obtén códigos de disposición para la fila o la sesión pertinentes:

    • GET /api/v1/disposition_codes?session_id=SESSION_ID

  2. Presenta el árbol de disposición al usuario o al sistema automatizado para su selección.

  3. Envía la disposición actualizada:

    • POST /api/v1/sessions/SESSION_ID/disposition

    • Incluye el disposition_code seleccionado, con id y full_path, y cualquier nota.

  4. Maneja la respuesta:

    • En 200 OK: Se actualizó la disposición. Los registros de CRM se actualizan automáticamente.

    • En caso de error: Muestra el mensaje de error y vuelve a intentarlo o escálalo según corresponda.

Comportamiento de CRM

Cuando se envía una disposición con esta API, sucede lo siguiente:

  • Se crea una nueva nota de CRM en el CRM conectado, como Salesforce, ServiceNow, Zendesk, Dynamics o HubSpot. La nota original no se modifica.

  • Para el almacenamiento externo, el archivo de metadatos de la sesión se reemplaza por los datos de disposición actualizados.

Limitación

Los compromisos de llamadas de HubSpot incluyen una propiedad escalar hs_call_disposition que se reemplaza (no se agrega) en cada actualización de disposición. Si bien el historial completo se conserva en las notas de HubSpot, la propiedad de interacción solo refleja el código de disposición más reciente.