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://. Comhttp://, 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émContent-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,UpgradeeProxy-*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) outest. 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 exemplo2026-11-03T14:30:05+00:00.system__date: a data,AAAA-MM-DD.system__time: a hora,HH:MM. Poupam-te formatarsystem__nowno teu lado.system__timezone: o fuso do agente (nome IANA), por exemploEurope/Lisbon. Se o fuso do agente for inválido, a Atendia usaEurope/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_agente 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,cookieouauthorizationchegam 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 acontece | O que o agente ouve |
|---|---|
| A tua API responde 200 a 299 | Recebe o resultado. |
| Responde 3xx (redirecionamento) | O serviço redirecionou o pedido e o redirecionamento não foi seguido. |
| Responde 401 ou 403 | O serviço recusou a autenticação. |
| Responde 404 | O serviço não encontrou o recurso pedido. |
| Responde 429 | O serviço limitou os pedidos por agora. Aguarda antes de tentar de novo. |
| Responde outro 4xx | O serviço recusou os dados do pedido. |
| Responde 5xx | O serviço devolveu um erro. Não repete sozinho; diz que a confirmação está pendente. |
| Não responde dentro do tempo limite | O pedido excedeu o tempo limite. Não repete sozinho; diz que a confirmação está pendente. |
| A ligação falha a meio | A ligação falhou. Não repete sozinho; diz que a confirmação está pendente. |
| A resposta passa os 256 000 bytes | A 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 existe | O 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 é permitido | Os 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 dewhsec_. - O endereço e os outros cabeçalhos não são assinados.
Como verificar
- Lê o corpo como texto, tal como chegou, antes de o converter para JSON. Um corpo reescrito já não bate com a assinatura.
- Aceita só pedidos com a hora a menos de 5 minutos de diferença (para cada lado). É a tolerância das bibliotecas oficiais.
- 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. - Se a verificação falhar, responde 401 e não faças nada com o pedido.
- 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.
- 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
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
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
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
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-idnovo: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-signatureeidempotency-keysã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/--jsoncom um corpo JSON,-G/--gete-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-dvão para a query.--jsonjunta os cabeçalhosContent-TypeeAcceptde JSON. - As opções
-s,-S,-v,-i,--compressed,-Le-ksã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 viraAuthorization: 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,$VARIAVELfora 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.cdesce por chaves.itens[0].nomelê 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 quea.itens[*].nomedá a lista dos nomes de todos os elementos, até 100. Elementos sem o campo ficam de fora. Seitensnã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 quea[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 comonull. - Só se leem chaves da própria resposta.
lengthoutoStringnão existem. - Máximo de 8 passos e 200 caracteres.
__proto__,prototypeeconstructorsã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 (
aea.b), um nó que seja lista e objeto (a[0]ea.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,callerIdeextractedData. transfer(state, e quando existemreasonehumanSeconds): só se a chamada tentou uma transferência.transcript: uma lista derole,messageetimestamp, 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/jsone 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-timestampewebhook-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 poratd_postcall_e o id do teu agente. Numa chamada de saída que termina sem registo da chamada, o id leva ooutboundIde 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:
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[*].nomeA tua API responde:
{"encomenda": {"estado": "enviada", "entrega": {"data": "2026-11-03"}},
"itens": [{"nome": "Cadeira", "preco": 49.9}, {"nome": "Mesa", "preco": 120}]}O agente recebe:
{"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:
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:
{"cliente": {"nome": "Ana Reis", "telefone": "+351900000000"},
"assunto": "Entrega atrasada",
"detalhe": {"prioridade": "normal"}}A tua API responde {"id": "A-1042"} e o agente recebe:
{"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
- Abre conta num fornecedor de SMS com API.
- Cria a chave da API. Na LOX24: «Settings» → «API Settings», com o papel «API v2: messaging».
- 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>). - 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.