Skip to main content
The Conversations resource lets you access conversation data, retrieve messages, send responses, and manage user credits.

​
Overview

client.conversations.list(filters?)       // List conversations
client.conversations.get(id)              // Get a conversation
client.conversations.getMessages(id)      // Get messages
client.conversations.sendMessage(id, msg) // Send a message
client.conversations.sendTemplate(id, t)  // Send template message
client.conversations.trigger(id, input)   // Trigger bot response
client.conversations.setCredits(id, c)    // Set user credits

​
List Conversations

Retrieve conversations with optional filters. 
const conversations = await client.conversations.list({
  botId: 'agent-uuid',
  active: true,
});

conversations.forEach(conv => {
  console.log(`${conv.number}: ${conv.active ? 'active' : 'inactive'}`);
});

​
Filter Parameters

ParameterTypeDescription
botIdUUIDFilter by agent
userIdUUIDFilter by user
activebooleanFilter by active status
countryCodestringFilter by country
offsetnumberPagination offset
limitnumberPagination limit

​
Response Type

interface Conversation {
  id: UUID;
  active: boolean;
  context: Record<string, unknown>;
  memory: Record<string, unknown>;
  credits: number;
  chatWindowRemainingTime: number;
  number: string | null;
  
  bot: {
    id: UUID;
    name: string;
  };
  user: PublicUser | null;
  
  createdAt: string;
  updatedAt: string;
}

​
Get Conversation

Retrieve a single conversation. 
const conversation = await client.conversations.get(conversationId);

console.log(`Agent: ${conversation.bot.name}`);
console.log(`User: ${conversation.number}`);
console.log(`Credits remaining: ${conversation.credits}`);
console.log(`Memory:`, conversation.memory);

​
Get Messages

Retrieve all messages in a conversation. 
const messages = await client.conversations.getMessages(conversationId);

messages.forEach(msg => {
  const content = msg.text?.body || msg.image?.caption || '[media]';
  console.log(`[${msg.role}] ${content}`);
});

​
Message Type

interface Message {
  id: UUID;
  role: 'user' | 'assistant' | 'system';
  type: 'text' | 'image' | 'cta_button' | 'list_selection' | 'template';
  status: 'sent' | 'delivered' | 'read' | 'failed' | null;
  createdAt: string;
  thinkingSpace: string | null;
  
  // Content variants (only one present based on type)
  text: TextMessage | null;
  image: ImageMessage | null;
  ctaButton: CTAButtonMessage | null;
  listSelection: ListSelectionMessage | null;
  template: TemplateMessage | null;
}

interface TextMessage {
  id: UUID;
  body: string;
}

interface ImageMessage {
  id: UUID;
  image: ImageInfo | null;
  caption: string | null;
}

interface CTAButtonMessage {
  id: UUID;
  text: string;
  url: string | null;
  buttonText: string;
  image: ImageInfo | null;
  clicks: Array<{ id: UUID; createdAt: string }>;
}

​
Send Message

Send a text message to a conversation (as the agent). 
const message = await client.conversations.sendMessage(conversationId, {
  message: 'Hello! Thanks for reaching out. How can I help you today?',
});

console.log(`Sent message: ${message.id}`);

​
Input

FieldTypeDescription
messagestringThe text message to send
This sends a message as the agent, not as a user. Use this for manual interventions or human handoff scenarios.

​
Send Template Message

Send a WhatsApp-approved template message. 
const message = await client.conversations.sendTemplate(conversationId, {
  templateName: 'order_update',
  variables: {
    body: ['John', 'ORD-12345', 'shipped'],
    header: ['Order Update'],
    buttons: ['https://track.example.com/ORD-12345'],
  },
});

​
Input

interface SendTemplateInput {
  templateName: string;
  variables: {
    body?: string[];
    header?: string[];
    buttons?: string[];
  };
}
Template messages must be pre-approved by WhatsApp. Create templates in your WhatsApp Business Manager or via the API before using them.

​
Trigger Bot

Trigger the agent to respond with a custom prompt. 
await client.conversations.trigger(conversationId, {
  prompt: 'The user just completed a purchase. Send them a thank you message.',
});
This causes the agent to generate a response based on the prompt, without requiring a user message.

​
Use Cases

  • Proactive outreach after events
  • Scheduled check-ins
  • Follow-up messages
  • System-triggered notifications

​
Set Credits

Update the credit balance for a conversation. 
const updated = await client.conversations.setCredits(conversationId, {
  credits: 100,
});

console.log(`New balance: ${updated.credits}`);

​
Use Cases

  • Grant credits after purchase
  • Bonus credits for promotions
  • Manual adjustments

​
Working with Message Types

​
Text Messages

const messages = await client.conversations.getMessages(conversationId);

const textMessages = messages.filter(m => m.type === 'text');
textMessages.forEach(m => {
  console.log(m.text!.body);
});

​
Image Messages

const imageMessages = messages.filter(m => m.type === 'image');
imageMessages.forEach(m => {
  console.log(`Image: ${m.image!.image?.url}`);
  console.log(`Caption: ${m.image!.caption}`);
});

​
CTA Button Clicks

Track button engagement: 
const ctaMessages = messages.filter(m => m.type === 'cta_button');
ctaMessages.forEach(m => {
  console.log(`Button "${m.ctaButton!.buttonText}": ${m.ctaButton!.clicks.length} clicks`);
});

​
Complete Example

import { createWassistClient } from '@wassist/sdk';

const client = createWassistClient({
  baseUrl: 'https://api.wassist.app/api/v1/',
  authToken: process.env.WASSIST_TOKEN,
});

async function handleOrderWebhook(orderId: string, customerPhone: string) {
  // Find the customer's conversation
  const conversations = await client.conversations.list({
    botId: 'support-agent-uuid',
  });
  
  const customerConv = conversations.find(c => c.number === customerPhone);
  
  if (!customerConv) {
    console.log('No existing conversation found');
    return;
  }
  
  // Send order confirmation via template
  await client.conversations.sendTemplate(customerConv.id, {
    templateName: 'order_confirmation',
    variables: {
      body: [orderId, 'Processing', '3-5 business days'],
    },
  });
  
  // Grant bonus credits for the purchase
  await client.conversations.setCredits(customerConv.id, {
    credits: customerConv.credits + 50,
  });
  
  console.log(`Notified customer about order ${orderId}`);
}

async function analyzeConversation(conversationId: string) {
  const conversation = await client.conversations.get(conversationId);
  const messages = await client.conversations.getMessages(conversationId);
  
  console.log(`Conversation with ${conversation.number}`);
  console.log(`Agent: ${conversation.bot.name}`);
  console.log(`Total messages: ${messages.length}`);
  console.log(`Credits remaining: ${conversation.credits}`);
  
  // Count by role
  const byRole = messages.reduce((acc, m) => {
    acc[m.role] = (acc[m.role] || 0) + 1;
    return acc;
  }, {} as Record<string, number>);
  
  console.log(`User messages: ${byRole.user || 0}`);
  console.log(`Agent messages: ${byRole.assistant || 0}`);
  
  // Check message status
  const failed = messages.filter(m => m.status === 'failed');
  if (failed.length > 0) {
    console.log(`Failed messages: ${failed.length}`);
  }
}

Agents

Manage the agents behind conversations.

WhatsApp Accounts

Manage phone numbers and templates.