# Quickstart

> From an API key to a completed test call and its webhook, in five minutes.


# Quickstart

This walks through the whole outbound flow in **test mode**: nobody is phoned and nothing is billed.

## 1. Get a test key and install the CLI

In the console open **Numbers and developers → API keys** and create a key in **test** mode. Then:

```sh
npm install -g https://api.allerto.cloud/cli/allerto-cli.tgz
allerto login            # paste the alt_test_… key
allerto whoami           # Your account · TEST
```

Prefer HTTP? Every step below shows the equivalent request.

## 2. Write an agent

Save this as `reminder.json`:

```json
{
  "type": "outbound",
  "name": "Payment reminder",
  "persona": "Giulia",
  "language": "en",
  "opening": "Hello, this is Giulia, the virtual assistant of Example Ltd. Am I speaking with {{name}}?",
  "instructions": "Remind them that the {{month}} instalment of {{amount}} euros is still open and ask when they expect to pay.",
  "inputs": [
    { "key": "name", "label": "Name", "type": "text", "required": true },
    { "key": "amount", "label": "Amount", "type": "number", "required": true },
    { "key": "month", "label": "Month", "type": "text", "required": true }
  ],
  "result": [
    {
      "key": "answer",
      "label": "Answer",
      "type": "select",
      "required": true,
      "options": ["will_pay", "disputes", "already_paid"]
    },
    {
      "key": "pay_by",
      "label": "Promised date",
      "type": "date",
      "when": { "field": "answer", "equals": "will_pay" }
    }
  ],
  "delivery": { "mode": "webhook", "url": "https://your-app.example/allerto" }
}
```

```sh
allerto agents validate reminder.json
allerto webhook-secret rotate        # once per account; store the secret
allerto agents push reminder.json --publish
```

```http
POST /v1/agents              {"config": { …reminder.json… }}
POST /v1/webhook-secret
POST /v1/agents/{id}/publish {"revision": 1}
```

`push` writes the new `id` and `revision` back into the file, so the next `push` updates the same agent.

## 3. Preview what it will say

```sh
allerto agents preview <agent-id> --input name="Luca Galli" --input amount=250 --input month=January
```

You get the first sentence and the full prompt, including the [platform rules](/docs/platform-rules/). No call is placed.

## 4. Place a test call

```sh
allerto calls create --agent <agent-id> --to +390000000001 \
  --input name="Luca Galli" --input amount=250 --input month=January \
  --ref invoice-42 --wait
```

```http
POST /v1/calls
Idempotency-Key: invoice-42
{"agent": "<agent-id>", "to": "+390000000001", "reference": "invoice-42",
 "inputs": {"name": "Luca Galli", "amount": 250, "month": "January"}}
```

`+390000000001` always completes. Try `…02` (no answer), `…05` (callback requested) or `…06` (do not call): see [Test mode](/docs/test-mode/).

## 5. Receive the result

Your webhook receives one `call.completed` event, signed with your secret:

```json
{
  "type": "call.completed",
  "livemode": false,
  "call": {
    "id": "…",
    "direction": "outbound",
    "reference": "invoice-42",
    "outcome": "completed",
    "result": {
      "data": { "answer": "will_pay", "pay_by": "2026-10-05" },
      "issues": [],
      "summary": "Simulated call (test mode)."
    }
  }
}
```

Verify the signature as shown in [Webhooks](/docs/webhooks/). No webhook yet? `allerto calls get <id>` or `GET /v1/calls/{id}` return the same object.

## 6. Go live

Create a **live** key, check the agent's `calling.hours`, and call real numbers. Live calls use one of your account's numbers as caller ID and respect the calling window, the do-not-call list and the daily cap automatically.