Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

API Disposition codes

Com a API de códigos de disposição, sua integração pode fazer o seguinte:

Receba listas de códigos de disposição para uma instância, uma fila ou uma sessão.
Atualize os códigos de disposição ou as observações (ou ambos) de uma sessão de chat ou chamada concluída anteriormente.

Autenticação e URL base

Todos os endpoints neste documento usam a autenticação padrão de token de API com um token de usuário da API (token de portador).

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

Receber lista de códigos de disposição

Receba os códigos de disposição disponíveis. É possível consultar no nível da instância, da fila e da sessão.

Por instância

Retorna a árvore de códigos de disposição completa da instância, incluindo todos os códigos de disposição de vários níveis.

Exemplo de solicitação

A solicitação a seguir recebe a lista completa de códigos de disposição:

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

Exemplo de resposta

O exemplo de resposta a seguir mostra a lista completa de códigos de disposição:

{
  "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

Retorna os códigos de disposição atribuídos a uma fila. Se nenhuma lista específica da fila for configurada, a lista global (no nível da instância) será retornada.

Exemplo de solicitação

A solicitação a seguir recebe códigos de encaminhamento para uma fila:

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

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`queue_id`	integer	Sim	O ID da fila para receber códigos de disposição.

Por sessão

Retorna os códigos de disposição disponíveis para um determinado ID de sessão, com base na última fila em que a sessão foi encaminhada.

Exemplo de solicitação

A solicitação a seguir recebe códigos de disposição para uma sessão:

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

Parâmetros de consulta

Parâmetro	Tipo	Obrigatório	Descrição
`session_id`	integer	Sim	O ID da sessão.

Atualizar o código e as observações de encaminhamento

Envie um código de encaminhamento ou observações atualizadas (ou ambos) para uma sessão de chat ou chamada concluída anteriormente. Isso cria um novo registro de disposição e uma observação no CRM. Ele não edita o registro original do CRM.

Exemplo de solicitação

A solicitação a seguir atualiza o código de disposição ou as observações de uma sessão:

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

Parâmetros de caminho

Parâmetro	Tipo	Obrigatório	Descrição
`session_id`	integer	Sim	O ID da sessão da chamada ou do chat a ser atualizado.

Exemplo de corpo da solicitação

Confira um exemplo de corpo da solicitação:

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

Parâmetros do corpo da solicitação

Parâmetro	Tipo	Obrigatório	Descrição
`disposition_code`	objeto	Condicional	O código de disposição atualizado. Pelo menos uma das propriedades `disposition_code` ou `notes` precisa estar presente.
`disposition_code.id`	integer	Sim (se `disposition_code` for especificado)	O ID do código de encaminhamento.
`disposition_code.full_path`	string	Sim (se `disposition_code` for especificado)	O caminho hierárquico completo do código de disposição, por exemplo, `/Support/Verification/Pending Documents`. Usado para validação em relação à árvore de disposição da sessão.
`notes`	string	Não	As observações atualizadas do agente. Consulte a tabela Comportamento das observações.

Comportamento das notas

Valor	Comportamento
Apresentar com texto, por exemplo, `"notes": "Updated notes"`	Substitui a observação atual pelo novo texto.
Apresentar como string vazia ("notes": "")	Limpa explicitamente a observação atual. O arquivo de metadados da sessão não vai mais conter a observação. O histórico do CRM retém registros anteriores.
Omitido (campo ausente da solicitação)	Deixa a observação atual inalterada.

Disposição de não ligar (DNC)

Para enviar uma ação "Não ligue", use disposition_code.id: -1. Isso só é aceito quando a instância tem o recurso de não ligar ativado e uma disposição de DNC configurada. Caso contrário, a API vai retornar 422 Unprocessable Entity com a mensagem: "A ação "Não ligar" não está ativada para este inquilino".

Atribuição do agente

A API não tem uma identidade de agente. O sistema atribui a ação aos seguintes itens, em ordem de prioridade:

O agente que enviou originalmente a ação para essa sessão.
Se não houver uma disposição original, o participante do agente mais recente na ligação ou no chat.

Se nenhum dos dois existir, a API vai retornar 422 Unprocessable Entity.

Validação

A lista a seguir descreve as regras de validação:

A chamada ou o chat da sessão precisa ter sido encerrado. A tentativa de atualizar a disposição em uma sessão ativa retorna 422 Unprocessable Entity.
Os parâmetros disposition_code.id e disposition_code.full_path são validados em relação à árvore de disposição da sessão (com base na fila pela qual a sessão foi encaminhada pela última vez).
A configuração de allow_disposition_edit administrador é um controle exclusivo da UI. A API pública sempre pode atualizar os dados de disposição, independente dessa configuração.

Exemplo de resposta

O exemplo a seguir mostra uma resposta a uma solicitação bem-sucedida:

{
  "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"
  }
}

