Pular para o conteúdo principal
DocumentationAPI ReferenceVideo Tutorials

Integrações

As integrações estendem os seus agentes de voz, ligando-os a serviços externos. Esta secção cobre todas as integrações disponíveis e como configurá-las.

Integrações Disponíveis​

IntegraçãoFinalidadeEstadoPlanos
Phone NumbersNúmeros de telefone e chamadasDisponívelTodos
SIP TrunkTraga o seu próprio operador (sipgate, Placetel, TENIOS, easybell, Zadarma, Twilio BYO, Telnyx, Custom)DisponívelTodos — requer aprovação de compliance
Google CalendarAgendamento de compromissos via GoogleDisponívelTodos
Outlook CalendarAgendamento de compromissos via Microsoft OutlookDisponívelTodos
eTerminVerificar disponibilidade e marcar/remarcar/cancelar compromissos ao vivo — ver eTerminDisponívelTodos
resmioReservar mesas de restaurante no seu livro de reservas ao vivo — ver resmioDisponívelTodos
HubSpot CRMLer/escrever contactos e negócios a partir do seu agente de vozDisponívelTodos
Servidores MCPTraga o seu próprio servidor de ferramentas compatível com MCP e exponha as suas ferramentas aos agentes — ver Servidores MCPDisponívelTodos
API KeysAcesso de aplicação externaDisponívelTodos
WebhooksNotificações de eventos em tempo realDisponívelTodos
Todos os Planos

As integrações de calendário, SIP, HubSpot, servidores MCP, acesso à API e webhooks estão disponíveis em todos os planos, incluindo Free. O SIP trunking requer uma aprovação de compliance única antes de o assistente de ligação ficar disponível.

Configuração de Número de Telefone​

Os números de telefone permitem que os seus agentes recebam e façam chamadas telefónicas reais.

Passos de Configuração​

  1. Vá a Phone Numbers na barra lateral
  2. Clique em "Buy Number"
  3. Selecione país e tipo de número
  4. Complete a compra
  5. Atribua um agente ao número

Os números são configurados automaticamente e estão prontos a usar após a compra.

Integração com SIP Trunk​

Traga o seu próprio operador SIP — a HANC fala SIP nativamente e encaminha as chamadas inbound para o seu agente de voz (e chamadas outbound de volta pelo seu trunk). Disponível em todos os planos, incluindo Free, após uma aprovação de compliance única.

Operadores Suportados​

A HANC tem adaptadores afinados para os seguintes operadores, mais uma opção genérica para qualquer outro:

OperadorAuto-importar números via APINotas
sipgateSim (Personal Access Token)SIP trunking UE
PlacetelManualVoIP alemão, credenciais Webportal
TENIOSManualSIP europeu
easybellManualOperador alemão, credenciais Kundencenter
ZadarmaSim (chave API opcional)Números globais
Twilio (BYO)SimAccount SID + Auth Token
TelnyxSimSIP e DIDs orientados a API
SIP trunk personalizadoManualQualquer outro fornecedor — forneça host, porta, transporte

Aprovação de Compliance​

As ligações de operador SIP partilham o mesmo fluxo de compliance das campanhas outbound. Até a sua conta ser aprovada, o botão Connect SIP abre um modal de vitrine listando todos os operadores suportados com um CTA mailto:support@hanc.ai. A aprovação é geralmente no mesmo dia útil.

Passos de Configuração (após aprovação)​

  1. Vá a Phone Numbers → Connect SIP.
  2. Escolha o seu operador.
  3. Introduza as credenciais SIP (e chave/segredo de API opcional se o seu operador suporta auto-importação).
  4. Para SIP Personalizado, forneça também host, porta (padrão 5060) e transporte (UDP / TCP / TLS).
  5. Clique em Connect — a HANC regista o seu utilizador SIP e, onde suportado, lista os seus números de telefone.
  6. Selecione os números a importar (ou adicione manualmente por E.164).
  7. Atribua um agente inbound e/ou outbound a cada número.

Quando Usar SIP vs. Comprar um Número​

CenárioRecomendação
Novo no serviço telefónicoCompre números através da HANC (mais simples — sem passo de compliance)
PBX existente ou contrato com operadorLigue via SIP — mantenha o seu número
Telefonia empresarial com requisitos rigorosos de operadorSIP para controlo total
Várias regiões / pools de númerosSIP para flexibilidade

Integração com Google Calendar​

Ligue o Google Calendar para permitir que os seus agentes de voz verifiquem disponibilidade e marquem compromissos durante chamadas.

Passos de Configuração​

  1. Vá a Integration → Calendars
  2. Clique em "Connect Google Calendar"
  3. Inicie sessão na Google
  4. Autorize o acesso da Hanc.AI

Permissões pedidas:

  • Ver eventos do calendário (para verificar disponibilidade)
  • Criar eventos do calendário (para marcar compromissos)

Configuração do Calendário​

Após ligar, configure a ferramenta de calendário no seu agente:

