Guias

Ferramentas HTTP: liga o agente à tua API

Uma ferramenta HTTP é um pedido que o agente faz à tua API durante a chamada. O agente decide quando o fazer, com base na conversa. Tu defines o endereço, o método, os cabeçalhos e os dados.

Serve para consultar uma encomenda, criar um pedido de apoio ou atualizar um registo no teu software. Esta página diz só o que a Atendia faz hoje.

Configurar com o Construtor

O Construtor da consola pode criar e editar uma ferramenta HTTP deste agente através de um cartão. Tu revês e aplicas.

  • Pergunta o que precisa e que programa já usas, e propõe a forma mais fácil de ligar que funcione: a ligação pronta da Atendia, se existir, depois o Make (ou o n8n, se já o usas), depois uma ferramenta HTTP direta.
  • Lê a documentação pública do programa e preenche o cartão. O endereço vem do que escreveste na conversa ou de uma página dessa documentação. Explica como usar a ferramenta, com os passos deste guia.
  • Testa sozinho, sem clique, uma ferramenta que só lê (pedido GET) e não precisa de chave. Vê só um resumo da resposta: a forma, os números e as mensagens de erro curtas.
  • Preenche sozinho os valores do sistema, de uma lista fechada: o id da chamada, o canal, o id do agente, a data e a hora, no fuso do agente.

O que fica contigo:

  • O endereço, quando não vem da conversa nem da documentação.
  • Os valores dos cabeçalhos e os valores fixos (campos secretos no cartão).
  • Os testes que precisam de chave: carregas em «Experimentar» no cartão. Um pedido que escreve dados não se experimenta no cartão; testa-o depois em «Ferramentas», na página do agente. A assinatura dos pedidos fica em «Definições».
  • As variáveis dinâmicas com valores (separador Ferramentas).

O pedido

  • O endereço tem de começar por https://. Com http://, o pedido é recusado quando o agente o tenta fazer.
  • Só chega a destinos públicos. Endereços locais ou privados são recusados, tal como endereços com utilizador e palavra-passe.
  • Os redirecionamentos não são seguidos. Se a tua API responder com um 3xx, o pedido falha. Usa o endereço final.
  • Por omissão, a Atendia envia Accept: application/json. Quando há corpo, envia também Content-Type: application/json. Podes trocar os dois nos cabeçalhos da ferramenta; escreve o nome tal como aqui, com as maiúsculas.
  • Os cabeçalhos Host, Content-Length, Transfer-Encoding, Connection, Upgrade e Proxy-* não são aceites.
  • Guarda chaves e tokens como segredos (menu «Segredos»). Ficam encriptados e a consola não os volta a mostrar. Se a tua API devolver o valor de um segredo, a Atendia troca-o por [REDACTED] antes de o agente o ler.
  • Os parâmetros vão na query (?nome=valor), no caminho (/encomendas/{numero}) ou no corpo JSON. O endereço não pode mudar de domínio por causa de um parâmetro do caminho.
  • Num GET o corpo não é enviado. O corpo é sempre JSON.
  • Cada parâmetro do corpo pode ter uma posição no JSON, por exemplo cliente.telefone. Sem posição, o nome do parâmetro é a chave, no primeiro nível. Ver «Caminhos».
  • Num pedido que não é GET, a opção «Confirmar antes de enviar» faz o agente dizer os dados a quem liga e só enviar o pedido depois de a pessoa confirmar. Uma ferramenta nova feita pelo Construtor vem com ela ligada. Num pedido que só consulta dados, podes desligá-la.

Os dados do pedido

Cada parâmetro tem um tipo de valor:

  • «Pedido ao modelo» (LLM Prompt): o agente preenche o valor a partir da conversa. É o único tipo que o agente vê.
  • «Valor estático» (Static Value): o mesmo valor em todos os pedidos. A Atendia guarda-o cifrado. Quem pode editar a ferramenta continua a vê-lo.
  • «Variável dinâmica» (Dynamic Variable): o valor de uma variável dinâmica da ferramenta ou da chamada.
  • Cada parâmetro é texto, número ou booleano. Podes limitar os valores permitidos e marcar o parâmetro como obrigatório. Um parâmetro opcional sem valor não é enviado.
  • system__contact_number é uma variável reservada. A Atendia preenche-a com o número de telefone do contacto da chamada. O agente não a escolhe nem a pode alterar. Se a Atendia não conseguir confirmar o contacto, o pedido não sai.