Observação: o campo name é resolvido pelo servidor na árvore de disposição com base nos valores id e full_path especificados. Ele é retornado na resposta para facilitar.

Metadados da sessão

Quando uma disposição é atualizada usando essa API, acontece o seguinte:

Armazenamento externo: o arquivo de metadados da sessão é regenerado e substitui o arquivo de metadados atual.
CRM: uma nova observação é criada, preservando a trilha de auditoria.

Tratamento de erros

Esta seção descreve o tratamento de erros.

Códigos de status comuns

Status	Condição	Exemplo de mensagem
`400 Bad Request`	Campos obrigatórios ausentes (`disposition_code` e `notes` ausentes) ou formato inválido.	"Pelo menos um de disposition_code ou notes precisa estar presente."
`401 Unauthorized`	Token de API inválido ou ausente.	"Não autorizado"
`403 Forbidden`	O usuário da API não tem acesso à sessão ou ao locatário especificado.	"Proibido"
`404 Not Found`	A sessão não foi encontrada ou não existe.	"Sessão não encontrada."
`422 Unprocessable Entity`	Várias falhas de validação. Consulte a tabela Cenários de entidade não processável 422.	Consulte a tabela Cenários de entidade não processável 422.

422 Cenários de entidade não processável

Cenário	Mensagem de erro
A sessão de chat ou chamada ainda está ativa	"A sessão não foi encerrada. A disposição só pode ser atualizada para sessões concluídas."
O ID do código de disposição não foi encontrado na árvore da sessão	"O código de disposição é inválido para a fila desta sessão."
A ação de DNC foi enviada, mas o recurso não está ativado	"A disposição "Não ligar" não está ativada para este locatário."
Não é possível resolver nenhum participante do agente para atribuição	"Não foi possível determinar o agente para atribuição de disposição."

Exemplo de resposta

Confira um exemplo de resposta de erro:

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

Fluxo de integração típico

Confira abaixo um fluxo de integração típico:

Receba os códigos de encaminhamento da fila ou sessão relevante:
- GET /api/v1/disposition_codes?session_id=SESSION_ID
Apresente a árvore de disposições ao usuário ou ao sistema automatizado para seleção.
Envie a disposição atualizada:
- POST /api/v1/sessions/SESSION_ID/disposition
- Inclua o disposition_code selecionado, com id e full_path, e observações.
Processe a resposta:
- Em 200 OK: a disposição foi atualizada. Os registros do CRM são atualizados automaticamente.
- Em caso de erro: mostre a mensagem de erro e tente de novo ou encaminhe conforme necessário.

Comportamento do CRM

Quando uma petição inicial é enviada usando essa API, acontece o seguinte:

Uma nova observação de CRM é criada no CRM conectado, como Salesforce, ServiceNow, Zendesk, Dynamics ou HubSpot. A observação original não é modificada.
Para o armazenamento externo, o arquivo de metadados da sessão é substituído pelos dados de disposição atualizados.

Limitação

Os engajamentos de chamada do HubSpot incluem uma propriedade escalar hs_call_disposition que é substituída (não anexada) em cada atualização de disposição. Embora o histórico completo seja preservado nas notas do HubSpot, a propriedade de engajamento reflete apenas o código de disposição mais recente.

API Disposition codes Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Autenticação e URL base

Receber lista de códigos de disposição

Por instância

Por fila

Por sessão

Atualizar o código e as observações de encaminhamento

Comportamento das notas

Disposição de não ligar (DNC)

Atribuição do agente

Validação

Metadados da sessão

Tratamento de erros

Códigos de status comuns

422 Cenários de entidade não processável

Fluxo de integração típico

Comportamento do CRM

Limitação

API Disposition codes