DefiniçãoDescrição
calendar_idQue Google Calendar usar para agendamento
timezoneFuso horário para agendamento de compromissos (ex.: Europe/Vienna)
work_hoursHoras disponíveis para marcação (ex.: segunda a sexta 9:00-18:00)
slot_durationDuração padrão do compromisso (ex.: 30 minutos)
bufferTempo de margem entre compromissos (ex.: 15 minutos)

Uso do Calendário em Agentes​

Uma vez ligado e configurado, os agentes podem:

  • Verificar disponibilidade para datas e horas específicas
  • Marcar compromissos automaticamente
  • Respeitar horas de trabalho e tempos de margem
  • Lidar com pedidos de remarcação

Conversa de exemplo:

Cliente: "Posso marcar uma consulta para terça-feira às 15h?"

Agente: [Verifica calendário]
       "Sim, terça-feira às 15h está disponível.
        Pode dar-me o seu nome para concluir a marcação?"

Integração com Outlook Calendar​

Ligue o Microsoft Outlook Calendar para permitir agendamento de compromissos através dos seus agentes de voz.

Passos de Configuração​

  1. Vá a Integration → Calendars
  2. Clique em "Connect Outlook Calendar"
  3. Inicie sessão com a sua conta Microsoft
  4. Autorize o acesso da Hanc.AI

Permissões pedidas:

  • Ver eventos do calendário (para verificar disponibilidade)
  • Criar eventos do calendário (para marcar compromissos)

Configuração do Calendário​

Após ligar, configure a ferramenta de calendário no seu agente:

DefiniçãoDescrição
CalendarQue calendário Outlook usar para agendamento
TimezoneFuso horário para agendamento de compromissos (ex.: Europe/Vienna)
Work HoursHoras disponíveis para marcação (ex.: segunda a sexta 9:00-18:00)
Slot DurationDuração padrão do compromisso (ex.: 30 minutos)
BufferTempo de margem entre compromissos (ex.: 15 minutos)

Diferenças do Google Calendar​

Ambas as integrações de calendário funcionam de forma idêntica do ponto de vista do agente. A única diferença é o processo de início de sessão — escolha o serviço de calendário que já usa.

dica

Pode ligar os calendários Google e Outlook ao mesmo tempo, mas cada agente só pode usar uma ferramenta de calendário.

Cancelar Compromissos​

Os interlocutores que marcaram um compromisso recebem um link de cancelamento. Podem cancelar o seu compromisso diretamente sem precisar de voltar a ligar.

Marcação de Compromissos eTermin​

Ligue o eTermin para que os seus agentes possam verificar disponibilidade e marcar, remarcar ou cancelar compromissos ao vivo na chamada, diretamente nos seus calendários e serviços eTermin — com proteção integrada contra dupla marcação. Use o eTermin em vez de um calendário simples quando os seus compromissos já vivem no eTermin e oferece serviços distintos com as suas próprias durações e regras.

Veja a página completa do eTermin para passos de ligação, configuração por agente e proteção contra dupla marcação.

Reservas de Mesa resmio​

Ligue o resmio para que os seus agentes possam reservar mesas de restaurante diretamente no seu livro de reservas durante uma chamada — verificando disponibilidade real por hora e número de pessoas, e tratando de remarcações e cancelamentos. Use o resmio quando o seu restaurante já aceita reservas através dele.

Veja a página completa do resmio para passos de ligação e detalhes.

Atuar Através de Contas Ligadas em Workflows​

Para além das ferramentas sempre ativas que um agente usa durante uma chamada ao vivo, os workflows têm um passo Integration dedicado (adicionado na v2.8). Coloque um passo Integration num workflow para que este atue através de uma conta Google Calendar, Outlook ou HubSpot ligada num único passo — por exemplo, criar um evento de calendário ou atualizar um negócio HubSpot como parte de um fluxo automatizado maior. O passo usa as mesmas ligações ao nível da conta que configura nesta página, por isso não há nada extra a autorizar.

Integração com HubSpot CRM​

Ligue o seu workspace HubSpot para que os seus agentes de voz possam ler e escrever contactos e negócios durante a chamada, e para que o CRM integrado da HANC possa espelhar os seus pipelines HubSpot.

O Que Permite​

  • Ferramenta ao vivo — HubSpot CRM na aba Actions do agente. O agente pode corresponder o interlocutor a um contacto HubSpot por telefone, obter a etapa do negócio e atualizar propriedades a partir da conversa ao vivo. Veja Ações e Ferramentas.
  • Espelhamento de pipeline no CRM da HANC. As suas etapas de negócio HubSpot aparecem no kanban Deals para que possa ver chamadas e contexto HubSpot lado a lado.
  • Toggle de IA por pipeline — decida em quais pipelines HubSpot a IA pode atuar; tudo o resto fica só de leitura.

Passos de Configuração​

  1. Abra a página Integrations e clique em Connect HubSpot.
  2. Autorize a HANC na sua conta HubSpot.
  3. Escolha quais pipelines devem ser espelhados (visíveis em definições CRM → Pipeline) e quais devem permitir atualizações de etapa pelo agente.
  4. Adicione a ferramenta HubSpot CRM a qualquer agente que deva tocar no HubSpot durante a chamada.
