Welcome Message - Aion Docs

Metadata

Field	Value
Canonical URI	`https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0`
Issuer	`aion`
Version	`1.0.0`
Activation	This extension will only activate when specified.
Related Extensions	Distribution, Distribution/Messaging

Overview

Welcome Message requests an opening response from an agent. The request and response belong to the ordinary conversation and its history. Fetching an Agent Card, opening existing history, or reconnecting does not invoke it. The agent decides how to generate the welcome, including which tools or capabilities to use. Personalization and provider context continue to use the Distribution extension.

Agent Card Declaration

Receivers implementing this contract advertise optional support:

{
  "capabilities": {
    "extensions": [
      {
        "uri": "https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0",
        "description": "Generate an opening message for a new conversation.",
        "required": false
      }
    ]
  }
}

Aion advertises this extension for A2A, Aion Chat, Slack, and Telegram Bot distribution routes only when a middleware or terminal behavior on that route implements it. A distribution declaration alone does not establish support. Slack and Telegram retain internal capability metadata without becoming public A2A endpoints. Clients use the card for their selected route. GraphQL chat clients resolve a2aAgentCardUrl with the same target and principal used for messaging. An identity’s preferred card URL may represent a different distribution. Voice does not advertise or dispatch this extension. It continues speaking its separately configured distribution welcomeMessage through the voice session’s existing playback path.

Activation

Producers send both the request-scoped A2A-Extensions header and the URI in message.extensions:

A2A-Extensions: https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0

For GraphQL, put the URI in serviceParameters.extensions and in message.extensions. Receivers recognize either explicit activation signal. A data part or metadata key alone does not activate welcome. Do not retain this activation on subsequent ordinary user requests.

Payloads

WelcomeRequestPayload

Schema URI: https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0#WelcomeRequestPayload An activated welcome request contains exactly one welcome-owned data part and no nonblank text part. Other extension-owned parts, including provider events, may accompany it. There are no personalization fields. Placement summary:

WelcomeURI: https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0
Payload location: message.parts[i].data
Schema location: message.parts[i].metadata[WelcomeURI].schema
Activation locations: A2A-Extensions and message.extensions

For JSON-RPC, message is inside params; for HTTP+JSON, it is in the request body. Do not place this payload in request-level metadata or message.metadata. Both SendMessage and SendStreamingMessage use this shape.

Payload Shape

{
  "type": "welcome-request"
}

Fields

Field	Type	Required	Description
`type`	`String`	required	Must be `welcome-request`; requests an opening conversation message.

The enclosing part’s metadata[WelcomeURI].schema must equal the Schema URI above. The schema reference identifies the part’s extension ownership; data.type alone is insufficient. Neither field activates the extension by itself.

Processing Rules

If the request contains nonblank user text, answer that text normally. This takes precedence even if welcome metadata is malformed or welcome support is disabled. Do not mark that ordinary response as a welcome.
Otherwise, an explicitly activated request must have the valid schema-tagged data part and an enabled receiver. Reject invalid or disabled welcome requests through the normal invalid-parameters error path before agent execution.
Generate the welcome through the agent implementation. Keep the ordinary context and response persistence.
Complete a successful welcome task. It must not remain waiting for user input; the user’s next message continues the conversation through the normal task lifecycle.
Explicitly mark every response message intended as welcome output, as shown below.

Activation acknowledgment and message provenance are distinct. An A2A-Extensions response header can acknowledge activation, but does not identify a particular message as intentional welcome output. Generic response processing must not add this URI to every message simply because the request activated it.

Response Message

Return an ordinary Message or completed Task. Each intentional welcome Message carries the URI in its own extensions, including messages within a Task’s history or status. No separate response payload is required. Preserve these message annotations through adapters, delivery, history, and replay. Do not relabel earlier messages.

Example: Welcome SendMessage

This A2A 1.0 JSON-RPC request uses a client-assigned context before any request is dispatched. The URL and token are placeholders; apply the receiver’s normal authentication in addition to extension activation.

POST /a2a HTTP/1.1
Host: agent.example.com
Content-Type: application/json
Authorization: Bearer <aion-token>
A2A-Extensions: https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0

{
  "jsonrpc": "2.0",
  "id": "welcome-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "welcome-request-001",
      "contextId": "chat-context-001",
      "role": "ROLE_USER",
      "extensions": [
        "https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0"
      ],
      "parts": [
        {
          "data": {
            "type": "welcome-request"
          },
          "metadata": {
            "https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0": {
              "schema": "https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0#WelcomeRequestPayload"
            }
          }
        }
      ]
    }
  }
}

