API do membro da conversa

  • Versão de lançamento: Zurich
  • Atualizado 31 de jul. de 2025
  • 9 min. de leitura

    • . Membro da conversa A API fornece métodos para mudar o estado de membro de um agente específico para removido ou atualizado em uma determinada conversa de Bate-papo do agente.

    Esta API fornece a capacidade de gerenciar programaticamente o estado de um membro do agente em conversas em Bate-papo do agente Experiência de Interfaces conversacionais. Consulte Bate-papo do agente para obter mais informações.

    Esta API está disponível por padrão. O usuário chamador deve ter a função awa_integration_user.

    Membro da conversa - PUT /now/conversation/member//drop

    Desconecta um agente de uma conversa.

    Formato de URL

    URL padrão: /api/now/conversation/member//drop

    Parâmetros de solicitação compatíveis

    Tabela 1. Parâmetros de caminho
    Nome Descrição
    user_id Sys_id do agente a ser descartado da conversa.

    Tipo de dados: Cadeia de caracteres

    Tabela: Usuário [sys_user]
    Tabela 2. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 3. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    interaction_id Obrigatório. Sys_id do registro de conversa do qual descartar o agente.

    Tipo de dados: Cadeia de caracteres

    Tabela: Interação [interaction]

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis .

    Tabela 4. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tipo de conteúdo Formato de dados do corpo da solicitação. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 5. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da REST API .

    Tabela 6. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400Erro ao processar operações de Membro de conversa. Por exemplo:
    • A conversa não foi encontrada para a interação fornecida.
    • O usuário não é membro da conversa de interação fornecida.

      Forneça um user_id ou interaction_id diferente na solicitação.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido. O usuário não tem direitos de acesso ao registro especificado.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    conversation_member Objeto que contém informações sobre o status do agente como membro da conversa, depois que a solicitação de desconexão é processada.

    Tipo de dados: Objeto

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.active Sinalizador que indica se o usuário atual está presente na conversa.
    Valores possíveis:
    • Verdadeiro: O agente está ativo na conversa.
    • Falso: O agente foi descartado da conversa e não é mais um participante ativo no bate-papo.

    Tipo de dados: Booliano
    Conversation_member.memberType Tipo de agente membro.
    Valores possíveis:
    • Public_fulfiller: Permite que o agente converse publicamente com outros agentes e solicitante em uma determinada conversa.
    • Observador: Disponível somente para o usuário com a função de gerente. Concede o direito de ver o conteúdo da conversa sem ingressar na conversa.
    • Private_fulfiller: Permite que o agente ingresse em um bate-papo privado entre os agentes para discutir a conversa ativa.

    Tipo de dados: Cadeia de caracteres

    Tabela: Membro da conversa [sys_cs_conversation_member]
    conversation_member.conversation_id Obrigatório. Sys_id do registro de conversa do qual o agente foi descartado.

    Tipo de dados: Cadeia de caracteres

    Tabela: Interação [interaction]
    êxito Sinalizador que indica se o processo de descartar agente foi bem-sucedido.
    Valores válidos:
    • Verdadeiro: Agente descartado com sucesso.
    • Falso: O agente não foi descartado e ainda é considerado ativo na conversa.

    Tipo de dados: Booliano
    mensagem Mensagem de resposta confirmando atribuição ou exceção bem-sucedida.

    Mensagem de sucesso: Solicitação para descartar agente processada com sucesso.

    Possíveis exceções:
    • Solicitação inválida. Entrada insuficiente O sys_id do agente ou o sys_id da interação não foi fornecido na solicitação.
    • A interação fornecida não é uma interação de terceiros : A solicitação só funciona para a interação de terceiros e o interaction_id fornecido não é uma interação de terceiros.
    • Não foi possível encontrar a conversa da interação correspondente Não é possível encontrar o registro de conversa correspondente com o sys_id de interação fornecido.
    • Solicitação inválida. O usuário não é membro da interação fornecida : O sys_id do agente não é membro da conversa de interação fornecida.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    O exemplo a seguir demonstra como descartar o ID de usuário do agente fornecido do ID de interação fornecido.

    curl "https://instance.servicenow.com/api/now/conversation/member/0b10223c57a313005baaaa65ef94f970/drop" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{\" interaction_id":\"27f675e3739713004a905ee515f6a7c3\"}" \ 
--user 'username':'password'

    A resposta mostra uma operação de descarte bem-sucedida para o agente fornecido a partir da interação. Observe que o campo ativo está definido como falso e a mensagem indica uma operação de descarte bem-sucedida.

    {
  "result": {
    "conversation_member": {
      "active": false,
      "memberType": "public_fulfiller",
      "conversation_id": "27f675e3739713004a905ee515f6a7c3"
    },
    "success": true,
    "message": "Request to drop agent processed successfully."
  }
}

    Membro da conversa - COLOQUE /now/conversation/member/(user_id)/update

    Atualiza o tipo de membro do agente em uma determinada conversa para um executante público de um observador ou executante privado.

    Você só pode usar este endpoint para atualizar o observador atual ou o tipo de executante privado de um agente para um tipo de executante público. Este endpoint não é compatível com a alternância do agente de volta para um observador ou tipo privado. A resposta retornará um código de status 500 se o agente fornecido já tiver uma função de executante público.

    O cenário a seguir é um exemplo de como o tipo de membro de um agente é atualizado usando Atualização PUT do membro da conversa endpoint:
    1. O supervisor abre e observa uma conversa em andamento na qual o agente está pedindo ajuda.
    2. O supervisor decide ingressar na conversa para oferecer ajuda e clica no botão "Ingressar na conversa" na IU. A solicitação de ingresso na conversa é enviada para o servidor de terceiros.
    3. O servidor de terceiros processa a solicitação de ingresso na conversa e chama o. Atualização PUT do membro da conversa endpoint e atualiza o tipo de membro do supervisor de observador para executante público.
    4. A IU do cliente do agente reflete o estado da conversa atualizado.

    Formato de URL

    URL com controle de versão: /api/now/

    URL padrão: /api/now/conversation/member//update

    Parâmetros de solicitação compatíveis

    Tabela 7. Parâmetros de caminho
    Nome Descrição
    api_version Opcional. Versão do endpoint a ser acessado. Por exemplo, v1 ou v2 . Especifique este valor somente para usar uma versão de endpoint diferente da mais recente.

    Tipo de dados: Cadeia de caracteres
    user_id Sys_id do agente a ser atualizado com um novo tipo de membro na conversa.

    Tipo de dados: Cadeia de caracteres

    Tabela: Usuário [sys_user]
    Tabela 8. Parâmetros de consulta
    Nome Descrição
    Nenhum(a)
    Tabela 9. Solicitar parâmetros do corpo (XML ou JSON)
    Nome Descrição
    interaction_id Obrigatório. Sys_id do registro de conversa no qual o tipo de membro do agente será atualizado.

    Tipo de dados: Cadeia de caracteres

    Tabela: Interação [interaction]
    member_type Obrigatório. Tipo de membro para atualizar o agente na conversa fornecida.

    Somente valor válido: Public_fulfiller

    Tipo de dados: Cadeia de caracteres

    Tabela: Membro da conversa [sys_cs_conversation_member], Campo: Tipo de membro

    Cabeçalhos

    Os cabeçalhos de solicitação e resposta a seguir se aplicam somente a esta ação HTTP ou se aplicam a esta ação de maneira distinta. Para obter uma lista de cabeçalhos gerais usados na REST API, consulte Cabeçalhos de REST API compatíveis .

    Tabela 10. Cabeçalhos da solicitação
    Cabeçalho Descrição
    Aceitar Formato de dados do corpo da resposta. Tipos compatíveis: application/jsonou application/xml.

    Padrão: application/json
    Tabela 11. Cabeçalhos de resposta
    Cabeçalho Descrição
    Nenhum(a)

    Códigos de status

    Os seguintes códigos de status se aplicam a esta ação HTTP. Para obter uma lista de possíveis códigos de status usados na REST API, consulte Códigos de resposta HTTP da REST API .

    Tabela 12. Códigos de status
    Código do status Descrição
    200 Bem-sucedido. A solicitação foi processada com sucesso.
    400 Erro ao processar operações de Membro de conversa.
    Por exemplo:
    • A conversa não foi encontrada para a interação fornecida.
    • O usuário não é membro da conversa de interação fornecida.
    401 Não autorizado. As credenciais do usuário estão incorretas ou não foram aprovadas.
    403 Proibido. O usuário não tem direitos de acesso ao registro especificado.
    500 Erro interno do servidor. Ocorreu um erro inesperado ao processar a solicitação. A resposta contém informações adicionais sobre o erro.

    Parâmetros do corpo da resposta (JSON ou XML)

    Nome Descrição
    conversation_member Objeto que contém informações sobre o estado do membro do agente depois que a solicitação de atualização é processada.

    Tipo de dados: Objeto

    "conversation_member": { 
  "active": Boolean, 
  "memberType": "String", 
  "conversation_id": "String"
}
    conversation_member.active Sinalizador que indica se o usuário atual está presente na conversa.
    Valores possíveis:
    • Verdadeiro: O agente está ativo na conversa.
    • Falso: O agente foi descartado da conversa e não é mais um participante ativo no bate-papo.

    Tipo de dados: Booliano
    Conversation_member.memberType Tipo de agente membro.
    Valores possíveis:
    • Public_fulfiller: Permite que o agente converse publicamente com outros agentes e solicitante em uma determinada conversa.
    • Observador: Disponível somente para o usuário com a função de gerente. Concede o direito de ver o conteúdo da conversa sem ingressar na conversa.
    • Private_fulfiller: Permite que o agente ingresse em um bate-papo privado entre os agentes para discutir a conversa ativa.

    Tipo de dados: Cadeia de caracteres

    Tabela: Membro da conversa [sys_cs_conversation_member]
    conversation_member.conversation_id Sys_id do registro de conversa em que o agente foi atualizado.

    Tipo de dados: Cadeia de caracteres

    Tabela: Interação [interaction]
    êxito Sinalizador que indica se o processo de atualização foi bem-sucedido.
    Valores válidos:
    • Verdadeiro: Agente atualizado com sucesso.
    • Falso: Falha ao atualizar o agente.

    Tipo de dados: Booliano
    mensagem Mensagem de resposta confirmando atribuição ou exceção bem-sucedida.

    Mensagem de sucesso: Solicitação para atualizar o tipo de membro do agente processada com sucesso.

    Possíveis exceções:
    • Solicitação inválida. Entrada insuficiente o sys_id do agente ou o sys_id da interação não foi fornecido na solicitação.
    • A interação fornecida não é uma interação de terceiros : a solicitação funciona somente para a interação de terceiros e a fornecida não é interação de terceiros.
    • Solicitação inválida. O tipo de membro deve ser um de [tipo de membro permitido] : O tipo de membro fornecido na solicitação não está em um dos tipos permitidos para atualização.
    • Não foi possível encontrar a conversa da interação correspondente Não é possível encontrar o registro de conversa correspondente com o sys_id de interação fornecido.
    • Solicitação inválida. O usuário não é membro da interação fornecida : O sys_id do agente fornecido não é membro da conversa de interação fornecida.

    Tipo de dados: Cadeia de caracteres

    Solicitação de curl

    A solicitação a seguir demonstra como atualizar um usuário do agente para uma função de executante público em uma determinada conversa.

    curl "https://instance.servicenow.com/api/now/conversation/member/{user_id}/update" \ 
--request POST \ 
--header "Accept:application/json" \ 
--header "Content-Type:application/json" \ 
--data "{ 
 \"interaction_id"":\"< interaction_sys_id" >\", 
 \"member_type\":\"public_fulfiller\" 
}" \ 
--user 'username':'password'

    A resposta retorna informações sobre a atualização bem-sucedida para uma função de executante público. Observe que o memberType foi atualizado, mas o campo ativo permanece verdadeiro, indicando que o tipo do agente foi alterado, mas ainda está ativo na conversa.

    {
  "result": {
    "conversation_member": {
      "active": true,
      "memberType": "public_fulfiller",
      "conversation_id": " <conversation_sys_id>"
    },
    "success": true,
    "message": "Request to update agent member type processed successfully."
  }
}