dica

Não tem de usar o HubSpot para usar o CRM da HANC. O CRM integrado funciona de forma autónoma — a integração HubSpot é puramente para organizações que já vivem no HubSpot e querem ambos os mundos sincronizados.

Servidores MCP​

O Model Context Protocol (MCP) é um padrão aberto para ligar assistentes de IA a ferramentas externas. Se executa um servidor compatível com MCP, pode registá-lo uma vez na página de Integração e ter os seus agentes a chamar as suas ferramentas a meio da conversa.

Passos de Configuração (visão geral)​

  1. Vá a Integration → MCP servers.
  2. Clique em Connect MCP server, introduza um rótulo e o URL HTTPS do seu servidor, escolha autenticação (None ou Bearer token), e guarde.
  3. Abra o agente que pretende usar as ferramentas, vá a Actions → Add Action → MCP servers, e ative as ligações que este agente deve usar.

O agente irá descobrir e usar as ferramentas do servidor no início de cada chamada.

Veja a página completa de Servidores MCP para configuração detalhada, resolução de problemas e como o MCP se encaixa ao lado das ferramentas integradas.

Chaves de API​

Gere chaves de API para integrar a Hanc.AI com as suas próprias aplicações.

Criar uma Chave de API​

Pode criar até 3 chaves de API por utilizador.

  1. Vá a Integration → API Keys
  2. Clique em "Create API Key"
  3. Introduza um nome (ex.: "CRM Integration")
  4. Defina permissões (read, write, admin)
  5. Copie a chave imediatamente (mostrada apenas uma vez)

Segurança da Chave de API​

Importante
  • Armazene chaves em segurança (variáveis de ambiente, secrets manager)
  • Nunca faça commit das chaves em controlo de versão
  • Faça rotação das chaves periodicamente
  • Elimine chaves não usadas

Usar Chaves de API​

Incluir em pedidos de API:

curl -X GET "https://api.hanc.ai/v1/agent/list" \
  -H "x-api-key: YOUR_API_KEY"

Permissões de Chave de API​

PermissãoAcesso
ReadVer agentes, chamadas, analítica
WriteCriar/modificar agentes, carregar KB
AdminTodas as operações, eliminar, definições

Endpoints disponíveis​

A lista completa de endpoints da API, agrupados por recurso (Calls, Agents, Knowledge Base, Phone Numbers, Voices, Subscription, Customers, Workspaces) vive na sua própria página:

→ Referência Completa da API

Webhooks​

Configure webhooks para receber notificações em tempo real sobre eventos na sua conta Hanc.AI.

Configuração​

  1. Vá a Integration → Webhooks
  2. Introduza o URL do seu endpoint de webhook
  3. Selecione os eventos para subscrever
  4. Guarde a configuração

Os webhooks enviam pedidos HTTP POST para o seu endpoint com dados do evento em formato JSON.

Ações Pós-Chamada​

As ações pós-chamada são acionadas automaticamente após uma conversa de agente de voz terminar. Configure-as em agentes individuais.

Tipos de Ação Disponíveis​

AçãoDescrição
EmailEnviar um resumo por email da chamada (para proprietário do negócio, cliente ou ambos)
SMSEnviar uma notificação SMS após a chamada
WhatsAppEnviar uma mensagem WhatsApp após a chamada
API CallFazer um pedido HTTP para um endpoint externo com dados da chamada

Configuração​

  1. Vá a Voice Agents → selecione o seu agente
  2. Abra a aba Actions
  3. Clique em "Add Action"
  4. Selecione tipo de ação e configure:
    • Trigger: Quando a ação é acionada (ex.: após cada chamada, apenas em desfechos específicos)
    • Recipients: Quem recebe a notificação
    • Content: Template de mensagem com variáveis de dados da chamada

Integrações Personalizadas​

Usar a API​

Construa integrações personalizadas usando a API Hanc.AI:

URL Base: https://api.hanc.ai/v1
Autenticação: Bearer token (chave de API)
Formato: JSON

Documentação da API​

Veja a Referência da API para a lista completa de endpoints disponíveis.

Boas Práticas de Integração​

Segurança​

  • Armazene credenciais em segurança
  • Faça rotação das chaves de API regularmente
  • Limite permissões ao mínimo necessário

Fiabilidade​

  • Registe todos os eventos de integração
  • Monitorize a saúde da integração

Testes​

  • Teste integrações em staging primeiro
  • Verifique o fluxo de dados em ambas as direções
  • Teste cenários de erro
  • Documente a configuração da integração

Resolução de Problemas​

A integração não liga​

  1. Verifique se as credenciais estão corretas
  2. Procure erros de escrita
  3. Garanta que a conta terceira está ativa
  4. Tente desligar e voltar a ligar

O calendário não está a sincronizar​

  1. Volte a autorizar o acesso ao calendário
  2. Verifique as permissões do calendário
  3. Verifique se o calendário selecionado está correto
  4. Verifique se há atrasos de sincronização (até 5 minutos)

Tópicos Relacionados​