Messaging Client

ApolloMessagingClient is the browser-safe client for end-user messaging. It authenticates with your publishable key, exchanging it for a short-lived access token internally — the agent comes from the key, never from request bodies.

import { ApolloMessagingClient } from '@aui.io/aui-client';

const client = new ApolloMessagingClient({ publishableKey: 'pk_network_...' });

All methods are async, fully typed, and throw typed errors on failure. Request and response models are exported under the Apollo namespace.

Want to see the responses before you write code? Every call on this page is a button in the Apollo Agent Tester — paste your publishable key and try sends, streams, traces and channels against your own agent.

Send a message

Omit thread_id to start a new conversation, or pass it to continue one.

const response = await client.messaging.sendMessage({
  user_id: 'end-user-123',
  text: 'I want to dispute a charge',
  // thread_id: existingThreadId,
});

console.log(response.thread_id);       // the (possibly new) thread
console.log(response.message.text);    // the agent's reply
console.log(response.message.id);      // interaction id — for reruns and traces

When the agent surfaces entities — products, bookings, search results — the reply carries them as cards. Each card holds the same entity in two self-contained representations, so you pick what fits your stack: a ready-to-render JSX string for React, or structured JSON for any other framework — see Cards for the full shape.

for (const card of response.message.cards ?? []) {
  card.rendered_jsx;              // ready-to-render JSX (React)
  card.json_data?.entity;         // flat key–value fields (any framework)
  card.json_data?.sub_entities;   // nested groups, e.g. product variants
  card.is_recommended;            // the agent's top pick
  card.title;                     // the card's authored title
  card.capability;                // which agent capability produced it — pick a widget template by it
  card.instance;                  // the specific record the card is about, if any
}

title, capability, and instance are optional and may be null — read them defensively. Pass structured data the caller should not have to state — the signed-in user, the account in view, what your systems already know — as agent_variables: a flat Record<string, unknown> whose keys are the context variables the agent’s program declares. Attach an image for the agent to reason over with image_url:

await client.messaging.sendMessage({
  user_id: 'end-user-123',
  text: 'Where is my order?',
  agent_variables: {
    'customer.id': 'CUST-1042',
    'order.id': 'ORD-1042',
  },
  // image_url: 'https://…/receipt.jpg',  // vision input, optional
});

Send requests also accept an optional runtime_version — an advanced build pin for the turn; normally omit it.

Stream a message

streamMessage is the streaming transport: one HTTP call per turn that returns the reply as an async-iterable stream of Server-Sent Events — token deltas while the agent works, then the complete message, then ready-made follow-up suggestions. It takes the same request body and auth as sendMessage, leaves you no connection to keep alive, and resumes after a drop without re-running the turn:

const stream = await client.messaging.streamMessage({
  body: { user_id: 'end-user-123', text: 'Tell me about my account' },
});

for await (const event of stream) {
  switch (event.type) {
    case 'thread':                       // first event: the resolved thread id
      console.log(event.data.thread_id);
      break;
    case 'event':                        // token deltas carry data.text
      // data is typed Record<string, unknown> — cast before use
      process.stdout.write(String(event.data.text ?? ''));
      break;
    case 'message':                      // terminal event: the full reply
      console.log('\n', event.data.text);
      break;
    case 'suggestions':                  // optional final event: follow-up prompts
      console.log(event.data.followup_suggestions);
      break;
    case 'error':                        // the turn failed mid-stream
      console.error(event.data);
      break;
  }
}

Ready-made follow-up prompts arrive automatically as the suggestions frame after the terminal message — render them as tappable chips, no extra call needed. Its data carries followup_suggestions alongside the thread_id and interaction_id it belongs to. (Runtime v1 agents don’t emit this frame; their followup_suggestions ride on the message itself.) To resume a dropped stream without re-running the turn, reconnect with the last seq you saw:

await client.messaging.streamMessage({
  'Last-Event-ID': String(lastSeq),
  body: { user_id: 'end-user-123', text: '...', thread_id },
});

Rerun an interaction

Regenerate a previous interaction — with the original or edited text — on a new thread branched from the original. Both interaction_id and text are required:

const rerun = await client.messaging.rerun(threadId, {
  interaction_id: message.id,
  text: 'Actually, the charge was from June 1st',
  // version_id / version_tag: pin to a specific agent version
  // user_id, image_url: optional, as on sendMessage
});

console.log(rerun.thread_id); // the NEW thread the rerun created

Read a conversation

A thread lives on the runtime that created it, so the transcript read names that runtime — pass the runtime version your agent runs on as runtime_version (sending resolves it automatically; see Threads and runtime versions):

const messages = await client.messaging.listMessages(threadId, {
  runtime_version: '0.8.0',
});

Any value outside the 1.x family selects runtime v2 — it doesn’t have to match the thread’s exact build. Threads of runtime v1 agents take no selector: listMessages(threadId) reads them as is.

Traces

Every interaction’s reasoning trace — what the agent understood, which sources it relied on, what it decided. The shape follows the runtime the agent runs on, and trace.runtime says which one you got:

const page = await client.messaging.threadTrace(threadId);                             // one trace per interaction, oldest first
const trace = await client.messaging.interactionTrace(interactionId, { thread_id });   // thread_id: required for runtime v2 agents

if (trace.runtime === "v2") {
  trace.citations_used;   // the passages the reply provably cited — what to show as "sources"
  trace.did;              // the capabilities the turn carried out
  trace.narrative;        // the turn in plain sentences
} else {
  trace.decisions;        // runtime v1 agents: the typed decision list
}

