Channels

Set or clear this address's own action or actor

Upserts the address with its action, the actor it speaks as, or both; a field left out is left alone. action: null forgets the exception and defers back to the route table; any other action requires the same fields a route or channel default would (agent_id for agent, text for message).

actor_id binds an actor of this project, so the address speaks as the same actor your own sessions use. A changed actor deletes the address's conversations and their sessions — a session's actor is fixed — and the next message opens a fresh one; the actor naturali created for the address is deleted with them. An actor you bind is never deleted here.

put/v1/projects/{project_id}/addresses/{identifier}

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/addresses/{identifier}
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

actor_idstring nullable

An actor of this project for the address to speak as, 404 when the project has none by that id. Create it with your own user id as its external_id: every tool call in the address's sessions carries that actor's actor_id and actor_external_id as tool context, set by the runtime and never by the caller, so a tool knows which of your users is talking.

null releases a bound actor (kept, not deleted); the next message gets an actor naturali creates.

action'agent' | 'oneshot' | 'message' | 'silence' | 'null' nullable

What an inbound message becomes.

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
textstring
languagestring
configobject

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.

display_namestring

Set only when the address is created by this call.

Example request

{
  "actor_id": "actor_V1StGXR8Z5jdHi6B",
  "action": "agent",
  "agent_id": "agent_V1StGXR8Z5jdHi6B",
  "text": "Subscribe at https://example.com/pricing",
  "language": "en-US",
  "display_name": "Ana"
}

Response

Action updated.

action'agent' | 'oneshot' | 'message' | 'silence' | 'null' nullable required

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_idstring nullable required

The agent that answers, when action is agent or oneshot.

textstring nullable required

The fixed text delivered, when action is message.

languagestring nullable required

Preferred reply language; null lets the agent decide.

configobject nullable required

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.

idstring required
project_idstring required
identifierstring required
display_namestring nullable required
actor_idstring nullable required

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_atstring date-time required
updated_atstring date-time required

Example response

{
  "action": "agent",
  "agent_id": "agent_V1StGXR8Z5jdHi6B",
  "text": "Subscribe at https://example.com/pricing",
  "language": "en-US",
  "config": {
    "media": {
      "audio": "transcribe"
    },
    "discord": {
      "allowed_role_ids": [
        "1290000000000000042"
      ]
    }
  },
  "id": "addr_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "identifier": "whatsapp:dm:5511999998888",
  "display_name": "Ana",
  "actor_id": "actor_V1StGXR8Z5jdHi6B"
}

Changes

No recorded changes to this operation across all 1 revision of this API.