Messaging Client

Send messages, stream replies, read conversations, and reach users on channels — with a publishable key.

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
}

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;
  }
}

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:

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
const trace = await client.messaging.interactionTrace(interactionId);

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 — pass 'whatsapp' or 'sms':

const thread = await client.channels.initiateThread('sms', {
  phone_number: '[phone]',
  user_id: 'end-user-123',
  text: 'Hi! Your order has shipped.',   // SMS only; WhatsApp uses your approved template
});

console.log(thread.thread_id);

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)	The thread’s full transcript.
messaging.threadTrace(threadId)	Every interaction’s reasoning trace.
messaging.interactionTrace(interactionId)	One interaction’s reasoning trace.
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.
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.