One number for many users

​

What you’ll build

• A shared number whose calls go to one agent.
• A lookup on your server that answers within two seconds: whose call it is, the greeting, and the voice and languages for that user. When it says “not ours”, or can’t answer in time, the caller is not answered and nothing is charged.
• A background lookup for slower data, such as notes about the caller. Its values reach the agent during the call.
• A summary of each call in the user’s own language, delivered to your webhook.
• A way for your app to end a call while it runs.

• A workspace API key and its webhook secret. See the Quickstart.
• A phone number in your workspace that answers incoming calls. The inbound calling cookbook covers buying or connecting one.
• A public HTTPS server on port 443 for the lookups and the webhook. While you build, a tunnel to your laptop works.
• Python 3.10+ with FastAPI and httpx, or Node.js 18+ with Express. The setup steps also work with cURL and jq.

​

How it works

​

Step 1: Answer “whose call is it?” on your server

import hmac
import json
import os

from fastapi import FastAPI, Header, HTTPException, Request
from pydantic import BaseModel

app = FastAPI()
LOOKUP_KEY = os.environ["MIRAI_LOOKUP_KEY"]  # the value you store as the lookup_key secret


def check_key(authorization: str | None) -> None:
    expected = f"Bearer {LOOKUP_KEY}"
    if not hmac.compare_digest(authorization or "", expected):
        raise HTTPException(status_code=401)


class IncomingCall(BaseModel):
    call_id: str
    caller_number: str
    called_number: str


@app.post("/mirai/whose-call")
def whose_call(body: IncomingCall, authorization: str | None = Header(default=None)):
    check_key(authorization)
    # Stand-in: your user lookup. Keep it to an indexed read; the caller is ringing.
    user = db.users.for_incoming_call(body.caller_number, body.called_number)
    if user is None:
        return {"answer": False}
    db.calls.save(call_id=body.call_id, user_id=user.id)
    return {
        "answer": True,
        "user_id": user.id,
        "owner_name": user.first_name,
        "greeting": user.greeting,  # "Namaste, Asha ji ka assistant bol raha hoon. Aap kaun?"
        "instructions": user.instructions[:500],
        "reply_language": user.reply_language,  # "Hindi"
        "summary_language": user.summary_language,  # "English"
        "call_settings": {
            "voice_id": user.voice_id,  # "neha"
            "language": user.language,  # "hi"
            "secondary_languages": user.secondary_languages,  # ["en"]
        },
    }


@app.get("/mirai/caller-notes")
def caller_notes(call_id: str, caller_number: str, called_number: str,
                 authorization: str | None = Header(default=None)):
    check_key(authorization)
    # This request starts together with /whose-call, so look the user up again.
    user = db.users.for_incoming_call(caller_number, called_number)
    if user is None:
        return {}
    notes = crm.notes_about(user.id, caller_number)  # stand-in; can take seconds
    return {"caller_name": notes.name, "last_message": notes.last_message}


@app.post("/mirai/events")
async def events(request: Request):
    raw = await request.body()
    verify_mirai_signature(raw, request.headers)  # stand-in: see Webhooks, signature verification
    event = json.loads(raw)
    if event["type"] == "call.processed":
        call = event["data"]["call"]
        saved = db.calls.get(call["id"])
        if saved and call.get("analysis"):
            db.messages.add(user_id=saved.user_id, call_id=call["id"],
                            summary=call["analysis"].get("summary"),
                            data=call["analysis"].get("data", {}))
    return {"ok": True}

import express from "express";
import { timingSafeEqual } from "node:crypto";

const app = express();
const expected = Buffer.from(`Bearer ${process.env.MIRAI_LOOKUP_KEY}`);

function fromMirai(req) {
  const got = Buffer.from(req.get("Authorization") ?? "");
  return got.length === expected.length && timingSafeEqual(got, expected);
}

app.post("/mirai/whose-call", express.json(), async (req, res) => {
  if (!fromMirai(req)) return res.sendStatus(401);
  const { call_id, caller_number, called_number } = req.body;
  // Stand-in: your user lookup. Keep it to an indexed read; the caller is ringing.
  const user = await db.users.forIncomingCall(caller_number, called_number);
  if (!user) return res.json({ answer: false });
  await db.calls.save({ callId: call_id, userId: user.id });
  res.json({
    answer: true,
    user_id: user.id,
    owner_name: user.firstName,
    greeting: user.greeting, // "Namaste, Asha ji ka assistant bol raha hoon. Aap kaun?"
    instructions: user.instructions.slice(0, 500),
    reply_language: user.replyLanguage, // "Hindi"
    summary_language: user.summaryLanguage, // "English"
    call_settings: {
      voice_id: user.voiceId, // "neha"
      language: user.language, // "hi"
      secondary_languages: user.secondaryLanguages, // ["en"]
    },
  });
});