Privacidade: o número do contacto é um dado pessoal e vai para a tua API. Usa-o só se a tua API precisar dele e o puder receber.

Variáveis do sistema

A Atendia preenche estas variáveis no servidor. O agente não as escolhe nem as altera. Usa-as num parâmetro do tipo «Variável dinâmica», tal como system__contact_number.

  • system__call_id: o identificador da chamada.
  • system__call_channel: inbound (chamada recebida), outbound (chamada feita pela Atendia), widget, preview (pré-visualização na consola) ou test. Se a Atendia não conseguir saber a origem, a variável fica sem valor e um parâmetro obrigatório falha.
  • system__agent_id: o identificador do agente.
  • system__now: data e hora no fuso do agente, em ISO 8601 com o desvio, por exemplo 2026-11-03T14:30:05+00:00.
  • system__date: a data, AAAA-MM-DD. system__time: a hora, HH:MM. Poupam-te formatar system__now no teu lado.
  • system__timezone: o fuso do agente (nome IANA), por exemplo Europe/Lisbon. Se o fuso do agente for inválido, a Atendia usa Europe/Lisbon.
  • No teste da consola não há chamada nem agente. Os valores são de teste: system__call_id é test_ e um identificador aleatório, o canal é test, system__agent_id é test_agent e o fuso é Europe/Lisbon. A hora é a do momento do teste.

Tempos e tamanhos

  • Tempo limite do pedido: de 1 a 300 segundos. Por omissão, 30.
  • A resposta da tua API pode ter até 256 000 bytes. Acima disso, o pedido falha. O corpo que a Atendia envia tem o mesmo limite.
  • O agente lê até 4000 caracteres do resultado, que tem a forma {"status": 200, "data": ...}. A conta é feita depois de escolheres os campos da resposta, se escolheres algum.
  • Acima de 4000 caracteres, o agente recebe {"truncated": true, "data": "..."} com o texto cortado. Escolhe campos para a resposta caber.
  • Campos com nomes como token, password, secret, cookie ou authorization chegam ao agente como [REDACTED]. Números que parecem cartões de pagamento também são escondidos.
  • Uma resposta que não é JSON é lida como texto. Uma resposta vazia conta como {}.

Respostas e erros

O agente nunca vê o corpo de um erro da tua API. Ouve uma frase fixa, conforme o caso:

O que aconteceO que o agente ouve
A tua API responde 200 a 299Recebe o resultado.
Responde 3xx (redirecionamento)O serviço redirecionou o pedido e o redirecionamento não foi seguido.
Responde 401 ou 403O serviço recusou a autenticação.
Responde 404O serviço não encontrou o recurso pedido.
Responde 429O serviço limitou os pedidos por agora. Aguarda antes de tentar de novo.
Responde outro 4xxO serviço recusou os dados do pedido.
Responde 5xxO serviço devolveu um erro. Não repete sozinho; diz que a confirmação está pendente.
Não responde dentro do tempo limiteO pedido excedeu o tempo limite. Não repete sozinho; diz que a confirmação está pendente.
A ligação falha a meioA ligação falhou. Não repete sozinho; diz que a confirmação está pendente.
A resposta passa os 256 000 bytesA resposta excedeu o limite. Não repete sozinho; diz que a confirmação está pendente.
O destino é recusado, ou o nome do servidor não existeO destino não está autorizado, ou não foi possível localizá-lo. O pedido não foi enviado.
Falta um parâmetro obrigatório, ou um valor não é permitidoOs dados enviados não são válidos. O pedido não foi enviado.

Escritas e repetições

Tudo o que não é GET conta como escrita. Durante a mesma chamada, a Atendia não volta a enviar a mesma escrita com os mesmos dados. Se o agente a pedir outra vez, ouve que já foi feita, ou que ainda está pendente.

Se mudares um dado, já é outro pedido. Se a primeira ficou por confirmar, o agente também não a repete.

