Referência da API › Recursos
Gatilhos
Agende agentes, crie webhooks e reaja a eventos de apps.
Um gatilho roda um agente sem ninguém mandar mensagem. Cada execução cria uma conversa com origem trigger ou webhook. Para criar, alterar, rodar ou apagar, você precisa poder editar o agente. O gatilho roda com a conta de quem o criou.
O objeto Trigger#
{
"id": "trg_6a2c4e8b1d3f",
"agentId": "agt_8f3a2b1c9d0e",
"name": "Briefing das 8h",
"type": "schedule",
"schedule": { "kind": "cron", "expression": "0 8 * * 1-5" },
"timezone": "America/Sao_Paulo",
"prompt": "Gere o briefing diário de hoje e mande no meu e-mail.",
"model": null,
"enabled": true,
"lastRunAt": "2026-10-27T11:00:04.000Z",
"nextRunAt": "2026-10-28T11:00:00.000Z",
"mine": true,
"createdAt": "2026-10-20T15:00:00.000Z"
}type | Campos próprios |
|---|---|
schedule | schedule, timezone |
once | runAt, timezone |
webhook | webhookSecret (só para quem criou o gatilho ou pode editar o agente) |
app | app: { event, connectorId, params } |
GET/api/triggers#
Lista os gatilhos dos agentes que você pode ver.
| Query | Descrição |
|---|---|
agentId | Só os gatilhos de um agente. |
Resposta: { "triggers": [Trigger, ...] }.
POST/api/triggers#
| Campo | Tipo | Descrição |
|---|---|---|
agentId | string | Obrigatório. |
type | schedule, once, webhook, app | Obrigatório. |
name | string, 1 a 80 | Obrigatório. |
prompt | string, até 4.000 | O que o agente deve fazer. Obrigatório, exceto com passRawData. Pode citar campos do evento: {{email}}, {{cliente.nome}}. |
model | string ou null | Modelo só deste gatilho (openrouter/auto é o DoubleX Auto). Sem ele, vale o modelo do agente. |
timezone | string | Fuso IANA para schedule e once. Padrão America/Sao_Paulo. |
passRawData | boolean | webhook e app: o agente recebe só o JSON do evento, sem prompt. |
schedule | objeto | Para schedule. Veja abaixo. |
runAt | data ISO 8601 | Para once. Precisa estar no futuro. |
app | objeto | Para app: { "event", "connectorId", "params" }. |
Agendado#
schedule aceita uma destas formas:
| Forma | Exemplo |
|---|---|
| Cron (5 campos, intervalo mínimo de 5 minutos) | { "kind": "cron", "expression": "0 8 * * 1-5" } |
| Intervalo em minutos (5 a 10.080) | { "kind": "interval", "minutes": 30 } |
| Diário | { "kind": "daily", "time": "08:00" } |
Semanal (weekday de 0, domingo, a 6) | { "kind": "weekly", "weekday": 1, "time": "09:30" } |
curl -X POST https://doublex.ai/api/triggers \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"agentId": "agt_8f3a2b1c9d0e",
"type": "schedule",
"name": "Briefing das 8h",
"prompt": "Gere o briefing diário de hoje e mande no meu e-mail.",
"schedule": { "kind": "cron", "expression": "0 8 * * 1-5" },
"timezone": "America/Sao_Paulo"
}'Webhook#
{ "agentId": "agt_8f3a2b1c9d0e", "type": "webhook", "name": "Novo lead", "prompt": "Qualifique o lead {{nome}} ({{email}})." }A resposta traz o webhookSecret. O endereço é https://doublex.ai/api/webhooks/<id do gatilho>. Veja como chamar em Webhooks.
Evento de app#
{
"agentId": "agt_2b7e4c6a1f3d",
"type": "app",
"name": "Pedido por e-mail",
"prompt": "Chegou um pedido de {{from}}: {{subject}}. Registre na planilha de pedidos.",
"app": { "event": "gmail.new_email", "connectorId": "con_7a9b1c3d5e2f", "params": { "query": "subject:pedido" } }
}event | Parâmetros | Campos para o prompt |
|---|---|---|
gmail.new_email | query | from, to, subject, date, snippet, body, attachments, labels |
google-calendar.new_event | calendar_id | title, start, end, location, description, organizer, attendees, link |
google-calendar.event_starting | calendar_id, minutes_before | os da agenda e minutes_until |
google-drive.new_file | folder | name, mime_type, link, created_time, owner |
google-sheets.new_row | spreadsheet (obrigatório), sheet | row_number, row, sheet |
O conector precisa ser do mesmo serviço do evento e você precisa poder usá-lo. A plataforma consulta o app a cada dois minutos; a primeira consulta só marca o ponto de partida.
Resposta 201: { "trigger": Trigger }. Os erros 400 explicam o problema: cron inválido ou frequente demais, data no passado, fuso inválido, evento ou parâmetro desconhecido, conector errado.
GET/api/triggers/apps#
Os eventos de app disponíveis, com parâmetros e campos, e as suas contas Google que podem ser usadas:
{
"events": [{ "id": "gmail.new_email", "service": "gmail", "params": [{ "name": "query", "type": "text" }], "fields": ["from", "subject", "..."] }],
"accounts": [{ "id": "con_7a9b1c3d5e2f", "service": "gmail", "label": "[email protected]", "status": "connected", "mine": true }]
}POST/api/triggers/generate-cron#
Converte uma frase em cron.
| Campo | Tipo |
|---|---|
description | string, 2 a 300. Por exemplo, "toda sexta às 17h30". |
timezone | string, opcional |
{ "cron": "30 17 * * 5", "description": "Toda sexta-feira às 17:30" }Se description já for um cron válido, ele volta direto. Senão, um modelo de IA faz a conversão e consome créditos. Erros: 422 se a frase não vira um horário válido, 402 sem créditos.
PATCH/api/triggers/{id}#
Altera name, prompt, model (null volta ao modelo do agente), passRawData, timezone, enabled, schedule, runAt ou app. O type não muda: para trocar, apague e crie outro.
curl -X PATCH https://doublex.ai/api/triggers/trg_6a2c4e8b1d3f \
-H "Authorization: Bearer $DOUBLEX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"enabled": false}'Resposta: { "trigger": Trigger }.
POST/api/triggers/{id}/run#
Roda o gatilho agora, em segundo plano.
- Gatilhos
schedule,onceewebhook: resposta202{ "started": true }. Acompanhe a execução emGET /api/tasks?agentId=.... - Gatilhos
app: consulta o app na hora e responde200{ "checked": true, "found": 2 }.
Erros: 402 sem plano ativo (plan_required), sem créditos (no_credits) ou com o agente sem orçamento no mês (agent_budget); 409 se a execução anterior ainda não terminou; 503 se o agente não tem modelo disponível.
DELETE/api/triggers/{id}#
Resposta: { "ok": true }.
POST/api/webhooks/{id}#
O endereço público dos gatilhos webhook. Não usa chave de API: o segredo vai no cabeçalho x-webhook-secret. Responde 202 { "accepted": true }. Veja Webhooks.