app.get("/mirai/caller-notes", async (req, res) => {
  if (!fromMirai(req)) return res.sendStatus(401);
  const { caller_number, called_number } = req.query;
  // This request starts together with /whose-call, so look the user up again.
  const user = await db.users.forIncomingCall(caller_number, called_number);
  if (!user) return res.json({});
  const notes = await crm.notesAbout(user.id, caller_number); // stand-in; can take seconds
  res.json({ caller_name: notes.name, last_message: notes.lastMessage });
});

app.post("/mirai/events", express.raw({ type: "application/json" }), async (req, res) => {
  verifyMiraiSignature(req.body, req.headers); // stand-in: see Webhooks, signature verification
  const event = JSON.parse(req.body);
  if (event.type === "call.processed") {
    const call = event.data.call;
    const saved = await db.calls.get(call.id);
    if (saved && call.analysis) {
      await db.messages.add({
        userId: saved.userId,
        callId: call.id,
        summary: call.analysis.summary,
        data: call.analysis.data ?? {},
      });
    }
  }
  res.json({ ok: true });
});

app.listen(3000);

{
  "answer": true,
  "user_id": "usr_2087",
  "owner_name": "Mehul",
  "greeting": "Kem cho, Mehul bhai na assistant sathe vaat karo cho. Aap kon?",
  "instructions": "Mehul is travelling this week. Take a message and the best time to call back.",
  "reply_language": "Gujarati",
  "summary_language": "Gujarati",
  "call_settings": { "voice_id": "sameer", "language": "gu", "secondary_languages": ["hi", "en"] }
}

​

Step 2: Create the agent

{
  "name": "Shared line assistant",
  "first_message": "{{owner.greeting}}",
  "system_prompt": "You answer phone calls for {{owner.owner_name}}. The caller is calling from {{caller_number}}. Find out who is calling and why, and take a short message. {{owner.instructions}} Reply in {{owner.reply_language}}, and switch if the caller does. Never share {{owner.owner_name}}'s personal details or say where they are. Keep replies to one or two short sentences. When you have the message, thank the caller and end the call.",
  "voice": { "voice_id": "neha" },
  "language": "hi",
  "secondary_languages": ["en"],
  "max_duration_secs": 300,
  "draft": false,
  "end_call": { "enabled": true, "confirm": true },
  "tools": [
    {
      "name": "owner",
      "phase": "pre_call",
      "request": {
        "method": "POST",
        "url": "https://api.example.com/mirai/whose-call",
        "headers": { "Authorization": "Bearer {{ secrets.lookup_key }}" },
        "body": {
          "call_id": "{{ call.id }}",
          "caller_number": "{{ vars.caller_number }}",
          "called_number": "{{ vars.called_number }}"
        }
      },
      "response": {
        "select": ["answer", "user_id", "owner_name", "greeting", "instructions", "reply_language", "summary_language"]
      },
      "timeout_ms": 1500,
      "on_failure": "abort"
    },
    {
      "name": "skip_call",
      "phase": "pre_call",
      "condition": { "field": "vars.owner.answer", "op": "is_false" },
      "builtin": { "reason": "Not one of our users' calls" }
    },
    {
      "name": "notes",
      "phase": "pre_call",
      "execution": "async",
      "on_failure": "continue",
      "timeout_ms": 60000,
      "request": {
        "url": "https://api.example.com/mirai/caller-notes",
        "headers": { "Authorization": "Bearer {{ secrets.lookup_key }}" },
        "query": {
          "call_id": "{{ call.id }}",
          "caller_number": "{{ vars.caller_number }}",
          "called_number": "{{ vars.called_number }}"
        }
      },
      "response": { "select": ["caller_name", "last_message"] }
    }
  ],
  "analysis": {
    "enabled": true,
    "prompt": "Summarise the call for {{owner.owner_name}} in two or three sentences: who called, why, and what they asked for. Write the summary in {{owner.summary_language}}.",
    "success_criteria": "The caller's name and the reason for the call were both captured.",
    "output_schema": {
      "type": "object",
      "properties": {
        "caller_name": { "type": "string" },
        "reason": { "type": "string" },
        "callback_requested": { "type": "boolean" }
      }
    }
  }
}

