chat | SignalWire

Send a message and return the agent’s reply. One call is one full turn, including any tool calls the agent makes along the way, so expect seconds rather than milliseconds.

Parameters

conversationId

stringRequired

The conversation to send on.

message

stringRequired

The message to send.

options

ChatOptions

Turn options.

options.role

stringDefaults to user

user or system. A system message steers the agent without appearing as something the user said.

options.configUrl

string

Creates the conversation if it does not exist yet. Saves a call, at the cost of never receiving initialMessage, so the agent does not speak first.

options.userMetadata

Record<string, unknown>

Arbitrary data about the user, echoed back on this conversation’s webhooks. Sent as user_meta_data.

options.timeout

number

Applies only when this call creates the conversation.

options.reinit

booleanDefaults to false

Applies only when this call creates the conversation.

Returns

Promise<ChatResponse> — carries text, conversationId, and userEvent.

userEvent is null unless the turn produced one. Its contents are whatever your tool passed to swmlUserEvent(), so the shape is yours.

Throws

ChatInProgressError when a turn is already running on this conversation. That is the contract rather than a transient failure, so wait for the first turn to return instead of retrying.

Example

import { AIChatClient, ChatInProgressError } from '@signalwire/sdk';
const CONFIG_URL = 'https://bayview-taxi.example.com/swml';
const client = new AIChatClient({ space: 'your-space' });
await client.createConversation('chat-8f21', { configUrl: CONFIG_URL });
try {
  const reply = await client.chat(
    'chat-8f21',
    'How much is a van from 123 Gough Street to the airport?',
  );
  console.log('Ada:', reply.text);
  if (reply.userEvent) handle(reply.userEvent);
} catch (e) {
  if (e instanceof ChatInProgressError) {
    // a turn is already running; wait rather than retry
  } else {
    throw e;
  }
}