Do lado da tua API

  • Responde 2xx só quando o trabalho está feito.
  • Usa códigos diferentes para erros diferentes (401, 404, 429, 5xx). É o código que decide o que o agente ouve.
  • Responde depressa. Uma escrita que demora mais do que o tempo limite deixa o resultado por confirmar.
  • Devolve só o que o agente precisa, ou escolhe campos na ferramenta.
  • Quando a ferramenta deixa de funcionar nas chamadas reais, os proprietários da organização recebem um e-mail: logo depois de uma chave recusada (401 ou 403), ou à terceira falha seguida de rede ou do servidor (5xx). Recebem também um, uma só vez, quando a chave caduca nos próximos 7 dias. No máximo, um e-mail por ferramenta e por dia. Os testes e as respostas 404 não contam.

Assinatura dos pedidos

A Atendia pode assinar os pedidos das ferramentas HTTP e o webhook pós-chamada. Assim, a tua API sabe que o pedido veio da Atendia. A assinatura segue o padrão Standard Webhooks, que tem bibliotecas oficiais.

  • É opcional e é por organização: um segredo serve todas as ferramentas e o webhook pós-chamada. Sem segredo, os pedidos saem como antes, sem assinatura.
  • O segredo começa por whsec_. Cria-o na consola, em «Definições» → «Assinatura dos pedidos». As chaves API não o podem criar. É mostrado uma só vez; guarda-o como segredo no teu sistema.
  • Se o perderes, usa «Criar segredo novo»: o novo substitui-o (ver «Trocar o segredo»).

O que chega

  • webhook-id: o identificador do pedido (ver «Id do pedido e chave contra duplicados»).
  • webhook-timestamp: a hora do envio, em segundos Unix.
  • webhook-signature: v1, e uma assinatura em base64. Durante uma troca de segredo vêm duas, separadas por um espaço.
  • O que se assina é webhook-id, um ponto, webhook-timestamp, um ponto e o corpo, exatamente como foi enviado. Num pedido sem corpo (um GET), o corpo é texto vazio. O algoritmo é HMAC-SHA256, com a chave igual ao base64 descodificado do que vem depois de whsec_.
  • O endereço e os outros cabeçalhos não são assinados.

Como verificar

  1. Lê o corpo como texto, tal como chegou, antes de o converter para JSON. Um corpo reescrito já não bate com a assinatura.
  2. Aceita só pedidos com a hora a menos de 5 minutos de diferença (para cada lado). É a tolerância das bibliotecas oficiais.
  3. Confirma o início do webhook-id. Numa ferramenta, é atd_tool_ e o id da tua ferramenta, seguido de _. No webhook pós-chamada, é atd_postcall_ e o id do agente, seguido de _. Sem isto, um pedido assinado para outra ferramenta da mesma organização também passava. O id da ferramenta aparece na consola.
  4. Se a verificação falhar, responde 401 e não faças nada com o pedido.
  5. Começa por aceitar também pedidos sem assinatura, e regista-os. Só quando vires os pedidos a chegar assinados passa a recusar os que não trazem assinatura.
  6. As bibliotecas leem o corpo como JSON. Num pedido sem corpo (GET), usa o exemplo à mão.

Exemplos

Os exemplos em Node e Python foram corridos contra pedidos assinados pelo código da Atendia: aceitam um pedido válido e recusam um corpo alterado, uma hora fora da tolerância, outro segredo e o id de outra ferramenta. Instala a biblioteca com npm install standardwebhooks ou pip install standardwebhooks.

Node, com a biblioteca

javascript
import { Webhook } from "standardwebhooks";

// The whsec_... secret, shown once when you created it.
const webhook = new Webhook(process.env.ATENDIA_SIGNING_SECRET);

// rawBody: the body text exactly as received, before any JSON parsing.
// headers: the request headers, names in lower case.
export function verifyAtendia(rawBody, headers, idPrefix) {
  // Throws if the signature is wrong or the timestamp is more than 5 minutes off.
  const data = webhook.verify(rawBody, headers);
  // Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
  if (!headers["webhook-id"].startsWith(idPrefix)) throw new Error("unexpected id");
  return data;
}

Node, à mão

javascript
import { createHmac, timingSafeEqual } from "node:crypto";

