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
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
Parameter Type Description 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 } ` );
Field Type Description 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' ],
},
});
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
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 } ` );
});
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://backend.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' ],
},
});
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.