Skip to main content

Addresses

The identifier as a first-class resource — created before any message arrives, and the one place a customer's own admission decision lives.

Overview​

An address is what an identifier names: a place a conversation can happen — sometimes a person's DM, sometimes a room a Discord server shares. It is project-scoped, keyed by the prefixed, self-describing identifier a channel adapter produces (whatsapp:dm:<phone>, discord:dm:<user_id>, discord:thread:<guild_id>:<channel_id>, x:dm:<user_id>). A first message answered by an agent creates one: Connect a Discord channel reads its address_id and identifier off the conversation a DM opened.

PUT /v1/projects/{project_id}/addresses/{identifier} is the write a customer's own application makes when it learns something about an identifier — a payment cleared, a plan lapsed, an abuse report. It is a one-call upsert keyed by the identifier: no read first, and no 404 for one that has never written, because at the moment a payment clears the customer's backend knows the identifier and does not know whether naturali has ever seen it. An identifier no channel kind produces is 400.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Addresses.

Data Model​

Address​

FieldTypeDescription
actionagent | oneshot | message | silence, nullableWhat an inbound message becomes; null only on an address with no action of its own, which the route table then decides. agent is a dialogue: the identity behind the message gets a session, and every later message on it continues the same one. oneshot runs the agent once and keeps nothing — no address, no actor, no session, no conversation — so each message is answered on its own. Choose it for work that is filed rather than discussed; choose agent when the answer depends on what came before. message delivers fixed text without running an agent, and silence answers nothing.
agent_idstring, nullableThe agent that answers, when action is agent or oneshot.
textstring, nullableThe fixed text delivered, when action is message.
repeatevery | once | objectHow often a message fires: every (default), once, or { after_seconds }. Null unless action is message.
languagestring, nullablePreferred reply language; null lets the agent decide.
configobject, nullableConversation config bag — media handling, persona overrides, the Discord allowlist, and how a oneshot answers. discord.reply picks the delivery: react (the default) adds discord.reaction — \u2705 unless named — to the message that triggered the run, mention answers beside it addressing whoever asked, react_or_mention reacts when the agent writes nothing and answers like mention when it writes a line, thread opens a thread and answers inside it, and none delivers nothing at all. A run that fails delivers nothing in every mode, so a reaction always means the work was done; there is no failure marker. A mention with nothing else in it is ignored unless the action says otherwise, for any action. discord.use_replied_message: true takes the text of the message it replies to, so replying to a message with only the mention files that message. discord.empty_mention_text answers any other bare mention with that fixed text, addressing the sender, without running the agent. discord.forward_user_id: true hands the sender's Discord user id to the agent's tools as the discord_user_id tool context, which a tool's headers read as {{context:discord_user_id}}. It is the id Discord reported for the message's author, never text the model wrote, so a tool can act for whoever sent it. Off unless set, because tool context reaches every tool the agent has. Read only for oneshot. A conversational agent in a guild is its thread — that is what its session is keyed on — so it always opens one.
idstringPublic address ID.
project_idstringThe owning project.
identifierstringThe prefixed, self-describing channel identifier.
display_namestring, nullableA human-friendly name, as the channel reported it.
actor_idstring, nullableThe actor this address speaks as: the one bound with actor_id, else one naturali creates when it first needs it (null until then).
created_atstring (date-time)
updated_atstring (date-time)

Key Concepts​

The address's action beats everything​

Resolution checks the address first: if it has an action, that wins outright, ahead of every route and the channel default. action: silence is how you block someone — abuse, an erasure in flight. action: null forgets the exception, so the route table decides again.

repeat, for a message action​

Left alone, ten inbound messages produce ten identical refusals. every (the default) delivers on every inbound and writes no state; once delivers once then stays silent; { "after_seconds": N } delivers at most once per window. Editing the text, or resolving to a different action, resets the clock immediately.

Speak as your own actor​

By default an address gets an actor of its own, so the same person on WhatsApp and in your app's sessions is two actors, with quotas, memory and history split between them. Send actor_id on the PUT and the address speaks as an actor of yours instead.

Create that actor with your user id as its external_id: every tool call in the address's sessions carries X-Naturali-Context-actor_id and X-Naturali-Context-actor_external_id, set from the actor and never from anything a caller sends, so your tool knows which user is talking.

A session's actor is fixed, so changing it deletes the address's conversations and their sessions, and the next message opens a fresh one. The actor naturali created is deleted with them; an actor you bound never is. actor_id: null releases yours. An actor naturali created for another address answers 409 ACTOR_MINTED_FOR_ADDRESS. Recognise one user across a channel and your app links them end to end.

Erasure is narrower than "erase this human"​

DELETE /v1/projects/{project_id}/addresses/{identifier} removes the address, its conversations and sessions, and the actor naturali created for it — an actor you bound is yours and stays. Without a merge graph, naturali does not know that two identifiers are the same person, so this is a promise about this address, not about a human across every channel they have ever used.

To forget one dialogue and keep the address, delete the conversation instead: DELETE /v1/projects/{project_id}/channels/{channel_id}/conversations/{conversation_id}.

Examples​

Admit an identifier the moment a payment clears — one call, no prior read:

naturali set-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999999999 \
--action agent \
--agent-id agent_V1StGXR8Z5jdHi6B

Hold a non-subscriber with a paywall message instead of an agent, once:

naturali set-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999999999 \
--action message \
--text 'Subscribe at https://example.com/pricing' \
--repeat once

Make an address speak as your own actor:

naturali set-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999998888 \
--actor-id actor_V1StGXR8Z5jdHi6B

Erase an address — its conversations and sessions, and the actor naturali created for it:

naturali delete-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999999999