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.

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 per-message values for the agent’s configured context variables with agent_variables:

await client.messaging.sendMessage({
  user_id: 'end-user-123',
  text: 'Where is my order?',
  agent_variables: {
    static: { customer_name: 'Ada' },
    dynamic: { order_id: 'ORD-1042' },
  },
});

Stream a message

streamMessage returns the reply as an async-iterable stream of Server-Sent Events — token deltas while the agent works, then the complete message:

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
      process.stdout.write(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.suggestions);
      break;
  }
}

With v2 agents, ready-made follow-up prompts arrive automatically as the suggestions frame after the terminal message — render them as tappable chips, no extra call needed. 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
});

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

Read a conversation

const messages = await client.messaging.listMessages(threadId);   // full transcript
const traces = await client.messaging.threadTrace(threadId);      // one trace per interaction (v1 agents)
const trace = await client.messaging.interactionTrace(interactionId);

v2 agents: their threads live on the v2 runtime, so the transcript read takes the runtime_version selector — pass the runtime version your agent runs on (sending never needs it):

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

Traces (threadTrace, interactionTrace) are available for v1 agents only.

Welcome message and follow-up suggestions

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

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

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 AUI playground. If you connected a specific phone number through the AUI 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 AUI 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. v2 threads: pass `runtime_version`.
`messaging.threadTrace(threadId)`	Every interaction’s reasoning trace (paginated; v1 agents only).
`messaging.interactionTrace(interactionId)`	One interaction’s reasoning trace (v1 agents only).
`messaging.getWelcomeMessage()`	The agent’s configured greeting.
`messaging.generateFollowupSuggestions(request)`	Suggested next prompts from a context.
`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.
`getContext()`	Resolve the key’s agent and organization.

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

​Welcome message and follow-up suggestions

​Channels (WhatsApp and SMS)

​Method reference