In the 0.3 representation, use role: "user", kind: "message", and kind: "data" on the corresponding objects. The extension URI, schema reference, and context ID stay the same. Both unary and streaming receivers can handle welcome intent; Aion’s chat clients initiate welcomes with unary SendMessage.

Response Example

The response uses the normal A2A result envelope. Its Message carries the welcome annotation:

{
  "jsonrpc": "2.0",
  "id": "welcome-1",
  "result": {
    "message": {
      "messageId": "welcome-response-001",
      "contextId": "chat-context-001",
      "role": "ROLE_AGENT",
      "extensions": [
        "https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0"
      ],
      "parts": [
        {
          "text": "Hello! How can I help?"
        }
      ]
    }
  }
}

For 0.3, use role: "agent", kind: "message", and kind: "text".

Agent Implementations

Control Plane Agents

The following control plane agents implement this extension:

Prompt Agent uses the configured content or instructions alongside its ordinary system prompt to generate the welcome response.
Hello World returns the configured text directly for protocol and UI testing. Ordinary text requests keep its configured echo behavior.

Configure WelcomeMessage on either agent:

Property	Value
Key	`WelcomeMessage`
Type	`String`
Required	No; nullable, with no default.
Maximum Length	5,000 characters.
Description	Content or instructions for the agent’s opening message when a new conversation starts.

A nonblank value enables support and advertises the extension. Missing or blank values disable support. Both implementations trim surrounding whitespace and preserve Markdown inside the value. In both cases, the response is part of the conversation, not a static client banner.

Python SDK

Opt in through aion.yaml:

enabled_extensions:
  - https://docs.aion.to/a2a/extensions/aion/welcome-message/1.0.0

The runtime validates the payload and exposes WelcomeRequestPayload through context.extensions.get(uri). The implementer decides how to respond and completes through the existing task API. The SDK does not generate a welcome automatically. Use context.extensions.is_active(uri) to recognize validated welcome intent; actual user text follows ordinary handling. Set the URI explicitly on the response Message’s extensions before emitting it.

Client And Provider Triggers

Surface	Trigger and behavior
Aion Chat React	Explicit new conversation creation checks the selected route card and sends one unary welcome.
Python SDK terminal chat	`/clear` creates a context and sends one unary welcome if the connected card supports it.
Slack	`im_created` for a new DM requests a welcome when the current downstream route supports it.
Telegram Bot	Every distinct private, parameterless `/start` requests a welcome on a supporting route.

Chat clients allocate the context before sending. An immediate user message uses that same context while the welcome is pending. Ordinary chat remains available; welcome and user responses may arrive out of order. A late welcome stays in its original conversation and does not change the foreground request’s task state. The synthetic, schema-tagged request is hidden from the chat transcript, while protocol inspection and stored history retain it. Real user text remains visible. There is no separate welcome-disable setting and no client retry. Restoration, reconnect, and capability refresh do not send another welcome.

Slack

Only im_created triggers this feature. im_open, app_home_opened, and assistant_thread_started do not. The event uses the existing authenticated, deduplicated event ingress and normal DM response delivery. No separate initialization marker is stored, and no source-message timestamp is fabricated for the channel-creation event. The generated app manifest includes im_created; its im:read scope is already part of Aion’s baseline. For an existing app, add im_created to its bot event subscriptions or apply the updated manifest before expecting welcomes. Projection checks detect the outdated subscription; automatic manifest updates are not performed by the current managed-app reconciler. Verify delivery in the installed workspace during rollout. See Slack’s im_created reference.

Telegram Bot

Bare /start, correctly bot-addressed /start@BotUsername, and trailing whitespace are accepted. Commands with parameters, group commands, and unsupported downstream routes keep their ordinary command handling. Commands addressed to another bot keep the existing rejection behavior. Repeated distinct starts reuse the existing chat context; they do not reset it. Provider redelivery is handled by existing update deduplication. Merely opening or deleting a chat does not trigger this feature. See Telegram’s bot commands.

​Overview

​Agent Card Declaration

​Activation

​Payloads

​WelcomeRequestPayload

​Payload Shape

​Fields

​Processing Rules

​Response Message

​Example: Welcome SendMessage

​Response Example

​Agent Implementations

​Control Plane Agents

​Python SDK

​Client And Provider Triggers

​Slack

​Telegram Bot