Ir para a navegação
Integrações

Webhooks

Dê à sua recepcionista ferramentas personalizadas que chamam seus endpoints HTTP.

A integração com a Ferramenta de Webhook expõe seus endpoints HTTP como ferramentas que sua recepcionista ou assistente comercial pode chamar durante as conversas. A IA decide quando chamar o endpoint com base na conversa.

Como funcionam as ferramentas de webhook

Ao criar uma ferramenta de webhook, você define:

  1. Um endpoint HTTP a ser chamado.
  2. Uma descrição do que ela faz, para que a IA saiba quando usá-la.
  3. Parâmetros que a IA deve coletar na conversa.

Durante uma chamada, quando a conversa corresponde à finalidade da ferramenta, sua recepcionista coleta os parâmetros, chama o endpoint e usa a resposta para continuar a conversa.

Como criar uma ferramenta de webhook

Acesse Integrações, selecione Adicionar integração e escolha Ferramenta de Webhook. Configure os campos abaixo e selecione Ativar. Você pode adicionar várias ferramentas de webhook.

CampoDescrição
NomeNome da ferramenta que a IA vê, por exemplo, check_order_status
DescriçãoQuando e por que usar esta ferramenta
MétodoGET, POST, PUT, PATCH ou DELETE
URLSeu endpoint HTTP
Tempo limite da resposta (segundos)Quanto tempo esperar pelo seu servidor: de 5 a 120 segundos; o padrão é 20
Atribuir a agentesRecepcionista, Agente assistente ou ambos
Desativar interrupçõesImpede que a pessoa que liga interrompa enquanto a ferramenta é executada
Cabeçalhos da solicitaçãoCabeçalhos opcionais enviados com todas as solicitações. O Tipo é Valor ou Segredo. Um Segredo é armazenado de forma criptografada e nunca mais é exibido. Um cabeçalho trazido do ElevenAgents pode mostrar Variável de ambiente ou Variável, com uma observação de que ele é definido na plataforma de agentes.
Parâmetros de caminhoExibidos quando a URL contém marcadores entre chaves, como /orders/{order_id}. Edite a URL para adicionar ou remover um.
Parâmetros do corpoParâmetros enviados como corpo de solicitação JSON, exibidos para POST, PUT e PATCH. Eles podem ser objetos e listas.
Parâmetros de consultaParâmetros enviados como strings de consulta da URL. Cada um tem um único valor.

Parâmetros

Cada parâmetro tem:

  • Chave: o nome do campo. Use letras, números, sublinhados, hífens, @ e pontos simples. Colchetes não são permitidos, portanto, uma API que espera chaves como filter[name] não pode ser chamada diretamente.
  • Tipo: string, number, integer ou boolean. Os parâmetros do corpo também podem ser object ou array.
  • Valor: Da conversa, preenchido pela IA, ou um Valor fixo, enviado em todas as solicitações.
  • Descrição: qual valor a IA deve extrair da conversa.
  • Obrigatório: se a IA precisa coletá-lo antes de chamar.

Use integer para números inteiros, como contagens, IDs e indicadores 0/1. Um number fixo é enviado com ponto decimal, então 1 chega como 1.0, o que algumas APIs rejeitam.

Um parâmetro configurado no ElevenAgents para receber seu valor de uma variável é exibido como somente leitura, com uma observação de que ele é definido na plataforma de agentes. Ele é enviado conforme configurado lá.

Objetos e listas

Muitas APIs esperam campos relacionados agrupados, como um contato com uma lista de números de telefone. Os parâmetros do corpo podem enviar isto:

  • Um object agrupa campos. Selecione Adicionar campo para adicionar cada um; todos os campos têm sua própria chave, tipo e valor.
  • Um array é uma lista. Em Cada item, escolha o tipo dos itens. Uma lista de objetos permite que a IA envie várias entradas com a mesma estrutura, como uma para cada número de telefone.

Os campos podem ser aninhados em até cinco níveis. Um objeto ou uma lista sempre vem da conversa, mas um campo dentro de um objeto pode ter um Valor fixo, como um rótulo ou um ID que nunca muda.

Por exemplo, estes parâmetros de corpo:

  • name: string, da conversa
  • phones: array, em que cada item é um objeto com dois campos:
    • number: string, da conversa
    • label: string, fixo como mobile
  • source: objeto com um campo, channel: string, fixo como phone

enviam um corpo de solicitação como este:

{
  "name": "Jane Doe",
  "phones": [{ "number": "+15551234567", "label": "mobile" }],
  "source": { "channel": "phone" }
}

Casos de uso

CenárioDescriçãoMétodo
Consulta de CRMConsulta informações do cliente no seu sistemaGET
Verificação de estoqueVerifica a disponibilidade do produto em tempo realGET
Captura de leadsEnvia os dados de quem liga para seu sistema de marketingPOST
Criação de ticketCria um ticket de suporte durante a chamadaPOST
Cotação de preçoCalcula uma cotação personalizada com base nas necessidades de quem ligaPOST

Exemplo

Uma empresa de encanamento cria uma ferramenta de webhook:

  • Nome: check_service_area
  • Descrição: “Verifique se atendemos o CEP de quem liga e qual é o próximo horário disponível.”
  • URL: https://api.mybusiness.com/check-area
  • Método: POST
  • Cabeçalhos da solicitação: Authorization definido como a chave de API da empresa, como um Segredo
  • Parâmetros do corpo: zip_code (string, obrigatório), service_type (string, obrigatório)

Quando alguém liga perguntando sobre atendimento na sua região, a recepcionista coleta o CEP, chama o webhook e informa o resultado.

As ferramentas de webhook estão disponíveis em todos os planos.