Referência da API

Deployments de canal

Anexe um agent a um número ou conexão de canal e escolha qual versão dele atende.

Um deployment é a ponte entre um agent e uma conexão de canal (o número de WhatsApp, o webchat). Ele decide quem responde o inbound daquele canal e, opcionalmente, em qual versão.

#Endpoints

Método	Caminho	Descrição
POST	`/v1/projects/:projectId/agent-deployments`	Anexa um agent a uma conexão.
GET	`/v1/projects/:projectId/agent-deployments`	Lista deployments por cursor, com filtros de conexão e agent.
PATCH	`/v1/projects/:projectId/agent-deployments/:id`	Liga/desliga, pina versão e troca os dials.
DELETE	`/v1/projects/:projectId/agent-deployments/:id`	Remove o deployment.

#Criar deployment

json

{
  "agentId": "agent_...",
  "connectionId": "conn_...",
  "agentVersion": 7,
  "config": { "escalationTarget": { "teamId": "team_..." } }
}

const deployment = await client.agentDeployments.create({
  agentId: agent.id,
  connectionId: connection.id,
  agentVersion: 7,
});

Uma conexão tem no máximo um deployment: repetir devolve 409 deployment.conflict. Trocar o agent de um número é remover e criar de novo — o PATCH não aceita agentId.

#Pin de versão

agentVersion escolhe qual versão publicada do agent atende aquele canal.

Valor	Efeito
ausente ou `null` (na criação)	Versão automática: cada session nova nasce na versão corrente do agent.
número	Versão pinada: toda session nova daquele canal nasce nessa versão.
`null` (no PATCH)	Limpa o pin — volta a flutuar na corrente.
ausente (no PATCH)	Não mexe no pin atual.

A resposta sempre traz agentVersion explícito (null quando flutuante):

json

{
  "id": "adep_...",
  "connectionId": "conn_...",
  "agentId": "agent_...",
  "enabled": true,
  "agentVersion": 7,
  "config": {},
  "createdAt": "2026-08-01T12:00:00.000Z",
  "updatedAt": "2026-08-01T12:00:00.000Z"
}

Sessions já em execução não são tocadas por uma troca de pin: o pin decide a versão no nascimento da session.

Validação na escrita. O pin só é aceito quando o agent não está arquivado e a versão existe:

Código	HTTP	Quando
`deployment.agent_archived`	422	Tentativa de pinar versão de um agent arquivado.
`deployment.agent_version_not_found`	422	A versão pedida não existe nesse agent.
`deployment.conflict`	409	A conexão já tem um deployment.
`deployment.not_found`	404	Deployment inexistente ou fora do projeto.
`agent.not_found`	404	O agent informado não existe no projeto.
`integration.connection_not_found`	404	A conexão informada não existe no projeto.

Criar um deployment sem pin para um agent arquivado continua permitido — o gate de arquivamento existe para o pin, não para o vínculo.

Fallback defensivo. Se, apesar da validação da escrita, o pin apontar para uma versão que não existe mais no momento em que uma mensagem chega, a plataforma degrada para a versão corrente e registra erro no log em vez de deixar a mensagem sem resposta. O pin também só vale quando o deployment é do mesmo agent que vai atender: um handoff manual para outro agent não herda o pin do número.

#Endpoints

#Criar deployment

#Pin de versão

#Relacionado