Como configurar ferramentas personalizadas da IAra

Use este guia quando você precisar configurar, entender ou validar Como configurar ferramentas personalizadas da IAra na IAra.

Antes de começar na IAra

• Confirme que seu usuário tem permissão para acessar a área citada no artigo.
• Faça a configuração primeiro em um cenário de teste, sempre que o recurso afetar atendimentos reais.
• Se o fluxo envolver WhatsApp, Meta, Twilio, e-mail, domínio, SAML, API ou outro provedor externo, confirme as credenciais e permissões antes de iniciar.

Guia detalhado

As ferramentas personalizadas permitem que a IAra chame suas APIs externas durante as conversas — para que ele possa verificar o status da garantia, verificar a cobertura do serviço ou buscar dados de seus próprios serviços sem entregá-los a um agente humano.

Quando um cliente faz uma pergunta, a IAra extrai os valores relevantes da conversa, insere-os na sua solicitação de API e usa a resposta para formar sua resposta.

As ferramentas personalizadas estão disponíveis no plano Business e superiores.

Criando uma ferramenta

Navegue até IAra -> Ferramentas e clique em Criar uma nova ferramenta.\

Na tela: As ferramentas do assistente ficam na área de Ferramentas do Capitão.

Nome da ferramenta — Um nome curto como "Pesquisa de garantia" ou "Verificação da área de serviço" (máximo de 55 caracteres).

Descrição — Diga a IAra quando usar esta ferramenta. Este é o campo mais importante. Escreva como se estivesse informando um agente de suporte: “Verifica o status da garantia de um produto pelo número de série”. Descrições vagas como "API de garantia" farão com que a IAra perca oportunidades de usar a ferramenta.

Método — Escolha GET (para buscar dados) ou POST (para enviar dados).

URL do terminal — o URL da sua API. Use {{ nome_do_parâmetro }} para inserir valores extraídos da conversa:

https://api.suaempresa.com/v1/warranty/{{ serial_number }}

A URL deve usar HTTPS, deve ser um nome de host (não um endereço IP) e não pode apontar para localhost ou redes privadas.

Autenticação — Escolha como sua API autentica solicitações:

• Nenhum — Sem autenticação

• Bearer Token — Envia seu token no cabeçalho Authorization

• Autenticação Básica — Envia um nome de usuário e senha

• API Key — Envia um nome e valor de cabeçalho personalizado (por exemplo, X-API-Key)

As credenciais de autenticação só são visíveis para administradores de conta.

Parâmetros — Defina o que a IAra deve extrair da mensagem do cliente. Cada parâmetro precisa de um nome, tipo e descrição. Por exemplo: serial_number (String) — "O número de série do produto, encontrado na parte traseira do dispositivo."

Modelo de solicitação (somente POST) — Um modelo de corpo JSON usando sintaxe Liquid.

Modelo de resposta — Controla o que a IAra vê na resposta da sua API. Se deixado em branco, a IAra recebe o JSON bruto.

Use Liquid para extrair campos relevantes, por exemplo: Serial {{response.serial_number }}: {{response.warranty_status }}. Expira em: {{response.expiry_date}}.

Use response para acessar o corpo JSON analisado. Os modelos de resposta ajudam a IAra a se concentrar nos dados relevantes e a evitar campos internos, como IDs de banco de dados ou informações de depuração.

Testando sua ferramenta

Clique em Testar conexão antes de salvar para verificar se seu endpoint está acessível. O teste relata o código de status HTTP.\

Se o teste falhar, verifique o seguinte:

• 401 Unauthorized — Suas credenciais de autenticação estão incorretas. Verifique novamente seu token de portador, chave de API ou nome de usuário/senha.

• 403 Proibido — Sua API está rejeitando a solicitação. Se você precisar de verificação de identidade, observe que as solicitações de teste não incluem cabeçalhos de contato.

• 404 Not Found — O URL do endpoint está errado. Verifique o caminho e certifique-se de que sua API esteja em execução.

• Tempo limite — Sua API demorou muito para responder. As ferramentas personalizadas têm um tempo limite de 30 segundos; certifique-se de que seu endpoint responda nessa janela

Contexto enviado com cada chamada de ferramenta

Quando a IAra chama sua API, ele inclui cabeçalhos de metadados para que seu backend conheça o contexto:

• X-IAra-Account-Id — ID da sua conta

• X-IAra-Conversa-Id — O ID da conversa

