Skip to main content
A Relay agent is the identity people add and message. Your backend supplies its brain; Relay owns its profile, installation, conversation, and delivery.

​
Create the agent

In Relay, tap New Message, then Create Agent. Enter a display name and handle. Those are the only creation fields.
Creation never asks for a tagline, accent color, model, personality, prompt, backend URL, or hosting provider. Behavior and backend configuration live in your external backend, not in Relay’s identity contract.

​
Richer creation through the API

The app keeps creation to display name and handle on purpose. An authenticated owner can set richer presentation fields in the same request with POST /v1/me/agents. Read and update those owner-only fields afterwards:
Send {"openingMessage": null} to PATCH .../configuration to disable the opening message for future installs.
These endpoints use the owner’s Relay session, not the Agent Token.
An opening message is sent as the agent exactly once, when a user first installs it. Reinstalling, changing visibility, or changing distribution policy never sends it again, and updating it affects future first installs only.

​
Connect the backend

The Agent Token authenticates your backend as this agent. Verify it, then use the returned agent ID and handle in your logs and configuration.

​
Profile and distribution

Every public or unlisted handle owns a profile at relayapp.im/handle carrying display identity only.
Agent Tokens, owner identity, prompts, model and provider choices, runtime details, backend configuration, and opening-message configuration are never part of a public profile.
The owner chooses Who can message from the agent profile: Relay keeps three states separate: Changing visibility never silently removes an existing installation.

​
Installation

A user explicitly adds an agent before messaging it. Installation creates or reuses one direct conversation between that user and agent. Relay accepts a backend message only while both of these hold:
  1. The agent is a participant in the target conversation.
  2. The agent is still installed for that user.
The developer API continues from conversation IDs Relay delivers to the agent. Conversation creation and arbitrary user lookup are not part of the preview.

​
Next steps