• owner waits for your answer. Its timeout_ms of 1.5 seconds leaves room inside the incoming-call budget, and on_failure: "abort" means a caller is never answered with a greeting that has no user in it. A call your server couldn’t answer ends failed with precall-tool-failed.
• The call_settings in your answer set the voice and languages. select doesn’t need to name them. See Set the voice and language for the call.
• skip_call runs after owner and turns the call away when your server answered "answer": false. The call ends aborted with skipped-by-condition, and nothing is charged.
• notes runs in the background, so it never holds the answer. It reads the call’s own variables only: a background tool can’t read owner’s values, because both start together. When it answers, the agent gets the caller’s name and last message. See Run a slow lookup in the background.
• analysis.prompt reads {{owner.summary_language}}, so each summary is written in that user’s language. See Variables in the prompt.
• The agent’s own voice and language are what a call uses when your answer leaves call_settings out.

​

Step 3: Store the key, create the agent and point the number at it

set -euo pipefail
: "${MIRAI_API_BASE:?}" "${MIRAI_API_KEY:?}" "${MIRAI_LOOKUP_KEY:?}" "${NUMBER_ID:?}"
AUTH="Authorization: Bearer $MIRAI_API_KEY"

jq -n '{value: env.MIRAI_LOOKUP_KEY}' |
  curl --fail-with-body -sS -X PUT "$MIRAI_API_BASE/v2/secrets/lookup_key" \
    -H "$AUTH" -H 'Content-Type: application/json' --data-binary @- > /dev/null

AGENT_ID=$(curl --fail-with-body -sS "$MIRAI_API_BASE/v2/agents" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  --data-binary @shared-line-agent.json | jq -er '.id')

NUMBER=$(curl --fail-with-body -sS "$MIRAI_API_BASE/v2/phone-numbers/$NUMBER_ID" -H "$AUTH")
jq --arg agent "$AGENT_ID" --arg url "https://api.example.com/mirai/events" \
  '{version, agent_id: $agent, webhook_url: $url}' <<< "$NUMBER" |
  curl --fail-with-body -sS -X PATCH "$MIRAI_API_BASE/v2/phone-numbers/$NUMBER_ID" \
    -H "$AUTH" -H 'Content-Type: application/json' --data-binary @- |
  jq '{id, number, agent_id, state}'

import json
import os
from pathlib import Path

import httpx

api = httpx.Client(
    base_url=os.environ["MIRAI_API_BASE"],
    headers={"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"},
    timeout=30,
)

api.put("/v2/secrets/lookup_key",
        json={"value": os.environ["MIRAI_LOOKUP_KEY"]}).raise_for_status()

agent = api.post("/v2/agents",
                 json=json.loads(Path("shared-line-agent.json").read_text()))
agent.raise_for_status()
agent_id = agent.json()["id"]

number_id = os.environ["NUMBER_ID"]
number = api.get(f"/v2/phone-numbers/{number_id}").raise_for_status().json()
number = api.patch(f"/v2/phone-numbers/{number_id}", json={
    "version": number["version"],
    "agent_id": agent_id,
    "webhook_url": "https://api.example.com/mirai/events",
}).raise_for_status().json()
print(number["number"], number["agent_id"], number["state"])

import { readFile } from "node:fs/promises";

const { MIRAI_API_BASE, MIRAI_API_KEY, MIRAI_LOOKUP_KEY, NUMBER_ID } = process.env;

