Helpdesk

Visão geral

O HelpDesk é um sistema de tickets projetado para agilizar o suporte ao cliente, organizando e gerenciando consultas de forma eficiente. Com a integração no SquadOS, seus agentes podem listar tickets, agentes, equipes, regras de automação e configurações de conta, além de monitorar assinaturas e webhooks sem sair do fluxo de trabalho do agente.

Site oficial: https://www.helpdesk.com/
Documentação na Composio: docs.composio.dev/toolkits/helpdesk

Autenticação

Esta ferramenta utiliza chave de API (API_KEY) para conectar.

Você vai precisar dos seguintes campos:

Campo	Obrigatório	Descrição
`api_key`	Sim	Token de acesso pessoal (PAT) gerado no Console de Desenvolvedores do LiveChat/HelpDesk.

Como obter a credencial

Acesse o Console de Desenvolvedores usando suas credenciais HelpDesk.
No menu lateral, navegue até Tools → Personal Access Tokens.
Clique em Create new token, selecione o escopo accounts--my:ro (mínimo necessário) e os escopos adicionais de que precisar, e confirme.
Copie o token gerado — ele é exibido apenas uma vez.
Anote também o seu Account ID, exibido no topo da tela do Console; é necessário junto ao token para autenticação básica.

Como conectar no SquadOS

Acesse Ferramentas no menu lateral (/admin/tools).
Abra a aba Disponíveis e procure por Helpdesk.
Clique no card para abrir o modal de detalhes e em Conectar.
Você é levado para a página de conexão segura hospedada pela Composio, onde informa as credenciais obtidas acima.
Ao concluir, você volta para o SquadOS com a conta conectada e a ferramenta disponível para os agentes. (Detalhes do fluxo em Ferramentas da Organização.)

Ações disponíveis

Listar agentes

HELPDESK_LIST_AGENTS

Recupera todos os agentes de suporte (membros da equipe) na conta HelpDesk. Use esta ação para obter a lista completa de agentes com seus detalhes, incluindo: perfis de agentes (nome, e-mail, avatar, cargo), atribuições de função (proprietário, normal, visualizador), associações a equipes, status (ativo ou convidado), configurações de atribuição automática e assinaturas de e-mail. Esta ação não requer parâmetros e retorna todos os agentes da conta. Útil para encontrar IDs de agentes, verificar a composição da equipe ou confirmar permissões.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar respostas prontas

HELPDESK_LIST_CANNED_RESPONSES

Lista as respostas prontas disponíveis na conta. Use quando precisar recuperar todos os modelos de resposta predefinidos para tickets.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar campos personalizados

HELPDESK_LIST_CUSTOM_FIELDS

Lista todos os campos personalizados definidos na conta. Use quando precisar visualizar ou gerenciar campos personalizados. Requer autenticação prévia.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar domínios de e-mail

HELPDESK_LIST_EMAIL_DOMAINS

Lista todos os domínios de e-mail configurados na conta HelpDesk. Retorna uma lista completa incluindo nomes de domínio, status de verificação, registros DNS e flags de configuração. Os domínios de e-mail permitem enviar e receber tickets via endereços de e-mail personalizados. Use esta ação para: obter IDs e nomes de domínio para outras operações da API, verificar o status de configuração e verificação do domínio, visualizar requisitos de configuração DNS e auditar quais domínios estão sendo usados ativamente. Não são necessários parâmetros — retorna todos os domínios de e-mail acessíveis pela conta autenticada.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar licenças

HELPDESK_LIST_LICENSES

Recupera todas as licenças (configurações de conta) para a conta HelpDesk autenticada. Uma licença representa uma conta de cliente e contém informações de assinatura, configurações globais, atribuições padrão de equipe e template, e idiomas detectados. A maioria das contas tem uma licença. Use esta ação para: verificar a configuração e as configurações da conta, obter ID e metadados da conta, visualizar atribuições padrão de equipe e template e inspecionar configurações da empresa e flags de recursos. Não são necessários parâmetros — retorna todas as licenças da conta autenticada.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar endereços de resposta

HELPDESK_LIST_REPLY_ADDRESSES

Lista todos os endereços de resposta configurados na conta HelpDesk. Os endereços de resposta são e-mails usados para receber e responder tickets de suporte. Cada endereço de resposta deve estar associado a um domínio de e-mail verificado e pode ser usado como endereço “De” ao enviar respostas de tickets aos clientes. Use esta ação para: obter todos os endereços de resposta disponíveis e seus status de verificação, recuperar IDs de endereços de resposta para uso em outras operações (ex.: criação de caixas de entrada), verificar quais domínios de e-mail estão sendo usados e auditar a configuração de endereços de resposta. Não são necessários parâmetros — retorna todos os endereços de resposta acessíveis pela conta autenticada.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar regras

HELPDESK_LIST_RULES

Recupera a lista de regras configuradas na conta. Use após autenticação quando precisar de uma visão geral de todas as regras de automação.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar assinaturas

HELPDESK_LIST_SUBSCRIPTIONS

