Agents

An agent is one JSON document. The console editor, allerto agents push, POST /v1/agents and the MCP tool create_agent all take exactly this object. The machine-readable schema is at /v1/agents/schema and in the reference.

#Common keys

#Inbound keys

Numbers belong to your account: Allerto buys them and assigns them to it. You route each one to any of your inbound agents with PUT /v1/numbers/{id} ({"agent": "<id>"}) or in the console, and every agent shows the numbers it answers on (numbers in the agent object). An agent from another account is refused with different_account.

Clients are an optional grouping (GET/POST /v1/clients). DELETE /v1/clients/{id} removes one: its agents are archived, its queued calls cancelled and its console login removed, while its calls and usage stay in your history. A client whose numbers are still active is refused with client_has_numbers; its external_id can be reused afterwards.

#Outbound keys

#Transfer to an operator

"transfer": {
  "to": "+390212345678",
  "when": "gas leaks, flooding or other emergencies",
  "hours": { "days": [1, 2, 3, 4, 5], "from": "09:00", "to": "18:00" },
  "announcement": "La metto in contatto con un operatore, resti in linea.",
  "musicUrl": "https://example.com/hold.mp3"
}

When the person asks to speak with an operator or a real person (or in the situations of when), the agent may ask once for their name and reason, then says the announcement and the call is transferred to to. Only to is required.

• to: the operator's number (E.164). It is the only number the agent ever transfers to, and it cannot be one of your Allerto numbers.
• hours: Italian time, any day of the week. Outside them the agent says nobody is available and takes the request. Without hours the transfer is always available.
• announcement: said word for word; the default is "La metto in contatto con un operatore, resti in linea." (Italian) or "I'm putting you through to a colleague, please hold." (English).
• musicUrl: an https audio file played while the operator's phone rings; without it the person hears the normal ringing tone.

The operator sees the Allerto number the person called (Italian networks block calls from abroad that show an Italian mobile number, so the caller's own number cannot be passed through); the caller's number is in the call data. If nobody answers within 25 seconds, the person hears that no operator is available and that their request has been recorded. A transfer lasts at most 30 minutes. The call keeps what was collected before the transfer, with outcome: "transferred" and a transfer object (see Calls).

#Fields

inputs and result use the same field shape:

{
  "key": "pay_by",
  "label": "Promised date",
  "type": "date",
  "required": false,
  "options": [],
  "when": { "field": "answer", "equals": "will_pay" },
  "description": "Only if they commit to a date"
}

Domain outcomes (promise to pay, dispute, confirmed appointment) belong in a select result field. The call outcome stays generic across sectors.

#Examples

Inbound:

{
  "type": "inbound",
  "name": "Fault reports",
  "persona": "Giulia",
  "greeting": "Good morning, this is Giulia, the virtual assistant of Studio Ferrario. How can I help?",
  "instructions": "Collect fault reports for the buildings we manage. Ask one question at a time.",
  "result": [
    { "key": "caller_name", "label": "Name", "type": "text", "required": true },
    {
      "key": "callback_phone",
      "label": "Callback number",
      "type": "phone",
      "required": true
    },
    {
      "key": "address",
      "label": "Building address",
      "type": "text",
      "required": true
    },
    {
      "key": "description",
      "label": "Description",
      "type": "text",
      "required": true
    }
  ],
  "delivery": { "mode": "email", "email": { "to": ["office@example.com"] } }
}

Outbound: see the Quickstart.

#Drafts, versions and concurrency

Every save needs the current revision. If someone else saved in between you get 409 revision_conflict with the current revision in details: reload, merge, save again. Publishing creates an immutable version; calls always record which version spoke.

Validation errors carry a path per problem (for example opening or result.2.when), so a program can point at the exact field.