export function verifyAtendia(secret, rawBody, headers, idPrefix) {
  const id = headers["webhook-id"];
  const timestamp = headers["webhook-timestamp"];
  const signatures = headers["webhook-signature"];
  if (!id || !timestamp || !signatures) return false;
  // 5 minutes either way. "!(x <= 300)" also refuses a timestamp that is not a number.
  if (!(Math.abs(Date.now() / 1000 - Number(timestamp)) <= 300)) return false;
  // Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
  if (!id.startsWith(idPrefix)) return false;
  const key = Buffer.from(secret.slice("whsec_".length), "base64");
  const expected = createHmac("sha256", key).update(`${id}.${timestamp}.${rawBody}`).digest();
  // During a rotation there are two entries; one match is enough.
  return signatures.split(" ").some((entry) => {
    const [version, value] = entry.split(",");
    if (version !== "v1" || !value) return false;
    const received = Buffer.from(value, "base64");
    return received.length === expected.length && timingSafeEqual(received, expected);
  });
}

Python, com a biblioteca

python
import os
from standardwebhooks import Webhook

# The whsec_... secret, shown once when you created it.
webhook = Webhook(os.environ["ATENDIA_SIGNING_SECRET"])


def verify_atendia(raw_body: bytes, headers: dict, id_prefix: str) -> None:
    # Raises WebhookVerificationError if the signature is wrong or the
    # timestamp is more than 5 minutes off. raw_body: the bytes as received.
    webhook.verify(raw_body, headers, json_parse=False)
    # Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
    if not {k.lower(): v for k, v in headers.items()}["webhook-id"].startswith(id_prefix):
        raise ValueError("unexpected id")

Python, à mão

python
import base64
import hashlib
import hmac
import time


def verify_atendia(secret: str, raw_body: bytes, headers: dict, id_prefix: str) -> bool:
    msg_id = headers.get("webhook-id")
    timestamp = headers.get("webhook-timestamp")
    signatures = headers.get("webhook-signature")
    if not (msg_id and timestamp and signatures):
        return False
    try:
        age = abs(time.time() - float(timestamp))
    except ValueError:
        return False
    if not age <= 300:  # 5 minutes either way; also refuses nan
        return False
    # Tool: "atd_tool_<your tool id>_". Post-call webhook: "atd_postcall_<your agent id>_".
    if not msg_id.startswith(id_prefix):
        return False
    key = base64.b64decode(secret[len("whsec_"):])
    signed = f"{msg_id}.{timestamp}.".encode() + raw_body
    expected = hmac.new(key, signed, hashlib.sha256).digest()
    # During a rotation there are two entries; one match is enough.
    for entry in signatures.split(" "):
        version, _, value = entry.partition(",")
        if version != "v1" or not value:
            continue
        try:
            received = base64.b64decode(value)
        except ValueError:
            continue
        if hmac.compare_digest(received, expected):
            return True
    return False

Trocar o segredo

  • Usa «Criar segredo novo» para criar outro. O antigo continua a assinar durante 24 horas, e cada pedido leva as duas assinaturas no mesmo cabeçalho (v1,... v1,...). As bibliotecas aceitam se uma delas bater.
  • Neste prazo, põe o segredo novo no teu sistema. Os pedidos não falham.
  • Se criares outro segredo novo antes das 24 horas, o mais antigo deixa de assinar logo: nunca há mais de dois.
  • «Deixar de aceitar o anterior» corta o segredo antigo de imediato (por exemplo, se foi exposto). «Desligar assinatura» apaga todos os segredos e os pedidos voltam a sair sem assinatura.

O que a assinatura prova

  • Prova que o pedido veio da Atendia, com a configuração da tua organização.
  • Não prova que os valores que o agente preencheu a partir da conversa são verdadeiros. Valida-os como validarias o que escreve um utilizador.
  • Quem, na tua organização, tem permissão para editar ferramentas pode fazer a Atendia assinar um pedido para o endereço e com o corpo que escolher, incluindo pelo teste da consola. O início do id só garante de que ferramenta vem o pedido; a assinatura confia em quem configura as ferramentas.

