Ao terminar este guia, você terá verificado sua chave e criado uma chamada com a API do Agents. Tudo roda em modo de teste: nenhum número é discado e nada é cobrado.
Antes de começar
Você precisa de:
- Uma conta Qomni (teste grátis de 14 dias, sem cartão).
- Um terminal com
curl, ou Python 3.9 ou superior, ou Node.js 18 ou superior.
-
Crie uma chave de teste
Cadastre-se em qomni.ai. Em Settings → API keys do seu workspace, crie uma chave de teste: ela começa por
sk_agents_test_. Guarde-a em uma variável de ambiente do seu shell:export QOMNI_KEY="sk_agents_test_…"Os exemplos desta página a leem de
QOMNI_KEY. Não a escreva no seu código nem a envie para um repositório. -
Instale o necessário
Com cURL você não precisa de mais nada. Em Python usamos
requests; o Node.js já trazfetch, etsxexecuta TypeScript sem compilar.pip install requestsnpm install --save-dev tsx -
Verifique a chave
Peça à API o contexto da sua chave. Salve o código em
ping.pyouping.mts, ou cole o comando cURL no seu terminal:curl https://api.qomni.ai/agents/v1/ping \ -H "Authorization: Bearer $QOMNI_KEY"import os import requests key = os.environ["QOMNI_KEY"] response = requests.get( "https://api.qomni.ai/agents/v1/ping", headers={"Authorization": f"Bearer {key}"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") print(response.json())const response = await fetch("https://api.qomni.ai/agents/v1/ping", { headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}` }, }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } console.log(await response.json());Execute:
python ping.pynpx tsx ping.mtsUm
200traz seu workspace elivemode: false, porque a chave é de teste. A resposta pode trazer mais campos: ignore os que você não conhece.200 OKjson { "product": "agents", "tenant": "acme", "cell": "co1", "region": "co", "livemode": false }Um
401significa que a chave falta ou não é válida: o campocodedo erro diz qual das duas. Veja Erros. -
Crie uma chamada
Peça que um agente ligue para um número. Em modo de teste,
+15005550001é um número mágico que sempre termina emcompleted. Salve o código emcreate_call.pyoucreate_call.mtse execute como no passo anterior:curl https://api.qomni.ai/agents/v1/calls \ -H "Authorization: Bearer $QOMNI_KEY" \ -H "Content-Type: application/json" \ -d '{ "to": "+15005550001" }'import os import requests key = os.environ["QOMNI_KEY"] response = requests.post( "https://api.qomni.ai/agents/v1/calls", headers={"Authorization": f"Bearer {key}"}, json={"to": "+15005550001"}, timeout=10, ) if not response.ok: error = response.json()["error"] raise SystemExit(f"{error['code']}: {error['message']}") call = response.json() print(call["id"], call["status"])const url = "https://api.qomni.ai/agents/v1/calls"; const response = await fetch(url, { method: "POST", headers: { Authorization: `Bearer ${process.env.QOMNI_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ to: "+15005550001" }), }); if (!response.ok) { const { error } = await response.json(); throw new Error(`${error.code}: ${error.message}`); } const call = await response.json(); console.log(call.id, call.status);A API responde
201com a chamada:201 Createdjson { "id": "call_01k8x2m4v7q9r3t5w8y1z0a2b4", "to": "+15005550001", "status": "completed", "livemode": false, "cell": "co1", "region": "co", "created_at": "2026-10-21T15:04:05+00:00" }
Você deve ver
A chamada existe, com status completed, e nenhum telefone tocou: assim
funciona o modo de teste. Você acabou de fazer as duas
chamadas que qualquer integração com o Agents faz: verificar a chave e criar
uma chamada. GET /calls as devolve para você, a mais recente primeiro.
Se no passo 3 você viu 401, o campo code diz por quê: api_key_missing
se o header falta, api_key_malformed se a chave foi copiada errado,
api_key_invalid se foi revogada.
Próximo passo
Troque a chave de teste por uma real (sk_agents_live_…) e o mesmo código
faz chamadas de verdade. Antes disso, coloque o agente para conversar com seu app:
- Referência do Agents: cada endpoint, campo e erro.
- Idempotência e novas tentativas: tente de novo sem criar duas chamadas.