Put an agent live

Switch an existing sales, service or acquisition agent live for a rooftop. This is the agent create-or-update call, sent with only the agent ID and isOnboarded: true.

POSThttps://api.spyne.ai/console/v1/product-onboarding/vini/agent

AuthBearer token (console user), validated again by the central config serviceRate limitNot documentedProcessingSynchronous, 30-second forward timeout

The request is forwarded as-is to the central config service. It first sets isOnboarded: true on the agent's team-agent mapping in the conversation service; if that fails, nothing is stored. It then merges agentId and isOnboarded into the stored agent record for this rooftop and agent type.

Auth: Bearer token of a signed-in console user, validated again by the central config service · Rate limit: not documented · Processing: synchronous, 30-second forward timeout

Before you call it

The agent must already exist. You need its team-agent mapping ID (agentId), returned when the agent is created in Create an agent. It is also listed as teamAgentMappingId by GET /console/v1/product-onboarding/vini/agents/teams/{teamId}/enterpriseId/{enterpriseId}.
The mapping must be active and must belong to the enterpriseId and teamId you send, or the call returns 400.
entity must be one of sales_inbound, sales_outbound, service_inbound, service_outbound, receptionist, acquisition_outbound or reputation_outbound.
No checks run before the switch. The call does not look at the readiness answers, checklist tasks, phone number or brand registration.
The onboarding console enables its go-live toggle only after the "Agent Customization" checklist task is done, and only on the sales inbound tab. That is a screen rule, not an API rule.

Request body

Requiredalways sendOptionalcan be left out

Request checklist

Headers: set Authorization: Bearer YOUR_TOKEN and Content-Type: application/json.
Identify the rooftop: send enterpriseId, teamId and entity.
Switch it on: set entityConfig.agent.agentId to the team-agent mapping ID and entityConfig.agent.isOnboarded to true.
Send nothing else in entityConfig.agent unless you mean to change it.
Check for 200 and data.agent.isOnboarded: true.

Parameter	Type	Required	Description
`enterpriseId`	string	Required	Dealer group ID.
`teamId`	string	Required	Rooftop ID.
`entity`	string	Required	Agent type, for example `sales_inbound`.
`enterpriseName`	string	Optional	Stored on the config if sent. The console sends it.
`teamName`	string	Optional	Stored on the config if sent. The console sends it.
`entityConfig`	object	Required	Holds the agent fields.
`agent`	object	Required	Send only the two fields below unless you mean to change others.
`agentId`	string	Required	Team-agent mapping ID. Its presence makes this an update. `teamAgentMappingId` is accepted as another name for it.
`isOnboarded`	boolean	Required	`true` to go live.

Sample request

curl -X POST "https://api.spyne.ai/console/v1/product-onboarding/vini/agent" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "enterpriseId": "<enterpriseId>",
    "teamId": "<teamId>",
    "enterpriseName": "<enterpriseName>",
    "teamName": "<teamName>",
    "entity": "sales_inbound",
    "entityConfig": { "agent": { "agentId": "<agentId>", "isOnboarded": true } }
  }'

import requests

res = requests.post(
    "https://api.spyne.ai/console/v1/product-onboarding/vini/agent",
    headers={"Authorization": "Bearer YOUR_TOKEN"},
    json={
        "enterpriseId": "<enterpriseId>",
        "teamId": "<teamId>",
        "entity": "sales_inbound",
        "entityConfig": {"agent": {"agentId": "<agentId>", "isOnboarded": True}},
    },
)
print(res.status_code, res.json())

const res = await fetch(
  'https://api.spyne.ai/console/v1/product-onboarding/vini/agent',
  {
    method: 'POST',
    headers: {
      Authorization: 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      enterpriseId: '<enterpriseId>',
      teamId: '<teamId>',
      entity: 'sales_inbound',
      entityConfig: { agent: { agentId: '<agentId>', isOnboarded: true } },
    }),
  }
);
console.log(res.status, await res.json());

Sample response

{
  "success": true,
  "message": "Agent updated successfully",
  "data": {
    "agentId": "<agentId>",
    "entity": "sales_inbound",
    "created": false,
    "agent": {
      "agentId": "<agentId>",
      "agentName": "<agentName>",
      "isOnboarded": true
    }
  }
}

{
  "success": false,
  "message": "Validation error",
  "errors": [
    {
      "code": "invalid_type",
      "expected": "boolean",
      "received": "string",
      "path": ["entityConfig", "agent", "isOnboarded"],
      "message": "Expected boolean, received string"
    }
  ]
}

{
  "success": false,
  "message": "Team agent mapping with id <agentId> not found",
  "error": "Team agent mapping with id <agentId> not found"
}

{
  "message": "Invalid Token",
  "error": true,
  "code": "ERROR_AUTH_401",
  "details": "",
  "data": null
}

{
  "success": false,
  "message": "<message from the conversation service>",
  "error": "<message from the conversation service>"
}

{
  "message": "No response received from external API",
  "error": "<error message>"
}

Response parameters (200)

Parameter	Type	Description
`success`	boolean	`true` on success.
`message`	string	`"Agent updated successfully"` for this call.
`data.agentId`	string	Team-agent mapping ID.
`data.entity`	string	Agent type.
`data.created`	boolean	`false` for an update.
`data.agent`	object	The stored agent record after the merge. It includes every field stored earlier for this agent, plus `isOnboarded`.

Errors

Status	Code	When it happens
`400`	Validation error	Missing `enterpriseId`, `teamId` or `entity`; `entity` not allowed; `isOnboarded` not a boolean; or `agentId` empty.
`400`	Team agent mapping not found	No active mapping with this ID for this dealer group and rooftop. The message comes from the conversation service.
`401`	`ERROR_AUTH_401` Invalid Token	No Bearer token, or the console's user check rejects it.
`401`	Invalid Auth key	The central config service rejects the forwarded token. Body: `"status": "401"` with this message.
`408`	`ERROR_REQ_TIMEOUT_408`	The console's user check timed out or could not connect.
`4xx`	Downstream message	The conversation service returned another 4xx. Its status and message are passed back as-is.
`500`	No response received from external API	The forward to the central config service got no response, including the 30-second timeout.
`500`	Failed to save agent	Unexpected error in the central config service.
`502`	Downstream message	The conversation service returned a 5xx or could not be reached.

What happens next

At runtime the conversation service treats an agent as available only when it is active and isOnboarded is true. That covers speed-to-lead SMS agent selection, default inbound call routing, web-call agent lookup, call transfer handoff and the campaign summary job.

To pause the agent, call Take an agent offline. To confirm the switch, re-read the agent list (GET /console/v1/product-onboarding/vini/agents/teams/{teamId}/enterpriseId/{enterpriseId}) and check config.isOnboarded.

In the onboarding console today, only the sales inbound tab has a go-live control. For sales outbound, service and acquisition agents there is no go-live control in onboarding. How those agents are switched live is to be confirmed; this API call works for them.