Id do pedido e chave contra duplicados

  • Com assinatura, cada pedido de uma ferramenta leva um webhook-id novo: atd_tool_, o id da ferramenta, _ e 22 caracteres aleatórios. Dois pedidos iguais têm ids diferentes. O id serve para confirmar a origem, não para apanhar duplicados.
  • Para duplicados, a ferramenta tem o interruptor «Evitar pedidos repetidos». Ligada, a Atendia envia o cabeçalho Idempotency-Key (atd_ e 32 caracteres) em cada pedido que não é GET. Funciona com ou sem assinatura. Uma ferramenta nova vem com a opção ligada; as que já existiam ficam desligadas.
  • A chave é calculada a partir da chamada, da ferramenta, do método, do endereço e do corpo. A mesma escrita, com os mesmos dados, na mesma chamada, leva sempre a mesma chave. A chave não revela os dados.
  • Limite: dados diferentes dão outra chave. Se o agente repetir a escrita com um dado diferente (outra hora, outro nome), a Atendia envia-a como um pedido novo, com outra chave. Verifica também os duplicados pelos dados, por exemplo pela hora e pelo contacto.
  • A tua API tem de guardar a chave e, ao vê-la outra vez, devolver o resultado guardado. Nem todas as APIs tratam este cabeçalho; se a tua o ignora, a chave não protege.
  • Os nomes webhook-id, webhook-timestamp, webhook-signature e idempotency-key são da Atendia. Não os podes pôr nos cabeçalhos de uma ferramenta nem do webhook pós-chamada (a gravação é recusada), e ao enviar a Atendia troca qualquer cabeçalho com esse nome pelo seu.

Testar na consola

  • O teste envia um pedido real à tua API.
  • Num pedido que não é GET, a consola pede confirmação antes de enviar, porque pode alterar dados.
  • Há um limite de 10 testes por minuto por organização.
  • Se a ferramenta usa o número do contacto, o teste usa o número de exemplo que indicares.
  • O teste mostra a resposta completa, com os segredos escondidos, e «O que o agente recebe»: o resultado depois de escolhidos os campos e cortado como na chamada. O agente lê-o em texto.
  • Depois de uma chave recusada (erro 401), a Atendia espera 1 minuto antes de mandar outro pedido para esse serviço. O teste diz quantos segundos faltam.

Importar de um exemplo da API (cURL)

Cola um comando curl da documentação da tua API e a consola preenche a ferramenta. Nada é executado, enviado ou gravado até gravares a ferramenta. Se a ferramenta já estiver preenchida, a consola pede confirmação antes de a substituir.

O que é aceite

  • O endereço e as opções -X / --request (GET, POST, PUT, PATCH, DELETE), -H / --header, -d / --data / --data-raw / --data-binary / --json com um corpo JSON, -G / --get e -u / --user. Aspas simples e duplas e \ no fim da linha funcionam.
  • Sem -X, o método é GET; com corpo, é POST. Com -G, os dados de -d vão para a query. --json junta os cabeçalhos Content-Type e Accept de JSON.
  • As opções -s, -S, -v, -i, --compressed, -L e -k são ignoradas, com uma nota. A Atendia não segue redirecionamentos (-L) e verifica sempre o certificado (-k).
  • O corpo JSON vira parâmetros com valor fixo, cada um com a sua «Posição no JSON» (ver «Caminhos»), até 50 valores. A query vira parâmetros de query com valor fixo.

Credenciais

  • Um cabeçalho com nome de credencial (Authorization, X-Api-Key...) e o -u (que vira Authorization: Basic) ficam como cabeçalho do tipo «Secret».
  • Um parâmetro da query ou do corpo com nome de credencial (token, password...) vira um parâmetro «Variável dinâmica» ligado a uma variável dinâmica do tipo «Secret».
  • Ao gravar, esses valores ficam guardados de forma segura. Nenhuma credencial fica em texto claro na ferramenta.

O que é recusado