async function api(method, path, body) {
  const res = await fetch(`${MIRAI_API_BASE}${path}`, {
    method,
    headers: { Authorization: `Bearer ${MIRAI_API_KEY}`, "Content-Type": "application/json" },
    body: body === undefined ? undefined : typeof body === "string" ? body : JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) throw new Error(`${method} ${path}: ${JSON.stringify(json)}`);
  return json;
}

await api("PUT", "/v2/secrets/lookup_key", { value: MIRAI_LOOKUP_KEY });
const agent = await api("POST", "/v2/agents", await readFile("shared-line-agent.json", "utf8"));

const current = await api("GET", `/v2/phone-numbers/${NUMBER_ID}`);
const number = await api("PATCH", `/v2/phone-numbers/${NUMBER_ID}`, {
  version: current.version,
  agent_id: agent.id,
  webhook_url: "https://api.example.com/mirai/events",
});
console.log(number.number, number.agent_id, number.state);

​

Step 4: Read each call’s result

{
  "id": "call_01K8F2A7C9E1G3J5L7N9Q1S3U5",
  "direction": "inbound",
  "from": "+919876543210",
  "status": "completed",
  "call_settings": {
    "voice_id": "sameer",
    "language": "gu",
    "secondary_languages": ["hi", "en"],
    "sources": { "voice_id": "pre_call:owner", "language": "pre_call:owner", "secondary_languages": "pre_call:owner" }
  }
}

​

Step 5: End a call from your app

curl --fail-with-body -X POST "$MIRAI_API_BASE/v2/calls/$CALL_ID/abort" \
  -H "Authorization: Bearer $MIRAI_API_KEY"

import os

import httpx

r = httpx.post(
    f"{os.environ['MIRAI_API_BASE']}/v2/calls/{call_id}/abort",
    headers={"Authorization": f"Bearer {os.environ['MIRAI_API_KEY']}"},
    timeout=30,
)
if r.status_code != 409:  # 409: the call had already ended
    r.raise_for_status()

const res = await fetch(`${process.env.MIRAI_API_BASE}/v2/calls/${callId}/abort`, {
  method: "POST",
  headers: { Authorization: `Bearer ${process.env.MIRAI_API_KEY}` },
});
if (!res.ok && res.status !== 409) throw new Error(`abort failed: ${res.status}`); // 409: already ended

​

Test it

{
  "name": "Shared line test",
  "first_message": "The secret word is {{echo.word}}. You called from {{caller_number}}.",
  "system_prompt": "You are a test assistant. Answer in one short sentence. If you learn the caller's name, use it when they ask who they are.",
  "voice": { "voice_id": "neha" },
  "language": "hi",
  "max_duration_secs": 120,
  "draft": false,
  "tools": [
    {
      "name": "echo",
      "phase": "pre_call",
      "request": {
        "url": "https://httpbin.org/anything",
        "query": { "word": "PINEAPPLE", "voice": "sameer", "lang": "gu", "summary": "Gujarati" }
      },
      "response": {
        "transform": "{word: .args.word, summary_language: .args.summary, call_settings: {voice_id: .args.voice, language: .args.lang}}",
        "select": ["word", "summary_language"]
      },
      "on_failure": "abort"
    },
    {
      "name": "slow",
      "phase": "pre_call",
      "execution": "async",
      "timeout_ms": 20000,
      "request": { "url": "https://httpbin.org/delay/5", "query": { "caller_name": "Ravi" } },
      "response": { "transform": "{caller_name: .args.caller_name}", "select": ["caller_name"] }
    }
  ],
  "analysis": {
    "enabled": true,
    "prompt": "Summarise the call in one sentence. Write the summary in {{echo.summary_language}}."
  }
}

1. Call the number. The agent says “The secret word is PINEAPPLE. You called from” and your number, in the sameer voice.
2. Read the call with GET /v2/calls/{id}. call_settings.sources shows pre_call:echo for voice_id and language.
3. Wait about five seconds into the call and ask “Who am I?”. The agent answers “Ravi”, from the background tool.
4. Hang up. The summary in GET /v2/calls/{id}/analysis is in Gujarati. Change summary to Tamil, call again, and the next summary is in Tamil.
5. Change voice to robot and call. The agent speaks in neha, the agent’s own voice. The echo receipt in GET /v2/calls/{id}/tool_runs has a warning naming call_settings.voice_id.
6. Call again and, while the agent talks, send POST /v2/calls/{id}/abort. The call hangs up and ends aborted.

​

Privacy and compliance

• The caller’s number goes to your server on every call. Treat it as personal data: keep it only as long as you need it and protect it like the rest of your user records.
• Caller ID can be faked. Use it to choose a greeting and settings, never as proof of who is calling. Don’t let the agent read out a user’s private details because of the caller’s number alone.
• Tell callers they’re speaking with an AI voice agent, and give a recording notice if you record. Your greeting is the place for both.
• The callers are usually not your users and have no account with you. Their words reach your users as summaries, so tell your users what is stored and for how long, and honour the data protection law that applies to you, such as India’s DPDP Act or GDPR.
• Keep lookup_key in workspace secrets. Never put keys in prompts or variables. Check webhook signatures on every event.
• Transcripts, recordings and summaries are kept for 90 days with the call. Copy what you need into your own system.

​

Production checklist

• whose-call answers in well under 1.5 seconds at your busiest hour, including the network between us and your server.
• Every user has a voice and languages your server can send, and the receipts of test calls carry no warnings.
• Calls that aren’t your users’ answer "answer": false, and you’ve tested that the caller is not answered.
• The background lookup has a timeout_ms that fits it, and the agent copes when its values never arrive.
• Summaries arrive in each user’s language on test calls for at least two languages.
• Webhooks are verified, deduplicated on the event id, and matched to users by the call id saved during the lookup.
• Your app can end a call with POST /v2/calls/{id}/abort, and you’ve tested it on a live call.

​

Related