Skip to main content
An Agent Token is scoped to a single Relay agent. It grants no access to a Relay user account, the directory, another agent, or Relay’s database.

​
What the backend receives

Your backend receives this for an active conversation: Message and receipt payloads carry a stable Relay user ID.

​
Conversation access

Request only the history the current task needs. A conversation in Relay does not authorize indefinite retention in an external system.

​
Contact discovery

Consumer contact discovery matches registered contacts. Relay returns a profile when a submitted address-book number belongs to another registered Relay user with a verified phone number. The matched user never has to submit the caller’s number.

​
Public profiles

GET /v1/agents/{handle}/profile resolves human usernames and agent handles alike, without authentication. A suspended or retired handle answers 404. Human profiles return null for the agent-only tagline, accent color, and creator fields. Reading a profile never installs or removes an agent for a user.
Tokens, system prompts, provider configuration, and backend details are never exposed through any public route.

​
Attachments

Attachment metadata is visible only to its uploader. Message parts may carry an unguessable capability URL so Relay clients can render the bytes without putting a session or Agent Token in the URL.
Treat capability URLs as secrets. Keep them out of analytics, public logs, model-training corpora, and any response outside the conversation that supplied them.

​
Removal and blocking

An old conversation ID preserves no permission. Relay checks authorization on every write.
The current webhook catalog does not emit installation, removal, blocking, or account-deletion events. Install lifecycle events are on the API availability.

​
Retention and deletion

Relay stores the transcript needed to operate the messenger. Your backend is an independent system. Any message, attachment, or derived memory copied there falls under your own retention and deletion behavior. Account deletion commits database removal before returning, then attempts external R2 and agent-runtime cleanup. The response reports which stage it reached: Each response includes a non-secret cleanup.receipt_id. A pending receipt is not completion. Relay retains a de-identified retry record until every target is cleared.
Relay cannot erase copies your backend holds. Until Relay exposes a developer-facing deletion event, state that in your retention policy and give users a direct deletion path for the data you store.

​
See also