A consola recusa o comando todo, com uma mensagem, e não importa nada. Recusa:

  • Qualquer outra opção.
  • Comandos do shell: $(...), crases, $VARIAVEL fora de aspas simples, ;, |, &, < e >.
  • -b / --cookie, -K / --config, --oauth2-bearer, --data-urlencode, -F / --form, @ficheiro, um utilizador e palavra-passe no endereço (https://u:p@...).
  • Um corpo que não seja JSON, um corpo num GET e os cabeçalhos reservados da Atendia.

Caminhos

Caminhos da resposta

Em «Campos da resposta» dás um nome e um caminho a cada campo (até 20 campos). O agente recebe só esses campos, em data. Os caminhos lêem-se como as variáveis da resposta do webhook de início.

  • a.b.c desce por chaves. itens[0].nome lê o primeiro elemento de uma lista.
  • Numa resposta que é uma lista, começa com [0]. Não uses $[0].
  • $ é o valor inteiro. $.a é o mesmo que a.
  • itens[*].nome dá a lista dos nomes de todos os elementos, até 100. Elementos sem o campo ficam de fora. Se itens não for uma lista, o resultado é null.
  • Uma chave que existe tal e qual, como "a.b", ganha à leitura por passos.
  • [01] é o mesmo que [1]. a[0]b é o mesmo que a[0].b. Os espaços à volta do caminho são ignorados.
  • Um caminho que não se consegue ler é recusado ao guardar: um segmento vazio (a..b, a.), um parêntese por fechar (a[0) ou um índice negativo ou que não é número. Um caminho válido sem valor na resposta, como um índice fora da lista, chega como null.
  • Só se leem chaves da própria resposta. length ou toString não existem.
  • Máximo de 8 passos e 200 caracteres. __proto__, prototype e constructor são recusados. Um índice com algarismos que não são 0 a 9 é recusado ao guardar.
  • O nome do campo tem letras, algarismos e _, começa por letra ou _ e tem até 64 caracteres. Nomes que a limpeza esconderia (token, password, secret…) são recusados, porque o agente só veria [REDACTED].
  • A limpeza corre antes da escolha. Se o caminho passa por um texto [REDACTED], o campo chega como [REDACTED].

Posição no corpo

  • Forma: cliente.telefone, itens[0].id. Cada nome usa letras, algarismos e _ $ @ : -, até 64 caracteres. O índice vai de 0 a 99.
  • Máximo de 8 passos e 200 caracteres. Sem $ à frente e sem [*].
  • Ao guardar, a Atendia recusa posições repetidas, uma posição que seja ao mesmo tempo valor e pai (a e a.b), um nó que seja lista e objeto (a[0] e a.b) e índices de uma lista que não começam em 0 ou saltam.
  • Um objeto ou lista só aparece no corpo se tiver pelo menos um valor. Numa lista, os elementos sem valor saem e os seguintes sobem.
  • Só os parâmetros do corpo têm posição. Query e caminho são sempre planos.

Webhook pós-chamada

No fim da chamada, a Atendia faz um POST ao endereço do webhook pós-chamada do agente, com o resultado em JSON. Responde 2xx depressa: a Atendia espera 10 segundos e uma resposta que não seja 2xx conta como falha. A mesma entrega pode chegar mais de uma vez: guarda o que já trataste e ignora o repetido.

O corpo

  • Sempre: callId, agentId, startedAt, endedAt, durationSeconds, direction, callerId e extractedData.
  • transfer (state, e quando existem reason e humanSeconds): só se a chamada tentou uma transferência.
  • transcript: uma lista de role, message e timestamp, só se ligaste a transcrição no webhook.
  • audioUrl: o endereço da gravação, só se ligaste o áudio no webhook.

Cabeçalhos e assinatura

  • Content-Type: application/json e os cabeçalhos que configuraste no webhook. Os nomes reservados da Atendia (ver «Id do pedido e chave contra duplicados») não são aceites.
  • Com segredo de assinatura, o webhook leva webhook-id, webhook-timestamp e webhook-signature, verificados como na secção «Assinatura dos pedidos». O corpo assinado é o texto exato que a Atendia envia.
  • O webhook-id é atd_postcall_, o id do agente, _ e o id da chamada. Uma entrega repetida leva o mesmo id: guarda os ids que já tratas e descarta uma entrega repetida. Confirma que o id começa por atd_postcall_ e o id do teu agente. Numa chamada de saída que termina sem registo da chamada, o id leva o outboundId e o estado, e o resultado que chega mais tarde com o registo leva outro id; ver «Fazer chamadas a partir do teu programa».
  • O webhook de início da chamada ainda não é assinado.

Dois exemplos

Consultar uma encomenda (GET)

A ferramenta, com os campos da resposta:

tool
Método:   GET
Endereço: https://api.loja.example/encomendas/{numero}
Cabeçalho: Authorization = (segredo)
Parâmetro de caminho: numero (Pedido ao modelo, texto, obrigatório)
Campos da resposta:
  estado  <- encomenda.estado
  entrega <- encomenda.entrega.data
  artigos <- itens[*].nome

A tua API responde:

json
{"encomenda": {"estado": "enviada", "entrega": {"data": "2026-11-03"}},
 "itens": [{"nome": "Cadeira", "preco": 49.9}, {"nome": "Mesa", "preco": 120}]}

O agente recebe:

json
{"status": 200, "data": {"estado": "enviada", "entrega": "2026-11-03", "artigos": ["Cadeira", "Mesa"]}}

Criar um pedido de apoio (POST)

A ferramenta, com posições no corpo:

tool
Método:   POST
Endereço: https://api.loja.example/pedidos-apoio
Parâmetros do corpo (nome -> posição):
  nome       -> cliente.nome       (Pedido ao modelo)
  telefone   -> cliente.telefone   (Variável dinâmica: system__contact_number)
  assunto    -> sem posição        (Pedido ao modelo)
  prioridade -> detalhe.prioridade (Valor estático: normal)

O corpo enviado:

json
{"cliente": {"nome": "Ana Reis", "telefone": "+351900000000"},
 "assunto": "Entrega atrasada",
 "detalhe": {"prioridade": "normal"}}

A tua API responde {"id": "A-1042"} e o agente recebe:

json
{"status": 201, "data": {"id": "A-1042"}}

Enviar um SMS

O agente pode enviar um SMS durante a chamada, pela tua conta num fornecedor de SMS (por exemplo, a LOX24), com uma ferramenta HTTP. Os SMS saem da tua conta e pagas ao fornecedor.

Como preparar

  1. Abre conta num fornecedor de SMS com API.
  2. Cria a chave da API. Na LOX24: «Settings» → «API Settings», com o papel «API v2: messaging».
  3. Pede ao Construtor, por exemplo: «Quero que o agente envie um SMS de confirmação da marcação». O Construtor prepara a ferramenta e tu escreves a chave no campo secreto. Na LOX24, escreve o número de conta, dois pontos e a chave (<número de conta>:<chave>).
  4. No cartão, o endereço de destino da LOX24 é https://api.lox24.eu/sms.

O que o agente faz

  • Pergunta primeiro e só envia depois de quem está na chamada confirmar. A ferramenta fica com «Confirmar antes de enviar» ligado.
  • Envia sempre para o número de quem está na chamada. Numa chamada de saída, é o número para onde o agente ligou.
  • Por regra, envia um só SMS por chamada.
  • O teste por texto não envia SMS.

O texto do SMS

  • Sem acentos e até 160 caracteres. Acima disso, conta como 2 SMS. O «€» escreve-se «EUR».
  • O remetente é o nome do negócio: até 11 letras, sem acentos.
  • Num negócio de saúde, recomendamos um texto neutro: data, hora e nome do negócio. A decisão é tua.

Se a chave estiver errada

  • Depois de uma chave recusada, a Atendia espera 1 minuto antes de mandar outro pedido para esse serviço. Nas chamadas, a mesma chave fica 15 minutos parada.
  • Corrige a chave e testa a ferramenta em «Ferramentas».
  • Porquê: alguns fornecedores bloqueiam os pedidos de todos depois de várias chaves erradas.

O que fica guardado

O que o agente lê para confirmar o SMS fica na transcrição e no resumo da chamada, como o resto da conversa. O texto enviado fica na tua conta no fornecedor de SMS.

Outros fornecedores

Se já usas a BulkGate, o Construtor também tem os passos dela. Com outro fornecedor que tenha API, o caminho é o de qualquer API: importa o exemplo do fornecedor e muda à mão o número para o de quem está na chamada e o texto para o agente preencher. Vê Importar de um exemplo da API (cURL).

Limites atuais

  • Sem OAuth2. Usa um token fixo num cabeçalho, guardado como segredo.
  • Sem listas de tamanho variável. O agente não escolhe quantos elementos enviar. Uma lista de tamanho fixo faz-se com índices (servicos[0].id, servicos[1].id).
  • No corpo, uma chave com . só se envia sem posição, no primeiro nível. Dentro de um objeto, não é suportada.
  • Só corpos JSON. Não há formulários nem ficheiros.
  • Só https://, sem redirecionamentos e sem destinos privados.