Allerto API

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:

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:

{
  "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" }
}

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

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

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. No call is placed.

4. Place a test call

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

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.

5. Receive the result

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

{
  "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. 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.

← OverviewAgents →