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. ![ferramentas.](https://app.digi2b.com/storage/file/8t7jwtk1c1i222rj4ihpvrm1s5iu) **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.