Apollo.Trace is a discriminated union — Apollo.Trace.V1 (Apollo.RuntimeV1Trace with runtime: "v1") or Apollo.Trace.V2 (Apollo.RuntimeV2Trace with runtime: "v2") — so the if narrows it. The runtime v2 sections are typed too (Apollo.RuntimeTraceFact, Apollo.RuntimeTracePassage, and the sources, citations_used, decided, checks and answer item types under Apollo.RuntimeV2Trace).

Requires SDK 3.4.0 or later. Earlier versions type Trace as the runtime v1 shape only and don’t know include_trace or the thread_id argument.

With the reply, in one request. Set include_trace: true on sendMessage / streamMessage / rerun; the reply carries the same object as message.trace_info. Off by default — a trace can be large. On a stream it rides the final message event:

const { message } = await client.messaging.sendMessage({ user_id, text, include_trace: true });
message.trace_info;                                   // Apollo.Trace | undefined (null on the wire when not requested)

const stream = await client.messaging.streamMessage({ body: { user_id, text, thread_id, include_trace: true } });
for await (const event of stream) {
  if (event.type === "message") event.data.trace_info; // the completed reply's trace
}

Paging a long thread. threadTrace takes page[size], page[after] / page[before], and sort_by / sort_order in its second argument and returns { results, meta, links }:

let cursor: string | undefined;
do {
  const page = await client.messaging.threadTrace(threadId, { "page[size]": 20, "page[after]": cursor });
  page.results.forEach(render);
  cursor = page.meta.has_more ? page.meta.after_cursor : undefined;
} while (cursor);

Errors. A runtime v2 interaction read without thread_id throws Apollo.BadRequestError (the message says to pass it, or to use include_trace on the send); a thread that belongs to another agent than the key’s throws Apollo.NotFoundError. Both carry the standard error envelope in error.body.

Welcome message and follow-up suggestions

const { welcome_message } = await client.messaging.getWelcomeMessage();

// Agents with a dynamic welcome message accept placeholder values:
await client.messaging.getWelcomeMessage({
  placeholders: { customer_name: 'Ada' },
});

const { suggestions } = await client.messaging.generateFollowupSuggestions({
  context: { topic: 'order tracking' },
});

Called without a context, generateFollowupSuggestions returns the agent’s configured static suggestions.

Client context

After the first exchange (or an explicit getContext() call), the client knows which agent and organization its key resolves to:

const { agentId, organizationId, keyType } = await client.getContext();

// Also available as getters once resolved:
client.keyType;          // 'agent' | 'unknown'
client.agentId;
client.organizationId;

Channels (WhatsApp and SMS)

Start an outbound conversation on a channel with channels.initiateThread. Pass 'sms' or 'whatsapp' as the channel. phone_number is the recipient (who receives the opener). sender_id is not that phone number. It is the MongoDB ObjectId of a sender record you already connected in the Playground. If you connected a specific phone number through the Playground (SMS or WhatsApp), copy that sender’s ObjectId and pass it as sender_id. The SDK then starts the conversation from that connected number. Without sender_id, the platform default sender is used instead. The response includes from when a specific sender was used, so you can confirm which connected number the opener was sent from.

const thread = await client.channels.initiateThread('sms', {
  phone_number: '+14155551234', // recipient
  user_id: 'end-user-123',
  text: 'Hi! Your order has shipped.',
  // thread_id: existingThreadId,
  // MongoDB ObjectId of the specific number you connected in the Playground.
  // Pass it here to start the conversation from that number.
  sender_id: '67c1a2b3d4e5f67890123456',
});

console.log(thread.thread_id, thread.from);

WhatsApp is the same call. Template fields apply to WhatsApp only; text is used for SMS and ignored by WhatsApp.

const thread = await client.channels.initiateThread('whatsapp', {
  phone_number: '+14155551234', // recipient
  user_id: 'end-user-123',
  // Same Playground-connected sender ObjectId — starts WhatsApp from that number
  sender_id: '67c1a2b3d4e5f67890123456',
  agent_display_name: 'Support', // bound to template variable {{1}}
});

Method reference

Method	Description
`messaging.sendMessage(request)`	Send a message and return the reply.
`messaging.streamMessage(request)`	Send a message and stream the reply (SSE).
`messaging.rerun(threadId, request)`	Regenerate an interaction on a new thread.
`messaging.listMessages(threadId, request?)`	The thread’s full transcript — pass `runtime_version` (runtime v1 threads: none).
`messaging.threadTrace(threadId, request?)`	Every interaction’s reasoning trace (paginated). `trace.runtime` says which shape.
`messaging.interactionTrace(interactionId, request?)`	One interaction’s reasoning trace — pass `{ thread_id }` for runtime v2 agents.
`messaging.getWelcomeMessage(request?)`	The agent’s configured greeting; accepts `placeholders`.
`messaging.generateFollowupSuggestions(request)`	Suggested next prompts from a context (static suggestions without one).
`channels.initiateThread(channel, request)`	Start a WhatsApp/SMS conversation. Pass `sender_id` to send from a Playground-connected number.
`connect(args?)`	Open a WebSocket session (runtime v1 agents only).
`getContext()`	Resolve the key’s agent and organization (also on the `keyType`, `agentId`, `organizationId` getters).

Every method also accepts a final requestOptions argument (timeoutInSeconds, maxRetries, abortSignal, extra headers) — see Best practices.

​Send a message

​Stream a message

​Rerun an interaction

​Read a conversation

​Traces

​Welcome message and follow-up suggestions

​Client context

​Channels (WhatsApp and SMS)

​Method reference

Send a message

Stream a message

Rerun an interaction

Read a conversation

Traces

Welcome message and follow-up suggestions

Client context

Channels (WhatsApp and SMS)

Method reference