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
| Field | Type | Description |
|---|---|---|
action | agent | oneshot | message | silence, nullable | What 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_id | string, nullable | The agent that answers, when action is agent or oneshot. |
text | string, nullable | The fixed text delivered, when action is message. |
repeat | every | once | object | How often a message fires: every (default), once, or { after_seconds }. Null unless action is message. |
language | string, nullable | Preferred reply language; null lets the agent decide. |
config | object, nullable | Conversation 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. |
id | string | Public address ID. |
project_id | string | The owning project. |
identifier | string | The prefixed, self-describing channel identifier. |
display_name | string, nullable | A human-friendly name, as the channel reported it. |
actor_id | string, nullable | The actor this address speaks as: the one bound with actor_id, else one naturali creates when it first needs it (null until then). |
created_at | string (date-time) | |
updated_at | string (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:
- CLI
- SDK
- curl
naturali set-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999999999 \
--action agent \
--agent-id agent_V1StGXR8Z5jdHi6B
const { data: address } = await naturali.channels.setAddress({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
identifier: 'whatsapp:dm:5511999999999',
},
body: { action: 'agent', agent_id: 'agent_V1StGXR8Z5jdHi6B' },
});
curl -X PUT https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/addresses/whatsapp%3Adm%3A5511999999999 \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "action": "agent", "agent_id": "agent_V1StGXR8Z5jdHi6B" }'
Hold a non-subscriber with a paywall message instead of an agent, once:
- CLI
- SDK
- curl
naturali set-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999999999 \
--action message \
--text 'Subscribe at https://example.com/pricing' \
--repeat once
await naturali.channels.setAddress({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
identifier: 'whatsapp:dm:5511999999999',
},
body: {
action: 'message',
text: 'Subscribe at https://example.com/pricing',
repeat: 'once',
},
});
curl -X PUT https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/addresses/whatsapp%3Adm%3A5511999999999 \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"action": "message",
"text": "Subscribe at https://example.com/pricing",
"repeat": "once"
}'
Make an address speak as your own actor:
- CLI
- SDK
- curl
naturali set-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999998888 \
--actor-id actor_V1StGXR8Z5jdHi6B
await naturali.channels.setAddress({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
identifier: 'whatsapp:dm:5511999998888',
},
body: { actor_id: 'actor_V1StGXR8Z5jdHi6B' },
});
curl -X PUT https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/addresses/whatsapp%3Adm%3A5511999998888 \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "actor_id": "actor_V1StGXR8Z5jdHi6B" }'
Erase an address — its conversations and sessions, and the actor naturali created for it:
- CLI
- SDK
- curl
naturali delete-address \
--project-id proj_V1StGXR8Z5jdHi6B \
--identifier whatsapp:dm:5511999999999
await naturali.channels.deleteAddress({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
identifier: 'whatsapp:dm:5511999999999',
},
});
curl -X DELETE https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/addresses/whatsapp%3Adm%3A5511999999999 \
-H "Authorization: Bearer $NATURALI_TOKEN"