Rodar o agente pelo seu sistema (execuções por usuário final)

Atualizado em 16/10/2026

O agente não precisa esperar alguém abrir o chat. O seu sistema pode pedir uma execução na hora que quiser, em nome de um cliente seu, e receber a resposta pronta: um resumo diário às 8h, um aviso quando algo acontece por lá, ou um botão dentro do seu produto.

Quem tem o relógio é você. A plataforma não agenda nada para os seus clientes, e isso é de propósito: você já sabe quando cada coisa deve acontecer, e a autorização fica respondida na origem. Cliente que saiu da sua empresa simplesmente para de aparecer na sua rotina, sem nada para revogar do nosso lado.

O que você precisa antes

1. Subcontas ativas e uma subconta criada para o cliente, com créditos. Veja Subcontas.
2. A chave da subconta, gerada no detalhe dela e exibida uma única vez.
3. Um agente configurado. Sem informar agent_id, responde o mesmo que atenderia no chat: o da marca do canal, ou o padrão da conta.

A chamada

curl -X POST https://api.seudominio.com/api/v1/agent-runs \
-H "Authorization: Bearer CHAVE_DA_SUBCONTA" \
-H "Idempotency-Key: rotina-7781-2026-08-05" \
-H "Content-Type: application/json" \
-d '{
"user_ref": "7781",
"task": "Liste o que vence hoje e o que ficou parado há mais de 3 dias.",
"deliver_to": ["chat"],
"callback_url": "https://seusistema.com/desk/resultado"
}'

{ "data": { "run_id": "run_9f2c…", "status": "queued" } }

Você não informa qual é a subconta: ela vem da chave, e aquela chave não alcança nenhuma outra.

Já assina o payload do chat? Então mande o mesmo auth e sig que você monta para o identify(), acrescentando só o texto do pedido. O user_ref, o nome e o e-mail saem do payload assinado, e a identidade chega às suas ações exatamente como chegaria numa conversa.

Campos:

Pegando o resultado

São três caminhos, escolha um:

• Callback (recomendado para rotinas): informe callback_url e receba o resultado quando ficar pronto, com delivered_to (o que realmente saiu) e conversation_token quando a entrega foi no chat. A chamada vai assinada no header X-Desk-Signature, com o mesmo segredo de webhook da sua conta. Confira a assinatura antes de confiar.
• Consulta: GET /api/v1/agent-runs/{run_id}.
• Na hora: acrescente ?wait=1 à chamada e receba o texto na resposta. Bom para botão dentro do seu produto, ruim para rotina, porque a conexão fica aberta enquanto o agente trabalha.

Repetição sem cobrança dobrada

Mande sempre um Idempotency-Key único por execução pretendida (algo como rotina-{usuario}-{data}). Repetir a mesma chave nunca roda duas vezes: se ainda estiver em andamento você recebe 409, e se já tiver terminado, o resultado de novo, sem gastar créditos.

Consultando os dados do seu cliente

Não há nada para configurar: valem as mesmas regras do chat identificado. Uma execução em nome de um cliente final chama as suas ações quando três coisas são verdade:

1. É consulta, não alteração. Ações de escrita nunca são executadas em nome de um cliente final. Quem altera o seu sistema é você.
2. Sabemos quem está pedindo, de forma verificada. Ou pelo payload assinado (o mesmo auth + sig do chat), ou pela chave da subconta, que é secreta e só sua.
3. A sua API sabe de quem se trata. Ou porque a ação usa o token do próprio usuário (o caso mais comum: nada muda no seu código, é só mandar o token em user_token ou dentro de meta), ou porque a API já recebe a identidade assinada nos Parâmetros adicionais.

A plataforma nunca filtra os seus dados, porque não os tem. Ela prova, de forma que não dá para forjar, quem está pedindo. Quem decide o que cada pessoa enxerga é a sua API.

Entregas

• chat e whatsapp entregam dentro da conversa que a pessoa já tem. Sem conversa existente, por padrão não há entrega, e nenhuma conversa nova é aberta: um aviso diário por cliente viraria um chamado por dia na sua fila. A mensagem também não reabre nem reatribui nada; só vira conversa se a pessoa responder.
• Precisa chegar a quem nunca abriu o chat? Mande deliver_chat_create: true: a conversa é criada como o widget criaria com identidade verificada (carimbada com a subconta e o user_ref) e o texto entra como resposta da IA, sem rodar o agente de novo. Ela nasce resolvida e sem responsável, então não cai na fila de não resolvidos; se a pessoa responder pelo widget, vira conversa normal. O delivered_to passa a incluir chat, e a resposta e o callback trazem conversation_token: use-o com Chat.resume(token) para abrir direto a thread. Para a conversa aparecer em GET /public/chat/conversations, use o mesmo key assinado na chamada (é o canal do key que define a marca da conversa) e mande o e-mail no payload (a listagem recorta pela identidade verificada).
• Rotina recorrente? Prefira uma conversa por execução. Mande deliver_chat_new: true (o deliver_chat_create fica implícito): cada execução cria a própria conversa — resolvida, sem responsável, com o texto como resposta da IA, igual à de cima — em vez de empilhar relatório sobre relatório na mesma thread. O conversation_token de cada execução aponta a conversa daquela execução, então o link "abrir no chat" de um relatório antigo continua abrindo aquele relatório. Com deliver_chat_title você nomeia a conversa (por exemplo, o nome da rotina e a data); sem ele, o título sai do texto do pedido.
• whatsapp ainda exige telefone vinculado àquele user_ref e conversa dentro da janela de 24 horas.
• email sai em nome da sua marca, para o endereço que você informar.
• webhook entrega para você, e aí quem avisa a pessoa é o seu produto.

Pode combinar mais de um. O que realmente saiu fica registrado na execução.

Erros que a sua rotina precisa tratar

Acompanhando pelo painel

Em Inteligência › Agentes › aba Subcontas, o botão Configurações › Documentação da API traz o exemplo já preenchido com os seus dados e, logo abaixo dele, o histórico das últimas execuções: situação, tempo, canal de entrega e o erro quando houve.

Quando uma execução é recusada por falta de saldo ou falha, você recebe um aviso no painel. Não se preocupe com rotina insistente: o aviso não se repete no mesmo dia.