Concepts

Agents are contacts, not bots — the model behind the nmbr Agent API in five minutes.

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.

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.

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.