# Concepts

> Agents are contacts, not bots — the model behind the nmbr Agent API in five minutes.
>
> Markdown mirror of https://nmbr.ai/developers/docs/concepts/ — part of the nmbr Agent API docs (https://nmbr.ai/developers/docs/). Spec: https://nmbr.ai/developers/openapi.yaml · Site index: https://nmbr.ai/llms.txt

## An agent is a first-class account

Your agent is a real nmbr user with `userType: "agent"`: it has an `800-xxx-xxx` nmbr, a profile (name, bio, avatar), and it rides every rail a person does — message types, push notifications, encryption at rest, both apps. There is no separate "bot" infrastructure and nothing for you to host except the agent itself.

Agents are created **only by humans, in the app** (Agents → Yours). There is no create-agent endpoint and an agent token cannot mint tokens — a leaked or prompt-injected agent cannot multiply itself. Each person can own a few agents; agent nmbrs are random and free.

## Tokens

`Authorization: Bearer agent:…` on every request. Tokens are shown once, stored hashed, and revocable one at a time or all at once from the app. An agent token opens **only** `/api/agent/v1/*`; it is rejected everywhere else, and human credentials are rejected on the agent surface. Suspending the owner cuts off every agent they own.

## Who can talk to your agent

Adding your agent as a contact *is* the install. People add it by nmbr; the request is accepted on the spot, subject to the agent's `requestPrivacy` (`everyone`, `contacts_of_contacts`, `nobody` — set it via `PATCH /me` or in the app). Your agent can message only people who added it (`not_a_contact` otherwise), and they can remove or block it like any contact. That is the whole permission model in v1: no allowlist code, no open world.

## Conversations

Everything in v1 is **1:1**. A conversation is identified by `conversationId`; you can address a message by `to` (a nmbr) or by `conversationId`, never both. Replies (`replyToId`) must point at a message in the same conversation. Group chats an agent is a member of are not evented yet.

## Events

Anything your agent should know about becomes an event: `message.received`, `contact.added`, `action.approved` / `action.rejected` / `action.expired`. Events have a global monotonic `seq`, which is also the long-poll cursor. Read them by **long-poll** (`GET /updates?afterSeq=&wait=`) or receive them by **signed webhook** — same envelope either way. Details: [Events & webhooks](/developers/docs/events/).

## Approvals

Your agent **proposes**; a person **decides** on a native card in the chat; the decision comes back as an event. nmbr never executes the action. Details: [Approvals](/developers/docs/approvals/).

## Limits

Per agent: 300 requests/min, 60 messages/min, 20 messages/min per recipient (proposals count as messages), 10 pending proposals per conversation, 16 KB proposal payloads. A `429` carries `Retry-After`. Error responses are always `{ "error": { "code", "message" } }` with a stable `code` — build on the code, not the message.

## The plaintext boundary (read this)

Messages are encrypted at rest and only ever decrypted inside nmbr's servers — *except* for your agent: to talk to it, nmbr sends the plaintext of the conversation to the token holder, on the infrastructure you chose. This is deliberate, scope-limited (1:1s with people who added the agent), and audited — and it means the agent API is **not end-to-end encrypted**. The person adding your agent trusts you with that conversation. Say so in your agent's bio. More in [Security](/developers/docs/security/).