Lista todas as assinaturas de cobrança da conta HelpDesk, incluindo assinaturas ativas, expiradas, canceladas e futuras. As assinaturas representam o plano selecionado (team ou enterprise) e o número de vagas de agentes pagas. Use esta ferramenta para recuperar detalhes de assinaturas incluindo códigos de plano, preços, ciclos de cobrança, períodos de teste e estados de assinatura. Ambos os parâmetros de filtro são opcionais — omita-os para recuperar todas as assinaturas.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`state`	string	Não	Filtra por status da assinatura. Opções: `active` (em uso), `expired` (data de término passada), `canceled` (encerrada manualmente), `future` (ainda não iniciada), `pending` (aguardando ativação). Omita para incluir todos os estados.
`plan_codes`	array	Não	Filtra por códigos de plano específicos. Nomenclatura: `hd-{tier}{duration}m`, onde tier é `team` ou `enterprise` e duration é o período de cobrança em meses (1, 3, 6, 12, 24 ou 36). Exemplos: `hd-team12m` (plano Team, 12 meses), `hd-enterprise6m` (plano Enterprise, 6 meses). Omita para incluir todos os tipos de plano.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar equipes

HELPDESK_LIST_TEAMS

Lista todas as equipes na conta HelpDesk. Retorna uma lista completa de todas as equipes configuradas, incluindo IDs, nomes, configurações, endereços de resposta e configurações de integração. As equipes são unidades organizacionais que agrupam agentes e gerenciam o roteamento de tickets. Use esta ação para: obter IDs de equipes para outras operações da API, recuperar nomes e configurações de equipes, auditar configurações e endereços de resposta de equipes e visualizar configurações de integração. Não são necessários parâmetros — retorna todas as equipes acessíveis pela conta autenticada.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar tickets

HELPDESK_LIST_TICKETS

Lista todos os tickets de um silo especificado com suporte a paginação baseada em cursor. Esta ferramenta recupera tickets do sistema de helpdesk com ordenação e paginação flexíveis. Use quando precisar recuperar tickets para monitoramento, relatórios ou processamento. Principais recursos: recupera tickets do silo especificado (tickets, archive, trash ou spam), suporta paginação baseada em cursor para navegação eficiente em grandes conjuntos de dados, tamanho de página configurável (1–100 tickets por página) e múltiplas opções de ordenação (createdAt, updatedAt, lastMessageAt) em ordem crescente ou decrescente. Casos de uso comuns: obter todos os tickets abertos com parâmetros padrão e silo=tickets; navegar por tickets arquivados com silo=archive; paginar pelos resultados usando next_value e next_id da resposta anterior.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`silo`	string	Não	Silo/pasta de onde listar os tickets. Padrão: `tickets`.
`order`	string	Não	Direção de ordenação (`asc` ou `desc`).
`sortBy`	string	Não	Campo de ordenação (`createdAt`, `updatedAt` ou `lastMessageAt`).
`next.ID`	string	Não	ID do último item na página atual (cursor de avanço).
`prev.ID`	string	Não	ID do primeiro item na página atual (cursor de retorno).
`pageSize`	integer	Não	Número de resultados por página (1–100).
`next.value`	string	Não	Timestamp do último item na página atual (cursor de avanço).
`prev.value`	string	Não	Timestamp do primeiro item na página atual (cursor de retorno).

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar e-mails confiáveis

HELPDESK_LIST_TRUSTED_EMAILS

Recupera a lista de endereços de e-mail ou domínios confiáveis. Use ao gerenciar a lista de permissões (whitelist) de spam após autenticação.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar visualizações

HELPDESK_LIST_VIEWS

Lista as visualizações de agentes. Use quando precisar recuperar visualizações salvas de tickets após autenticação.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Listar webhooks

HELPDESK_LIST_WEBHOOKS

Lista todos os webhooks configurados para a conta HelpDesk. Os webhooks permitem receber notificações em tempo real sobre eventos de tickets (criação, atualizações, mudanças de status, atribuições, etc.) enviadas como requisições HTTP POST para as URLs especificadas. Use esta ação para visualizar todas as configurações de webhook ativas.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.

Visualizar agente

HELPDESK_VIEW_AGENT

Recupera detalhes completos de um agente específico no sistema HelpDesk. Retorna informações completas do agente, incluindo detalhes do perfil, atribuições de função, associações a equipes, status, configurações e assinatura de e-mail. Use esta ação quando precisar de informações detalhadas sobre um agente específico, após obter o ID do agente pela ação HELPDESK_LIST_AGENTS.

Parâmetros de entrada

Nome	Tipo	Obrigatório	Descrição
`agentID`	string	Sim	Identificador único (formato UUID) do agente a recuperar. Obtenha os IDs de agentes pela ação `HELPDESK_LIST_AGENTS`.

Saída

Nome	Tipo	Obrigatório	Descrição
`data`	string	Sim	Dados retornados pela execução da ação.
`error`	string	Não	Mensagem de erro caso a execução tenha falhado.
`successful`	boolean	Sim	Indica se a ação foi executada com sucesso.