• X-IAra-Contact-Email — O e-mail do cliente (se disponível)

• X-IAra-Contact-Caixa de entrada-Verified — Se a identidade do cliente foi verificada pelo HMAC

• X-IAra-Assistant-Id — O assistente do assistente de IA fazendo a ligação

• X-IAra-Tool-Slug — O identificador interno da ferramenta

• X-IAra-Contact-Id — O ID de contato do cliente

• X-IAra-Contact-Phone — O número de telefone do cliente (se disponível)

• X-IAra-Conversa-Display-Id — O número de exibição da conversa

Você pode usar esses cabeçalhos para procurar a pessoa atendida em seu próprio sistema, registrar quais conversas acionaram chamadas de API e verificar a autenticidade da solicitação.

Segurança

Proteções integradas:

*Todos os endpoints devem usar HTTPS

• Solicitações para intervalos de IP privados, localhost e domínios .local são bloqueadas

• Redirecionamentos HTTP não são seguidos

• As respostas são limitadas a 1 MB

• As credenciais de autenticação são visíveis apenas para administradores

Verificação de identidade: se sua ferramenta retornar dados específicos do cliente (pedidos, faturamento, detalhes da conta), sua API deverá verificar o cabeçalho X-IAra-Contact-Caixa de entrada-Verified. Sem a verificação HMAC habilitada em sua caixa de entrada, um visitante pode definir qualquer endereço de e-mail no widget de chat. Retorne dados confidenciais apenas quando este cabeçalho for true. Para ferramentas que retornam dados públicos esta verificação não é necessária.

Injeção de prompt: se sua API retornar conteúdo gerado pelo usuário (avaliações, postagens em fóruns), textos maliciosos poderão influenciar o comportamento da IAra. Use modelos de resposta para extrair apenas campos estruturados e limpar o conteúdo da sua API.

Limites

• Máximo de ferramentas por conta — 15

• Recomendado — 10 ou menos. Um aviso aparece acima de 10; mais ferramentas tornam mais difícil para a IAra escolher a ferramenta certa.

• Comprimento do nome da ferramenta — 55 caracteres

• Tamanho da resposta — 1 MB no máximo

• Tempo limite da solicitação — 30 segundos

Quando usar ferramentas personalizadas

As ferramentas personalizadas são mais adequadas para pesquisas estruturadas com entradas previsíveis – verificando o status do sistema, buscando programações ou procurando registros por ID. Se você já tem uma integraçãa IAra dedicada para seu caso de uso (por exemplo, Shopify para comércio eletrônico), use-a - integrações dedicadas lidam com pesquisa, correspondência difusa e sincronização de dados de forma mais confiável do que uma única chamada de API.

Exemplos

Pesquisa de garantia

Quando um cliente pergunta se seu produto ainda está na garantia, a IAra pode verificar usando o número de série.

• Nome da ferramenta: Pesquisa de garantia

• Descrição: Verifica o status da garantia de um produto pelo seu número de série. Use quando um cliente perguntar se seu produto está coberto, quando a garantia expira ou que tipo de cobertura ele possui.

Verificação da área de serviço

Para empresas que operam em regiões específicas – os clientes perguntam se o serviço está disponível em sua localidade.

• Nome da ferramenta: Verificação da área de serviço

• Descrição: Verifica se o serviço ou entrega está disponível em uma área específica através do CEP ou nome da cidade do cliente.

As ferramentas personalizadas funcionam melhor quando as entradas são diretas e a resposta da API é previsível – verificações de status, pesquisas e outras consultas estruturadas são uma ótima opção.

---

Como validar na IAra

1. Execute o fluxo em uma conta ou conversa de teste.
2. Confirme se o resultado aparece para o agente, gestor ou cliente exatamente como esperado.
3. Revise se o nome da caixa, time, etiqueta, assistente ou integração está claro para o restante da equipe.

Problemas comuns

• Usuário sem permissão para acessar a configuração.
• Nome de tela diferente entre versões ou contas.
• Recurso dependente de plano, provedor externo ou habilitação pela Digi2B.
• Falta de teste em conversa realista antes de liberar para a equipe.

Checklist final

• [ ] Configuração revisada por um administrador.
• [ ] Teste realizado com dado ou conversa controlada.
• [ ] Impacto para agentes e gestores entendido.
• [ ] Artigos relacionados revisados para evitar links quebrados.